NEWS.md

In visPedigree: Tidying, Analysis, and Fast Visualization of Animal and Plant Pedigrees

Changes in version 1.8.1 released on 28 Mar 2026

New features

1. visped() generation labels: Added a new genlab argument to visped() for drawing generation labels (G1, G2, ...) on the left margin of pedigree plots. This helps identify each row in deep pedigrees. The default is FALSE, so existing plots are unchanged unless genlab = TRUE is requested.

Documentation

1. draw-pedigree vignette updated: Added a new example showing how to display generation labels with visped(..., genlab = TRUE).

Changes in version 1.8.0 released on 25 Mar 2026

Bug Fixes

1. tidyped() fast path with addnum = FALSE + cand: When the input tidyped object was created with addnum = FALSE (no IndNum/SireNum/ DamNum columns), passing a cand argument would always raise "None of the specified candidates were found in the pedigree." because the fast-path BFS looked up ped_dt$IndNum which was NULL. The fix temporarily adds integer index columns for the BFS and removes them from the output when addnum = FALSE.

2. pediv() / pedne() incorrect fg, MeanCoan, and NeCoancestry values when ECG was not pre-computed: Inside pediv() and pedne(), a merge(..., by = "Ind", all.x = TRUE) was used to attach ECG values. data.table::merge() sorts output by the key column (Ind, alphabetically), breaking the IndNum == row-index invariant that the fast-path BFS in tidyped() depends on. The result was that the traced pedigree used for coancestry calculation was incorrect, producing wildly wrong fg and related values (e.g., fg ≈ 240 instead of fg ≈ 19). Fixed by calling setorder(ped_dt, IndNum) immediately after the merge.

3. summary_pedmat() reported Density = 100% for all A, D, and AA matrices: The speed branch changed the return type of pedmat(sparse = TRUE) for these methods from dgCMatrix (sparse) to dgeMatrix (dense) to avoid the O(N²) zero-scan performed by Matrix::Matrix(..., sparse = TRUE). However, summary_pedmat() contained a hard-coded branch that returned sparsity = 1.0 for any non-sparseMatrix Matrix subclass (including dgeMatrix), always printing Density = 100% instead of the true fill ratio. Fixed by using Matrix::nnzero() / (nrow * ncol) for all Matrix subclasses; nnzero() works correctly for both dgeMatrix and dgCMatrix.

Performance

1. ~100× faster inbreeding calculation: Replaced the Meuwissen & Luo (1992) linear path-trace algorithm in cpp_calculate_inbreeding with the Sargolzaei & Iwaisaki (2005) LAP (Longest Ancestral Path) bucket method. At N = 1,000,000, the C++ kernel now completes in ~0.15 s (previously ~15 s), and the full inbreed() call returns in ~0.40 s. The key improvements are O(1) ancestor retrieval via bucket pop (vs. O(gap) linear scan), O(1) duplicate suppression via L[k] == 0 check, and O(m_i) path-coefficient reset (vs. O(k) full-array scan). All results are numerically identical to the previous implementation (max difference < 2 × 10⁻¹⁵).

2. ~16× faster tidyped() candidate tracing: When the input is already a tidyped object and cand is specified, the fast path now uses three new pure C++ BFS functions (cpp_trace_ancestors, cpp_trace_descendants, cpp_topo_order) instead of rebuilding an igraph object. At N = 1,000,000 with 200 candidates, elapsed time drops from ~0.91 s to ~0.056 s. The fast path now also correctly applies sibling and mate generation alignment for genmethod = "bottom", matching the output of the full path.

3. ~9× faster pedgenint() generation-interval lookup: Replaced the character-key data.table join used to look up each individual's generation number with a pre-computed integer index array. Benchmark on a representative dataset: 4.24 s → 0.49 s.

4. ~2× faster pedmat(sparse = TRUE) matrix coercion: The conversion from a dense numeric matrix to a Matrix::dgeMatrix now bypasses the S4 dispatch overhead of as(mat, "dgeMatrix") via a direct methods::new() call backed by a package-level class cache. The cached class object is looked up once per session instead of on every call. Benchmark: 1.24 s → 0.60 s for a representative subpedigree.

5. pedrel(compact = TRUE) 200 k safety guard: Added an early error when the number of reference individuals exceeds 200,000 in compact mode, preventing inadvertent multi-hour runs from silent O(N²) matrix allocation.

Internal changes

1. align_bottom_generations() extracted as shared helper: The ~60-line sibling/mate generation-alignment block previously duplicated between the main path and the fast path of tidyped() has been consolidated into a single internal helper. Both paths now call it consistently.

