% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pedanalysis.R
\name{pedrel}
\alias{pedrel}
\title{Calculate Mean Relationship or Coancestry Within Groups}
\usage{
pedrel(
  ped,
  by = "Gen",
  reference = NULL,
  compact = FALSE,
  scale = c("relationship", "coancestry")
)
}
\arguments{
\item{ped}{A \code{tidyped} object.}

\item{by}{Character. The column name to group by (e.g., "Year", "Breed", "Generation").}

\item{reference}{Character vector. An optional vector of reference individual IDs to calculate
relationships for. If provided, only individuals matching these IDs in each group
will be used. Default is NULL (use all individuals in the group).}

\item{compact}{Logical. Retained for backward compatibility. It is ignored
because \code{pedrel()} now uses matrix-free pedigree products for all
calculations.}

\item{scale}{Character. One of \code{"relationship"} or \code{"coancestry"}.
\code{"relationship"} returns the pairwise off-diagonal mean additive
relationship (current \code{pedrel()} behavior). \code{"coancestry"}
returns the corrected population mean coancestry used for pedigree-based
diversity calculations.}
}
\value{
A \code{data.table} with columns:
\itemize{
  \item A grouping identifier column, named after the \code{by} parameter (e.g., \code{Gen}, \code{Year}).
  \item \code{NTotal}: Total number of individuals in the group.
  \item \code{NUsed}: Number of individuals used in calculation (could be subset by reference).
  \item \code{MeanRel}: Present when \code{scale = "relationship"}; average of off-diagonal
    elements in the Additive Relationship (A) matrix for this group
    (\eqn{a_{ij} = 2f_{ij}}).
  \item \code{MeanCoan}: Present when \code{scale = "coancestry"}; diagonal-corrected
    population mean coancestry for this group.
  \item \code{Status}: \code{"ok"}, \code{"skipped"}, or \code{"failed"}.
  \item \code{Message}: Empty for successful groups; otherwise a diagnostic
    explaining why \code{NA} was returned.
}
}
\description{
Computes either the average pairwise additive genetic relationship
coefficients (\eqn{a_{ij}}) within cohorts, or the corrected population mean
coancestry used for pedigree-based diversity summaries.
}
\details{
Let \eqn{g} be a zero-one indicator vector for the \eqn{N} selected
individuals and let \eqn{S = g^\prime A g}. When
\code{scale = "relationship"}, the returned value is
\deqn{\bar{a}_{off} =
  \frac{S - \sum_{i:g_i=1}(1 + F_i)}{N(N - 1)},}
the mean of the off-diagonal additive relationship coefficients. When
\code{scale = "coancestry"}, the returned value is
\deqn{\bar{C} = \frac{S}{2N^2},}
which includes both pairwise coancestry and diagonal self-coancestry. This
is equivalent to
\deqn{\bar{C} = \frac{N - 1}{N} \cdot
  \frac{\bar{a}_{off}}{2} + \frac{1 + \bar{F}}{2N}.}
The implementation computes \eqn{A g} directly from the pedigree and does
not construct the dense relationship matrix \eqn{A}.
}
\examples{
\donttest{
library(data.table)
# Use the sample dataset and simulate a birth year
tp <- tidyped(small_ped)
tp$Year <- 2010 + tp$Gen

# Example 1: Calculate average relationship grouped by Generation (default)
rel_by_gen <- pedrel(tp, by = "Gen")
print(rel_by_gen)

# Example 2: Calculate average relationship grouped by Year
rel_by_year <- pedrel(tp, by = "Year")
print(rel_by_year)

# Example 3: Calculate corrected mean coancestry
coan_by_gen <- pedrel(tp, by = "Gen", scale = "coancestry")
print(coan_by_gen)

# Example 4: Filter calculations with a reference list in a chosen group
candidates <- c("N", "O", "P", "Q", "T", "U", "V", "X", "Y")
rel_subset <- pedrel(tp, by = "Gen", reference = candidates)
print(rel_subset)
}

}