2. C++11 compatibility: Two C++17 structured-binding usages (auto [cur, d] = q.front()) in the BFS functions have been replaced with explicit C++11 equivalents, ensuring compatibility with GCC 8 (CRAN's minimum required compiler).

3. methods declared in Imports: The methods package is now explicitly listed under Imports in DESCRIPTION, as required by CRAN policy when methods::getClass() and methods::new() are called at runtime.

Documentation

1. Updated inbreed() and vignette references to cite Sargolzaei & Iwaisaki (2005) instead of Meuwissen & Luo (1992).

Changes in version 1.7.0 released on 23 Mar 2026

New features

1. pediv() retained genetic diversity (GeneDiv): pediv()$summary gains a new column GeneDiv = 1 - MeanCoan, the pedigree-based retained genetic diversity of the reference population. Values lie in $[0, 1]$; higher values indicate more diversity retained relative to an unrelated base population. print.pediv() displays it alongside fg and MeanCoan. This dimensionless complement to fg is easier to communicate to non-specialist stakeholders.

2. vismat() large-pedigree representative view: When the original pedigree has more than 5,000 individuals, vismat() no longer attempts a full N × N matrix expansion. Instead, it uses the compact matrix (K × K representative individuals) directly and adds sibling-count labels of the form ID (×n) to each axis tick. When compact = TRUE and by is supplied, the function now computes group means algebraically from the K × K matrix without expanding to N × N, eliminating memory overflow for very large pedigrees (e.g., N ≈ 178,000 in big_family_size_ped).

Internal changes

1. vismat() named threshold constants: Hardcoded magic numbers controlling large-pedigree behavior (5000, 2000, 50) have been refactored into named constants (VISMAT_EXPAND_MAX, VISMAT_LABEL_MAX, VISMAT_WARN_THRESHOLD) at the top of R/vismat.R for easier maintenance.

Changes in version 1.6.2 released on 23 Mar 2026

New features

1. pedrel() coancestry scale: Added a scale parameter to pedrel() supporting "relationship" (default, returns mean $a_{ij}$) and "coancestry" (returns corrected mean coancestry $\bar{c}$). The coancestry scale uses the diagonal-corrected formula of Caballero & Toro (2000), properly accounting for self-coancestry within the reference group.

API Changes

1. vispstat() internal downgrade: The vispstat() function has been downgraded to an internal-only function. Specifically, it is now the internal backend for plot.pedstats(). Users should use the standard plot(stats_obj) S3 method instead.
2. Standardized vispstat() documentation: Updated the documentation for generation intervals in vispstat() to accurately reflect the visualization of mean values (removing the misleading "± SD" claim).

Documentation

1. pedigree-analysis.Rmd §9 expanded: Section 9 ("Average Relationship Trends with pedrel()") split into two sub-sections to cover both scale options. Added §9.2 with the Caballero & Toro (2000) diagonal-corrected coancestry formula, a worked example using scale = "coancestry" (returning MeanCoan), and guidance on when to prefer each scale.
2. relationship-matrix.Rmd updated: Added §3.2 compact-to-vismat() direct path and expanded §4.1 with five sub-sections (reorder = FALSE, ids, by = "Gen", by = "Family", compact auto-expand). Replaced incorrect performance thresholds in §5 with an accurate reference table.

Bug fixes

1. Eliminated spurious subsetting warnings: Internal group-by slicing in pedrel(), pedne(), pediv(), pedhalflife(), and pedgenint() previously triggered false-positive [.tidyped] warnings ("Subsetting removed parent records..."). Fixed by using as.data.table() to bypass the completeness guard when the subset is only used for ID extraction, not for pedigree computation.
2. Eliminated internal class-restoration messages: pedrel(compact = TRUE) previously emitted "Note: 'ped' lost its tidyped class ... Restoring automatically." messages. Root cause was compact_ped_for_matrix() returning a plain data.table in its early-return branches (no full-sib families or no compactable members). Fixed by returning data.table::copy(ped) to preserve the tidyped class.
3. Internal cleanup: Removed dead code variables and added comprehensive unit tests for the genint branch of vispstat().

Changes in version 1.6.1 released on 21 Mar 2026

Improvements

1. Standardized diversity notation: Output columns in pedhalflife()$timeseries are now lowercase (fe, fa, fg, lnfe, lnfa, lnfg, lnfafe, lnfgfa) to maintain consistency with standard population genetics nomenclature.
2. Enhanced plot.pedhalflife() visualization: In type = "log" mode, the plot now includes an OLS regression line for total diversity decay ($\ln f_g \sim \text{Time}$) and a vertical reference line for the diversity half-life $T_{1/2}$.
3. Improved unit labeling: plot.pedhalflife() and print.pedhalflife() now automatically use the name of the timevar column (e.g., "Gen", "Year") for axis and summary labels.

Changes in version 1.6.0 released on 20 Mar 2026

New features

1. Information-theoretic diversity half-life (pedhalflife()): New function that tracks $f_e$, $f_a$, and $f_g$ across time points and fits a log-linear decay model to quantify the rate of genetic diversity loss. The total loss rate $\lambda_{total}$ is decomposed into three additive components: foundation bottleneck ($\lambda_e$, unequal founder contributions), breeding bottleneck ($\lambda_b$, overuse of key ancestors), and genetic drift ($\lambda_d$, random sampling loss). The diversity half-life $T_{1/2} = \ln 2 / \lambda_{total}$ is reported in units of the timevar column (e.g., generations, years). S3 print and plot methods are provided. The plot() method supports both log-scale (type = "log") and raw-scale (type = "raw") views of the decay trajectory.

Changes in version 1.5.0 released on 20 Mar 2026

New features

1. Shannon-entropy effective founders and ancestors (feH, faH): pedcontrib() and pediv() now compute two additional diversity statistics based on the Hill number of order $q=1$ (Shannon entropy):
2. feH — effective number of founders under equal entropy weighting. Satisfies the inequality $N_{\mathrm{Founder}} \ge f_e^H \ge f_e$.
3. faH — effective number of ancestors under equal entropy weighting. Satisfies the inequality $N_{\mathrm{Ancestor}} \ge f_a^H \ge f_a$. Both are computed from the vector of genetic contributions using the formula $\exp(-\sum p_i \ln p_i)$ and complement the classical quadratic ($q=2$) effective numbers $f_e$ and $f_a$ (Lacy 1989; Boichard et al. 1997). The new columns appear in pediv()$summary and pedcontrib()$summary alongside the existing fe, fa, and fg columns.

Changes in version 1.4.1 released on 15 Mar 2026

Bug fixes

1. Fail-fast incomplete pedigree analysis: inbreed() and other completeness-sensitive analysis functions now error on row-truncated subsets with missing parent records. This prevents incorrect results (e.g., zero inbreeding) caused by calculating on partial ancestry data.

Changes in version 1.4.0 released on 15 Mar 2026

New features

1. tidyped class redesign and optimization: Refined the internal tidyped class architecture around a clearer metadata contract and safer S3/data.table interaction model, making the object more robust for repeated downstream analysis and extension.
2. Safer tidyped object workflows: Added is_tidyped(), pedmeta(), has_inbreeding(), and has_candidates() to make class checks and metadata inspection explicit and user-facing.
3. Fast candidate tracing from existing tidyped objects: tidyped() now uses a fast path when the input is already a valid tidyped object and cand is supplied, avoiding repeated global validation and preprocessing.
4. Workflow coverage and developer documentation: Added a new workflow vignette, a tidyped structure and extension vignette, and focused regression tests covering safe subsetting, := by-reference behavior, and split workflow semantics.

Bug fixes

1. Stable by-reference mutation for tidyped: Replaced class and metadata attachment paths with data.table::setattr() so subsequent := operations keep true by-reference behavior instead of silently writing into shallow copies.
2. Safe row subsetting: Added [.tidyped interception so incomplete subsets degrade to plain data.table objects with a warning, while complete subsets preserve tidyped structure and rebuild pedigree indices correctly.
3. More robust class recovery: Core analysis entry points now cooperate with ensure_tidyped() / validate_tidyped() to recover valid tidyped objects after common class-dropping operations.

Documentation

1. Pkgdown article navigation: Reorganized vignette order, restored draw-pedigree to the recommended reading sequence, and exposed tidyped developer notes through a dedicated pkgdown developer-documentation entry.

Changes in version 1.3.5 released on 14 Mar 2026

New features

1. S3 Class Protection: Added as_tidyped() and an internal ensure_tidyped() mechanism to robustly handle the "silent class loss" bug. Standard R operations like merge(), rbind(), and dplyr verbs often strip custom S3 classes from data.table objects. Major analysis functions now automatically detect if the tidyped class is missing and restore it if the underlying data structure is intact, providing an informational message to the user instead of erroring.

Bug fixes

1. Robust Analysis Entry: Updated all 11 core analysis functions (including pedstats(), pedne(), pediv(), pedrel(), etc.) to use the new auto-recovery logic. This ensures that analysis remains user-friendly and reliable even after manual data manipulation by the user.

Changes in version 1.3.4 released on 14 Mar 2026

Bug fixes

1. data.table invisibility: Fixed a subtle but pervasive issue where functions returning data.table or tidyped objects (which are based on data.table) were returning them invisibly. This occurred because internal data.table operations like := and set* set an internal "invisible" flag. Affected functions included pedancestry(), pedpartial(), pedne(), pedrel(), tidyped(), and many others. All relevant functions now explicitly return the object using the [] syntax to ensure they auto-print correctly in the R console and knitted documents.
2. Side-effect prevention: Updated calc_ne_demographic() to operate on a copy of the input pedigree instead of modifying the user's data by reference.

Documentation

1. Positron Guide: Added a new coding standard to Positron.md regarding data.table return visibility to prevent regressive "invisible output" bugs in future development.

Changes in version 1.3.3 released on 14 Mar 2026

Documentation

1. pedigree-analysis.Rmd rewrite: Reorganized the main pedigree analysis vignette into clearer thematic sections covering pedigree overview, pedigree completeness (pedecg()), generation intervals (pedgenint()), subpopulation structure (pedsubpop()), diversity indicators (pediv()), effective population size (pedne()), average relationship trends (pedrel()), inbreeding classification (pedfclass()), and ancestry / partial inbreeding diagnostics.
2. Theory expansion: Added core formulas, interpretation notes, and breeding-use explanations for Equivalent Complete Generations (ECG), generation intervals, effective numbers of founders / ancestors / founder genomes (f_e, f_a, f_g), three effective population size definitions (N_e by demographic, inbreeding, and coancestry methods), and average additive relationship (MeanRel).
3. Reference update: Expanded the vignette bibliography to include the key classical references underlying the package's diversity and effective population size metrics, including Wright (1922, 1931), Lacy (1989), Boichard et al. (1997), Caballero & Toro (2000), Cervantes et al. (2011), and Gutiérrez et al. (2008, 2009).

Bug fixes

1. Vignette API synchronization: Replaced outdated pedinbreed_class() calls in the pedigree analysis vignette with the current pedfclass() interface and aligned all examples with the current reference, foundervar, and cycle argument names.

Testing

1. Analysis regression coverage: Added focused unit tests to verify that pedancestry() proportions sum to 1 in a multi-line admixture pedigree and that pedrel() returns identical results between compact = TRUE and compact = FALSE modes on the same pedigree.

Changes in version 1.3.2 released on 13 Mar 2026

New features

1. Added Comprehensive Examples: Added @examples to core analysis functions pedne(), pedecg(), and pedsubpop() to improve documentation completeness and provide immediate value to users.
2. Pedigree Connectivity Analysis (pedsubpop): Enhanced pedsubpop() to better distinguish between pedigree splitting (via splitped) and grouping/summary analysis. It now provides clear counts of total individuals, sires, dams, and founders within subgroups or connected components.

API Changes

1. pedfclass() rename: Renamed the inbreeding-class summary helper from pedinbreedclass() to pedfclass() to align with the package naming guide and provide a shorter, clearer user-facing API.
2. pedfclass() output refinement: Renamed the returned class column from F_Class to FClass, and added support for user-defined inbreeding class breakpoints through the breaks and labels arguments.
3. pedgenint() parameter rename: Renamed cycle_length to cycle for consistency with the package naming guide.
4. pedgenint() / pedstats() unit parameter: Removed "gen" from unit options. The unit parameter now only accepts "year", "month", "day", or "hour". The previous "gen" option produced incorrect results when combined with date inputs.
5. pedgenint() timevar definition: Clarified timevar as a birth date column. Numeric year inputs (e.g., 2020) are now automatically converted to Date ("YYYY-07-01") with an informational message. Character date strings are parsed via as.POSIXct() with tz = "UTC" to avoid DST artifacts.

Minor improvements and bug fixes

1. Documentation Audit: Refined internal documentation for pedsubpop() to clarify its use cases alongside splitped().
2. vispstat() pathway filter fix: Fixed an issue where the generation-interval bar chart could silently drop pathways due to an overly broad factor() filter. Now uses explicit %in% c("SS", "SD", "DS", "DD") subsetting.
3. .parse_to_numeric_time() rewrite: Completely rewrote the internal time parser to handle Date, POSIXct, character date strings, and numeric years robustly. All POSIXct conversions now use tz = "UTC" to prevent DST-related artifacts.

Changes in version 1.3.1 released on 12 Mar 2026

New features

1. Added the selfing argument to tidyped() to support plant and aquaculture pedigrees where an individual can appear as both Sire and Dam, resolving biologically impossible sex conflict errors (#10).
2. pedrel() logic upgrade: Modified pedrel() to use full ancestral tracing via tidyped(ped, cand = ...) when calculating sub-group relationships. This ensures that relationships in deep-inbred populations (e.g., full-sib mating over multiple generations) are calculated correctly rather than being underestimated due to ancestor truncation.

API Changes

1. pedancestry() parameter rename: Renamed labelvar to foundervar and labels to target_labels to align with the package naming guide and make the ancestry-tracing interface more explicit. Old argument names are no longer supported because this function is still under active development.
2. pedecg() parameter cleanup: Removed the short-lived reference argument. It only filtered rows after a full ECG pass and did not define a true reference population or prune the pedigree before calculation. Users should subset the returned table directly if needed.

Minor improvements and bug fixes

1. Academic nomenclature alignment: Updated documentation for pedrel() and pedne() to explicitly distinguish between Additive Genetic Relationship ($a_{ij}$) and Coancestry ($f_{ij}$).
   • pedrel() now clearly states it returns $a_{ij} = 2f_{ij}$.
   • pedne() documentation now specifies that its "coancestry" method is based on $f_{ij}$.
2. Individuals acting as both parents are now identified as "monoecious" in the Sex column.
3. visped() now uses a distinct teal color (#26a69a) to render "monoecious" individuals, ensuring clear visual separation from males, females, and highlighted nodes.
4. Pedigree edges are now colored based on the parent's role in a specific mating (Sire blue, Dam gold, Selfing teal) rather than invariant node sex, allowing monoecious individuals to display role-appropriate connection colors.
5. summary() and print() methods for tidyped objects now accurately report the count and percentage of monoecious individuals.
6. Efficiency Optimization: Optimized pedancestry() initialization on large pedigrees by using vectorized matrix indexing, significantly reducing overhead for pedigrees with >25k nodes.
7. Added a new unit test for pedrel() to verify correct relationship calculation in deep-inbreeding scenarios (Gen 4 relationships reaching 1.0).

Changes in version 1.3.0 released on 10 Mar 2026

New Features

1. Founder Genome Equivalents ($f_g$): Integrated the robust calculation of Founder Genome Equivalents into pediv(). It directly evaluates the mean coancestry while properly correcting for diagonal intra-cohort elements through adaptive scaling, keeping computational costs linear relative to the reference cohort size.
2. Reproducible Parameter Inference: Added a seed argument to both pedne() and pediv() functions functions enabling precise reproducible sampling for effective population size estimations (Ne) and $f_g$ computations using Monte Carlo approximations.

Changes in version 1.2.3 released on 08 Mar 2026

Bug Fixes

1. Trace edge highlighting in visped(): Fixed incorrect edge highlighting when using trace = "all". Previously, when a node was highlighted as both an ancestor (via upward tracing) and a parent of descendants (via downward tracing), the cross-path edges were incorrectly highlighted. For example, visped(tp, highlight = "X", trace = "all") would incorrectly highlight the edge from N to Z1/Z2, even though that parent-child relationship is not on X's trace path. The fix separates the up and down trace paths and uses trace_edges to precisely control which edges are highlighted.
2. Focal node upward edge in trace = "down": Fixed an issue where the focal node's upward connection to its parents' family node was incorrectly shown as highlighted when tracing downward only. For example, visped(tp, highlight = "X", trace = "down") would show X's edge to the UxV family node in solid black, even though X's ancestors are not part of the downward trace. Now, individual → family edges are only highlighted when the individual appears as a child in the traced path.

Changes in version 1.2.2 released on 08 Mar 2026

New Features

1. Unified Diversity Analysis (pediv): Added pediv() as a single entry-point wrapper that aggregates founder contributions ($f_e$), ancestor contributions ($f_a$), and all three Ne estimates (coancestry, inbreeding, demographic) into one consolidated pediv S3 object. A dedicated print.pediv() method provides a formatted summary table.
2. New Dataset (complex_ped): Added complex_ped, a multi-generation pedigree dataset suitable for testing deeper ancestry tracing and cross-generation diversity analyses.

API Changes

1. Parameter Rename (cand → reference): Standardized the reference population parameter name across all relevant analysis functions:

   • pedne(... , reference = NULL) (previously cand)
   • pedcontrib(... , reference = NULL) (previously cand)
   • pedrel(... , reference = NULL) (previously cand)

   The new name better reflects population genetics terminology, where the target group is the reference population rather than a set of "candidates". (Note: Old cand argument is no longer supported; please update existing scripts.)

Documentation

1. Vignette Rewrite (pedigree-analysis.Rmd): Completely restructured the pedigree analysis vignette with expanded theory explanations for $f_e$, $f_a$, and Ne, updated code examples using pediv() and the new reference parameter, and improved narrative linking the statistical outputs to practical breeding decisions.
2. Workspace Reorganization: Moved development-only files (MACOS_OPENMP_FIX.md, manuscript.md, analysis scripts) into sandbox/ to keep the package root clean. Added corresponding .gitignore and .Rbuildignore rules.

Changes in version 1.2.1 released on 07 Mar 2026

New Features

1. Ancestral Analysis (pedcontrib): Added robust algorithms for assessing genetic diversity through gene origin probabilities. Computes the effective number of founders ($f_e$) via recursive gene derivation and the effective number of ancestors ($f_a$) via Boichard's iterative algorithm.
2. Missing Parent Conservation ("Phantom Parents"): Implemented correct probability mass conservation. In pedcontrib, single missing parents (half-founders) are seamlessly augmented with temporary "phantom parents" before processing, overcoming the critical issue of gene probability leakage found in earlier tools.
3. Ancestry Proportions (pedancestry): Added pedancestry() function to trace line origins and monitor the surviving proportion of genes from specified historic founder lines or strains down to modern descendants.
4. Partial Inbreeding (pedpartial): Engineered the Meuwissen & Luo (1992) based partial inbreeding decomposition pedpartial(). Enables breaking down the overall inbreeding coefficient into discrete fractions attributed to specifically targeted ancestors.
5. New Dataset (half_founder_ped): Added empirical ENDOG dataset containing instances of strictly missing single parents (sire known, dam unknown, etc.) specifically engineered to test and validate phantom-parent corrections.

Performance

1. Peeling Core Engine: Rebuilt the C++ core array engine backing the $f_a$ and $f_e$ calculations. Execution latency for incredibly massive and deep graphs (>180,000 nodes) was resolved, avoiding hanging scenarios by limiting computational bounds optimally inside $O(K \times N)$ array states.

Documentation

1. Analysis Indexing: Expanded _pkgdown.yml configuration mapping to fully expose all newly engineered high-level pedigree statistical functions (pedancestry, pedcontrib, pedpartial, pedecg, etc.) within the main Reference documentation.
2. Analysis Vignettes: Updated vignettes/pedigree-analysis.Rmd carefully illustrating Boichard's genetic bottleneck interpretations ($f_e$ vs $f_a$) alongside new code examples for tracing targeted lineage flows.

Changes in version 1.2.0 released on 04 Mar 2026

New Features

1. Enhanced Effective Population Size (Ne) Calculation:
   • The pedne() function has been significantly expanded and now supports three robust methods for estimating Ne in breeding populations:
     • coancestry (New Default): Based on the rate of coancestry ($\Delta c$). This method captures the loss of genetic potential and is considered the "gold standard" for populations under selection pressure. It typically yields a smaller, more conservative Ne estimate than inbreeding-based methods, providing a better early warning signal for genetic diversity loss.
     • inbreeding: Based on the individual rate of inbreeding ($\Delta F$). This method reflects the realized inbreeding but may overestimate Ne in managed populations where mating between relatives is actively avoided.
     • demographic: A census-based method using the number of breeding males ($N_m$) and females ($N_f$).
2. Parallel Processing Support:
   • Introduced OpenMP multi-threading for the computationally intensive coancestry method. Users can now specify ncores to speed up large-scale matrix calculations.
   • Added a nsamples parameter to allow efficient estimation on massive pedigrees by sampling subsets of each cohort.

Performance

1. C++ Optimization:
   • Implemented a high-performance C++ backend (cpp_calculate_sampled_coancestry_delta) using RcppArmadillo. This replaces the previous R-based logic for coancestry calculations, enabling the analysis of much larger datasets.

Documentation

1. Clarified Parameter Scopes: Updated documentation for pedne() to explicitly state that ncores and nsamples parameters are specific to the method = "coancestry" calculation path.
2. Method Descriptions: Expanded details on the three Ne calculation methods to help users choose the most appropriate metric for their breeding program.

Changes in version 1.1.1 released on 02 Mar 2026

New Features

1. pedgenint Sex-Independent Pathways: Added evaluation of SO (Sire-to-Offspring) and DO (Dam-to-Offspring) generation intervals alongside the standard 4 pathways. This is especially useful for aquatic species (like shrimp) or early-stage screening where offspring sex might remain unknown.

API Changes and Refactoring

1. pedne Interface Standardization:
   • Renamed arguments timevar to by, and cohort to cand to harmonize parameter naming conventions across the package.
   • Removed unused and misleading parameters (unit, cycle_length, maxgen). The effective population size Ne calculation innately depends on Equivalent Complete Generations (ECG), making it independent of scalar temporal units.
2. vismat Parameter Alignment: Renamed grouping argument to by to maintain grouping consistency. (Note: Old arguments timevar, cohort in pedne() and grouping in vismat() are retained for backward compatibility but will display a deprecation warning.)

Bug fixes

1. pedrel Correctness: Fixed a critical calculation bug in pedrel() where the mean average relatedness calculation erroneously divided the sum of the full relationship matrix (including all traced ancestors) by only the size of the target subgroup. It now cleanly subsets the relationship matrix, and correctly handles boundary limits (NUsed < 2). The output columns N and MeanRel behavior has been replaced with NTotal, NUsed, and MeanRel.
2. pedgenint Aggregation: Fixed pedgenint() to output appropriate unweighted mixture standard deviation for generating generation intervals alongside its unweighted 4-pathway average interval estimate.
3. pedgenint Sample Size (N): Fixed an issue where the Average pathway N was severely underestimated. It now accurately evaluates all parent-offspring pairs via calc_all_pathway().
4. pedcontrib Accuracy: Standardized effective founders (Ne_f) and effective ancestors (Ne_a) calculation in pedcontrib() to ensure they are calculated based upon the full un-truncated cohort before outputting strictly the top n-ranked figures. Results list has been augmented with variables tracking the _total and _reported count values.
5. pedcontrib Deep Pedigree Latency: Replaced a string-named vector backward pass with a pure integer-indexed backward pass, resolving instances where evaluating contributions on deep, large pedigrees (e.g., > 200,000 records) would hang indefinitely due to scaling constraints.
6. pedpartial / pedancestry Input Compatibility: Ensured missing numeric identifiers in incoming pedigrees (e.g. addnum = FALSE) do not break pedpartial() or pedancestry(). Increased performance of the pedigree propagation loop in pedancestry by dropping an internal array linear probe algorithm with an immediate linear vector lookup.
7. pedne Performance bottleneck: Removed an obsolete O(N^2) individual traversal evaluation (calc_ancestral_f()), streamlining calculation purely around the efficient direct formula by Gutiérrez et al.

Changes in version 1.1.0 released on 01 Mar 2026

New Features

1. Pedigree Analysis Module: Introduced a comprehensive suite of pedigree analysis and population genetics tools.
   • pedstats(): Calculate holistic and demographic statistics.
   • pedrel(): Formulate average relatedness within specific population groupings.
   • pedgenint(): Compute distinct breeding pathways (SS, SD, DS, DD) and overall population generation intervals.
   • pedcontrib(): Determine genetic contributions from founders (Ne_f) and prominent ancestors (Ne_a) utilizing iterative gene flow derivations.
   • pedancestry(): Establish proportionality of ancestral lineages on subsequent descendants.
   • pedpartial(): Decompose inbreeding mechanisms to detect fractional/partial origins from core ancestors.
2. Pedigree Analysis Visualization: Added vispstat() to intuitively render bar charts of generation intervals and histogram distributions detailing depth tracking factors (like Equivalent Complete Generations).

Changes in version 1.0.1 released on 31 Jan 2026

Bug fixes

1. Compact Matrix Correctness: Fixed a critical data integrity bug in compact = TRUE mode where relationship values (A, D, AA) were incorrect for parent-offspring and avuncular pairs due to improper merging of parent individuals with their non-parent siblings.
2. Pedigree Compression Strategy: Updated compaction logic to preserve original genetic identity of any individual that appears as a sire or dam, ensuring parents always have unique entries in the relationship matrix.
3. Sibling Row/Column Expansion: Fixed expand_pedmat() to correctly handle sibling off-diagonal elements by dynamically calculating relationship values based on parent kinship, rather than simply duplicating representative diagonal values.
4. Generation Alignment Logic: Fixed tidyped(..., genmethod = "bottom") to prioritize Sibling Consistency (P1) over Mate Alignment (P2). This ensures that full siblings are always aligned to the same generation.
5. visped() edge highlighting: Fixed edge highlighting logic so relationship edges are only emphasized when trace is used.
6. Shared-parent/shared-child paths: Corrected edge highlighting for cases where a parent has multiple families or a family has multiple children.
7. visped() layout: Fixed layout optimization failure when showf = TRUE. The layout algorithm now correctly uses immutable individual IDs.

Changes in version 1.0.0 released on 24 Jan 2026

API Standardization (BREAKING)

To provide a clean and intuitive API for v1.0.0, core function names and behaviors have been standardized: - pedmatrix is renamed to pedmat. - pedmat default method is now "A" (Additive Relationship Matrix). Previously it was "f" (Inbreeding Coefficients). - expand_pedmatrix is renamed to expand_pedmat. - summary_pedmatrix is renamed to summary_pedmat. - The parameter n_threads is standardized to threads across all functions. - Legacy function names (pedmatrix, etc.) have been removed. Please use pedmat() directly.

New Features

1. Family Assignment and Summary:
   • tidyped() now automatically assigns and includes a Family column, identifying full-sib groups.
   • summary.tidyped() has been updated to provide family statistics (count, sizes, top largest families) and richer offspring analysis.
2. Pedigree Splitting (splitped): Added splitped() function to detect and split disconnected pedigree components. It efficiently identifies independent sub-populations (connected components) using graph theory, excludes isolated individuals, and returns a list of re-indexed tidyped objects ready for separate analysis or visualization.
3. Comprehensive Matrix Support: pedmat() (formerly pedmatrix) now fully supports 6 types of genetic relationship matrices: Additive (A, Ainv), Dominance (D, Dinv), and Additive-by-Additive Epistatic (AA, AAinv).
4. Relationship Matrix Visualization (vismat): Added vismat() function for visualizing relationship matrices (A, D, AA, etc.) with heatmaps and histograms. It supports pedmat objects, tidyped objects (auto-calculates A matrix), and standard matrices. Heatmaps can be annotated with family groups when a pedigree is provided.

CRAN Submission & Internal Improvements

This release marks the first stable version 1.0.0, polished for CRAN.

1. Portable Compilation: Standardized src/Makevars for cross-platform compatibility (removed GNU/platform-specific extensions).
2. Dependencies: Moved RcppArmadillo to LinkingTo to optimize package structure.
3. Documentation & S3: Fixed vignette generation, resolved diag S3 method dispatch, and cleaned up documentation for CRAN compliance.

Changes in version 0.7.3 released on 13 Jan 2026

New behavior (BREAKING)

1. Simplified pedmatrix() return and single-method enforcement: pedmatrix() now requires a single method argument (e.g., method = "A"). When a single method is requested, the function returns the corresponding matrix or vector directly (not a named list). Requesting multiple methods in one call will now raise an error. Use repeated calls for multiple outputs.

New features

1. High-Performance Genetic Relationship Calculations: Introduced pedmatrix() function implemented in Rcpp for efficient computation of:
   • Additive relationship matrix (A) using the tabular recursive algorithm.
   • Sparse inverse additive matrix (A-Inverse) using Henderson's rules.
   • Dominance matrix (D) using the tabular approach.
   • Inbreeding coefficients (f) using the Meuwissen & Luo (1992) path-tracing algorithm.

Improvements

1. Default Inbreeding Calculation Method: The inbreed() function now uses the native Rcpp implementation by default, moving the nadiv package to Suggests.
2. Documentation and Website: Updated package documentation and vignettes to reflect new features and improvements. The official package website is available at https://luansheng.github.io/visPedigree/.

Changes in version 0.7.2 released on 12 Jan 2026

New features

1. Flexible Generation Assignment: Added genmethod parameter to tidyped(). Users can now choose between "top" (top-aligned, default) and "bottom" (bottom-aligned) methods for generation inference.
   • The "top" method aligns founders at Generation 1, which is more appropriate for biological pedigrees and prevents "founder drift" in pedigrees with varying depths.
   • The "bottom" method aligns terminal nodes at the bottom, useful for visualizing introductions of unrelated exogenous parents.

Improvements

1. Default Logic Change: Switched the default generation assignment method to "top" (top-down) for more intuitive biological visualization.
2. Pkgdown Documentation: Generated and published the official package website at https://luansheng.github.io/visPedigree/.
3. Automated CI/CD: Added GitHub Actions workflow for automatic documentation updates and deployment via GitHub Pages.

Changes in version 0.7.1 released on 11 Jan 2026

Performance optimizations

1. Large Pedigree Performance: Optimized visped performance for displaying large pedigrees through efficient attribute handling and vectorized rendering. Computation time for 100k+ individuals reduced significantly by avoiding redundant igraph attribute lookups.
2. Vectorized Tracing: Refactored trace_ped_candidates in tidyped to use vectorized igraph::neighborhood calls, achieving ~150x speedup for large candidate lists (e.g., 37k candidates in a 178k individual pedigree traced in ~1.2s).
3. Early Filtering: Implemented unified early filtering of isolated individuals (Gen 0) in prepare_ped_graph to streamline downstream graph conversion and layout algorithms.

Improvements

1. User Feedback: Standardized filtering notifications. The message "Note: Removed N isolated individuals..." now appears consistently for all pedigree sizes when Gen 0 individuals are present.
2. Refined Tracing: Corrected trace = "all" logic in both tidyped and visped. It now correctly retrieves the union of ancestors and descendants ("up" + "down") instead of the entire connected component (undirected search).

Changes in version 0.7.0 released on 10 Jan 2026

Breaking changes & Major Refactoring

1. Graph-based tidyped Core: Reimplemented the pedigree tidying engine using formal graph theory principles (Directed Acyclic Graphs). Improved loop detection and generation inference accuracy using topological sorting.
2. Modular Architecture: Split the monolithic visped.R into functional modules: visped_layout.R, visped_graph.R, visped_style.R, and visped_render.R for better maintainability.

New features

1. New Parameters in visped():
   • pagewidth: Allows users to specify the PDF page width (default 200 inches) to accommodate different pedigree scales.
   • symbolsize: A scaling factor (default 1) to adjust node sizes relative to label dimensions, providing finer control over whitespace.
2. Two-Pass Rendering Engine: Introduced a two-pass strategy in plot_ped_igraph() to ensure edges connect exactly at node centers, eliminating visual gaps in vector PDF outputs.
3. Enhanced Highlighting: Added support for real-time ancestry and descendant highlighting via the trace parameter in visped().

Bug fixes

1. Fixed rendering failure in outline = TRUE mode by correcting attribute indexing in the graph object.
2. modernized the unit testing suite to testthat 3rd edition, removing all legacy context() warnings.
3. Improved coordinate calculation precision to prevent overlapping in high-density generations.

Changes in version 0.6.2 released on 01 Jan 2026

New features

1. Added summary() method for tidyped objects to provide quick pedigree statistics (number of individuals, founders, sex distribution, etc.).

Bug fixes

1. Fixed an issue where tidyped(..., inbreed=TRUE) failed due to incorrect class assignment order.
2. Fixed visped(..., showf=TRUE) to gracefully handle missing f columns by warning the user instead of erroring.
3. Fixed broken internal navigation links in package vignettes.

Changes in version 0.6.1 released on 30 Dec 2025

New features

1. Implemented opaque highlighting effects for better visualization clarity.
2. Added trace option to visped() to control ancestry tracing direction.

Changes in version 0.6.0 released on 28 Dec 2025

New features

1. Implemented strict S3 class structure for tidyped objects with new_tidyped() constructor and validate_tidyped() validator to ensure data integrity.

Changes in version 0.5.0 released on 26 Dec 2025

New features

1. Added highlight parameter to visped() function. Users can now highlight specific individuals using a character vector of IDs or a list for custom colors.
2. Added showf parameter to visped() function to display inbreeding coefficients on the pedigree graph.
3. Added inbreed parameter to tidyped() function to calculate inbreeding coefficients using the nadiv package.
4. Refactored inbreed() function as a standalone tool that operates on tidyped objects.
5. Optimized repeloverlap() function using data.table for significantly better performance.

Bug fixes

1. Fixed a critical crash in visped() when combining compact = TRUE, highlight, and showf = TRUE by refactoring ped2igraph() to delay label modification until after layout calculation.
2. Fixed documentation grammar and phrasing across all functions for CRAN compliance.
3. Fixed R CMD check notes related to data.table non-standard evaluation by adding R/globals.R.

Changes in version 0.4.1 released on 25 Dec 2025

Bug fixes

1. Fixed overlapping edge detection for small pedigree graphs.
2. Improved coloring consistency for compact mode.

Changes in version 0.2.6 released on 31 Mar 2020

Bug fixes

1. Fixed a bug that the number of generations for candidates would be traced to n+1 when tracegen=n. This bug is found by Mianyu Liu.

Changes in version 0.2.5 released on 25 Feb 2020

Bug fixes

1. The tidyped() does not work with trace='all' in certain cases

Changes in version 0.2.4.1 released on 24 Feb 2020

Bug fixes

1. An unexpected column with the name as NA occured when a tidyped object is tidyed again using the tidyped()

Changes in version 0.2.4 released on 12 June 2019

Bug fixes

1. The data.table used as the input parameter 'ped' may be changed in tidyped() and visped().

Changes in version 0.2.3 released on 05 Mar 2019

Bug fixes

1. The generation number of individuals is not inferred rightly.

Changes in version 0.2.2 released on 28 Jan 2019

Bug fixes

1. The tidied pedigree will not include the candidates which are not in the Ind column of the origin pedigree when the cand parameter is not NULL.

Changes in version 0.2.1 released on 17 Nov 2018

Bug fixes

1. Repel the overlapping nodes due to very small differences (digits > 7) among x positions of nodes

visPedigree documentation built on March 30, 2026, 9:07 a.m.