Package {tidygedcom}

Type:	Package
Title:	Read and Tidy 'GEDCOM' Genealogy Files
Version:	0.2.0
Description:	Reads and parses 'GEDCOM' (Genealogical Data Communication) files, the standard interchange format exported by genealogical software, and converts them into tidy data frames. Individuals, families, life events, and parent-child links are extracted into rectangular structures suitable for pedigree and kinship analysis. Additional helpers summarize file contents, convert place coordinates, and repair malformed records. Wikipedia family tree templates can be parsed into the same tidy structure. For a discussion of these and related data structures see [Hunter et al. (2026) <doi:10.1007/s10519-026-10259-z>].
License:	GPL-3
URL:	https://github.com/R-Computing-Lab/tidygedcom/, https://r-computing-lab.github.io/tidygedcom/
BugReports:	https://github.com/R-Computing-Lab/tidygedcom/issues
Depends:	R (≥ 3.5.0)
Imports:	BGmisc, dplyr, igraph, purrr, rlang, stringr, tidyr
Suggests:	discord, EasyMx, ggpedigree, ggplot2, kinship2, knitr, OpenMx, rmarkdown, testthat (≥ 3.0.0), tidyverse, withr
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-08-21 20:28:00 UTC; smaso
Author:	S. Mason Garrison [aut, cre, cph], Christian Waugh [aut, dtc]
Maintainer:	S. Mason Garrison <garrissm@wfu.edu>
Repository:	CRAN
Date/Publication:	2026-09-01 08:50:08 UTC

addPersonToPed

Description

A function to add a new person to an existing pedigree data.frame.

Usage

addPersonToPed(
  ped,
  name = NULL,
  sex = NULL,
  momID = NA,
  dadID = NA,
  twinID = NULL,
  personID = NULL,
  zygosity = NULL,
  notes = NULL,
  url = NULL,
  overwrite = FALSE
)

Arguments

Value

A data.frame with the new person added to the existing pedigree.

Apply Tag Mappings to a Line

Description

Iterates over a list of tag mappings and, if a tag matches the line, updates the record. Stops after the first match.

Usage

applyTagMappings(line, record, pattern_rows, tag_mappings)

Arguments

Value

A list with the updated record (record) and a logical flag (matched).

Parse Tree

Description

Parse Tree

Usage

buildTreeGrid(tree_lines)

Arguments

Value

A data frame containing the tree structure.

Examples

buildTreeGrid(c(" | | GMa |~|y|~| GPa | ", " | | MOM |y| DAD | | "))

collapse Names

Description

This function combines the 'name_given' and 'name_given_pieces' columns in a data frame. If both columns have non-missing values that differ, a warning is issued and the original 'name_given' is retained. If one column is missing, the other is used. The same logic applies to the 'name_surn' and 'name_surn_pieces' columns.

Usage

collapseNames(verbose, df_temp)

Arguments

Value

A data frame with the combined columns.

Combine Columns

Description

This function combines two columns, handling conflicts and merging non-conflicting data.

Usage

combineColumns(col1, col2)

Arguments

Value

A list with the combined column and a flag indicating if the second column should be retained.

Convert GEDCOM Coordinate Columns to Numeric

Description

Converts all latitude and longitude columns in a parsed GEDCOM data frame from GEDCOM compass-prefix notation (e.g., '"N51.5074"', '"W0.1278"') to signed decimal degrees. By default, all columns whose names end in '_lat' or '_long' are converted.

Usage

convertGedcomCoords(df, lat_cols = NULL, long_cols = NULL)

Arguments

Value

The data frame with the specified columns replaced by numeric values.

Examples

df <- data.frame(
  birth_lat = "N51.5074", birth_long = "W0.1278",
  stringsAsFactors = FALSE
)
convertGedcomCoords(df)

Make Long Tree

Description

Make Long Tree

Usage

convertGrid2LongTree(tree_df, cols_to_pivot)

Arguments

Value

A long data frame containing the tree structure.

Count GEDCOM Pattern Rows

Description

Counts the number of lines in a file (passed as a data frame with column "X1") that match various GEDCOM patterns. Returns a list with counts for each pattern.

Usage

countPatternRows(file)

Arguments

Value

A list with counts of specific GEDCOM tag occurrences.

Deduplicate pairs of IDs in a data frame

Description

Deduplicate pairs of IDs in a data frame

Usage

deduplicatePairs(df)

Arguments

Value

A data frame with unique pairs of IDs

Detect GEDCOM Version from File Lines

Description

Detect GEDCOM Version from File Lines

Usage

detectGedcomVersion(lines)

Arguments

Value

A string such as '"5.5.1"', '"7.0"', or '"unknown"'.

Extract Coordinate from Event Sub-Block

Description

Given a sub-block of GEDCOM lines corresponding to an event (e.g., birth or death) and a coordinate tag ("LATI" or "LONG"), this function searches all lines in the sub-block for the first occurrence of the tag as a whole word. This approach allows it to find coordinates regardless of whether they are direct children of the event, nested under a "PLAC" structure, or nested under a "MAP" structure within "PLAC". If a matching line is found, it extracts the coordinate information using the 'extractInfo()' function; otherwise, it returns 'NA_character_'.

Usage

extractCoordFromSubBlock(sub_block, tag)

Arguments

Value

A character string with the extracted coordinate information from the first matching line, or 'NA_character_' if no matching line is found.

Extract Event Sub-Block

Description

Given a block of GEDCOM lines and a starting index corresponding to an event tag (e.g., "BIRT" or "DEAT"), this function extracts the sub-block of lines that are children of that event. It uses the GEDCOM level structure to determine which lines belong to the event's sub-block, returning all lines until it encounters a line with a level less than or equal to the event's level.

Usage

extractEventSubBlock(block, start_idx)

Arguments

Value

A character vector containing the lines that are part of the event's sub-block, or an empty character vector if there are no child lines.

Extract GEDCOM Level

Description

Extracts the GEDCOM level (the leading integer) from a line of GEDCOM data. This is used to determine the hierarchical structure of the data when parsing events and their sub-fields.

Usage

extractGedcomLevel(line)

Arguments

Value

An integer representing the GEDCOM level, or NA if no leading integer is found.

Extract Year from a GEDCOM Date String

Description

Extracts a four-digit year from a GEDCOM date string, stripping calendar escapes (e.g., '\@#DGREGORIAN\@') and common qualifiers ('ABT', 'BEF', 'AFT', 'BET'/'AND') before searching for the year. Returns 'NA_integer_' when no year is found. The function can be used to extract years from various GEDCOM date formats, including approximate dates and date ranges.

Usage

extractGedcomYear(x, year_len = 4)

Arguments

Value

Integer vector of years.

Examples

extractGedcomYear(c("ABT 1 JAN 1900", "BEF 31 DEC 2000", "1850", NA))

Extract Information from Line

Description

Extracts the relevant information from a GEDCOM line based on the specified type. The function uses regular expressions to locate and return the desired data.

Usage

extractInfo(line, type)

Arguments

Value

A character string with the extracted information.

Extract Information from Lines by Tag

Description

Given a set of lines (e.g., direct children of an event) and a GEDCOM tag, this function searches for the first line that contains the tag as a whole word and extracts the relevant information using the 'extractInfo()' function. If no matching line is found, it returns 'NA_character_'.

Usage

extractInfoFromLines(lines, tag)

Arguments

Value

A character string with the extracted information from the first matching line, or 'NA_character_' if no matching line is found.

Match Members

Description

Match Members

Usage

extractMemberTable(text)

Arguments

Value

A data frame containing information about the members of the family tree.

Find Where One or More IDs Occur Across a List of Data Frames

Description

Searches a named list of data frames for the supplied IDs, looking in every column whose name matches 'id_regex' (parent, spouse, and person-ID columns by default). Returns one row per hit, recording which dataset, which column, and which row the ID was found in, alongside any requested context columns. This is the detective step of link repair: locating every place an ID lives before deciding how to fix it.

Usage

findIDs(
  data_list,
  ID,
  id_regex = "(^id$|id$|^pid|pid$|pid_|dadid|momid|patid|matid|spid|spouse|sire|dame)",
  context_cols = c("sex", "byr", "dyr", "name"),
  ignore_case = TRUE,
  include_all_id_cols = FALSE
)

Arguments

Details

Unlike [sliceByID()], this does *not* standardize column names, because its whole purpose is to catch IDs wherever they hide, including in non-canonical columns.

Value

A data frame with one row per match, containing 'matched_id', 'dataset', 'matched_column', 'matched_value', the source 'row_index', and any available 'context_cols'. Returns an empty data frame if nothing matches.

Examples

clean <- readGedcom(
  system.file("extdata", "waugh.ged", package = "tidygedcom"),
  verbose = FALSE
)
messy <- readGedcom(
  system.file("extdata", "waugh_messy.ged", package = "tidygedcom"),
  verbose = FALSE
)

# Locate every reference to W. Henderson Waugh across both parses
findIDs(list(clean = clean, messy = messy), ID = 3)

Convert GEDCOM Latitude String to Numeric

Description

Converts GEDCOM-style latitude strings like '"N51.5074"' or '"S33.8688"' to signed decimal degrees. Returns 'NA' for 'NA' or unrecognized-prefix input.

Usage

gedcomLat2Numeric(x)

Arguments

Value

Numeric vector of decimal degrees (positive = N, negative = S).

Examples

gedcomLat2Numeric(c("N51.5074", "S33.8688", NA))

Convert GEDCOM Longitude String to Numeric

Description

Converts GEDCOM-style longitude strings like '"E151.2093"' or '"W0.1278"' to signed decimal degrees. Returns 'NA' for 'NA' or unrecognized-prefix input.

Usage

gedcomLon2Numeric(x)

Arguments

Value

Numeric vector of decimal degrees (positive = E, negative = W).

Examples

gedcomLon2Numeric(c("E151.2093", "W0.1278", NA))

Build adjacency list (4-way neighbors)

Description

Build adjacency list (4-way neighbors)

Usage

getGridNeighbors(cell, active_keys)

Arguments

Value

A character vector of neighboring cell keys

Extract Summary Text

Description

Extract Summary Text

Usage

getWikiTreeSummary(text)

Arguments

Value

A character string containing the summary text.

Examples

getWikiTreeSummary("{{familytree/start |summary=A three-generation example.}}")

Impute a Day (and Month) for Partial GEDCOM Dates

Description

Historical genealogical records are frequently precise only to the month or the year: a birth year reconstructed from a census age question, or a death month taken from a probate filing. 'as.Date()' requires a day component, so such dates would otherwise be dropped entirely.

This helper fills in the missing components with the midpoint of the known interval – the 15th for a known month, and 15 June for a known year only – which minimizes the expected error of the imputed value. Values that already carry a day, and values that match neither pattern, are returned unchanged.

Callers should strip calendar escapes and qualifiers ('ABT', 'BEF', 'AFT') before calling this function.

Usage

imputePartialDates(x, default_day = "15", default_month = "JUN")

Arguments

Value

A character vector of the same length, with month- and year-precision entries expanded to a full '"

Initialize an Empty Individual Record

Description

Creates a named list with all GEDCOM initialized to NA_character_.

Usage

initializeRecord(all_var_names)

Arguments

Value

A named list representing an empty individual record.

Build Attribute Tag Mappings

Description

Returns a list of tag-to-field mappings for GEDCOM individual-attribute tags (SEX, CAST, DSCR, EDUC, IDNO, NATI, NCHI, NMR, OCCU, PROP, RELI, RESI, SSN, TITL). Build this once and pass it to parseIndividualBlock() via the mappings argument.

Usage

make_attribute_mappings()

Value

A list of mapping entries, each with tag, field, and mode elements.

Build Event Field Mappings

Description

Returns a named list mapping each supported GEDCOM life-event type to the record fields it populates. Each entry has two sublists: children (tags extracted from direct child lines via extractInfoFromLines()) and subblock (tags searched across all descendant lines via extractCoordFromSubBlock()). Build this once and pass it to processEventLine() rather than constructing it on every call.

Usage

make_event_fields()

Value

A named list with entries birth, chr, death, and burial.

Build Name-Piece Tag Mappings

Description

Returns a list of tag-to-field mappings for GEDCOM name-piece tags (GIVN, NPFX, NICK, SURN, NSFX, _MARNM). Build this once and pass it to parseIndividualBlock() via the mappings argument.

Usage

make_name_piece_mappings()

Value

A list of mapping entries, each with tag, field, and mode elements.

Build Relationship Tag Mappings

Description

Returns a list of tag-to-field mappings for GEDCOM family-relationship tags (FAMC, FAMS). Each entry includes a custom extractor that pulls the numeric family ID from the cross-reference pointer. Build this once and pass it to parseIndividualBlock() via the mappings argument.

Usage

make_relationship_mappings()

Value

A list of mapping entries, each with tag, field, mode, and extractor elements.

Assign momID and dadID based on family mapping

Description

This function assigns mother and father IDs to individuals in the data frame based on the mapping of family IDs to parent IDs. It updates the data frame in place.

Usage

mapFAMC2parents(df_temp, family_to_parents)

Arguments

Value

A data frame with added momID and dad_ID columns.

Create a Mapping from Family IDs to Parent IDs

Description

This function scans the data frame and creates a mapping of family IDs to the corresponding parent IDs.

Usage

mapFAMS2parents(df_temp, mom_sex = "F", dad_sex = "M")

Arguments

Value

A list mapping family IDs to parent information.

Parse a GEDCOM Family Block

Description

Parse a GEDCOM Family Block

Usage

parseFamilyBlock(block, verbose = FALSE)

Arguments

Value

A named list with family fields, or 'NULL' if no family ID is found.

Parse a GEDCOM Individual Block

Description

Processes a block of GEDCOM lines corresponding to a single individual.

Usage

parseIndividualBlock(
  block,
  pattern_rows,
  all_var_names,
  mappings,
  verbose = FALSE
)

Arguments

Value

A named list representing the parsed record for the individual, or NULL if no ID is found.

Parse Name Line

Description

Extracts full name information from a GEDCOM "NAME" line and updates the record accordingly.

Usage

parseNameLine(line, record)

Arguments

Value

The updated record with parsed name information.

infer relationship from tree template

Description

infer relationship from tree template

Usage

parseTreeRelationships(tree_long, tree_paths = NULL)

Arguments

Value

A data frame containing the relationships between family members.

Assign Parent

Description

Assign Parent

Usage

populateParents(df, child, parent)

Arguments

Value

A data frame with updated parent information.

Post-process GEDCOM Data Frame

Description

This function optionally adds parent information, combines duplicate columns, and removes empty columns from the GEDCOM data frame. It is called by readGedcom() if post_process = TRUE.

Usage

postProcessGedcom(
  df_temp,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  add_parents = TRUE,
  parse_dates = FALSE,
  impute_partial_dates = TRUE,
  clean_names = TRUE,
  skinny = TRUE,
  verbose = FALSE
)

Arguments

Value

The post-processed data frame.

Process Event Lines (Birth or Death)

Description

Extracts event details (e.g., date, place, cause, latitude, longitude) from a block of GEDCOM lines. Uses level-aware sub-block parsing so fields are looked up by tag name rather than fixed offsets.

Usage

processEventLine(event, block, i, record, pattern_rows, event_fields)

Arguments

Value

The updated record with parsed event information.

Process Parents Information from GEDCOM Data

Description

This function adds mother and father IDs to individuals in the data frame

Usage

processParents(df_temp, datasource, person_id_col = "personID")

Arguments

Value

The updated data frame with parent IDs added.

Process a GEDCOM Tag

Description

Extracts and assigns a value to a specified field in 'vars' if the pattern is present. Returns both the updated variable list and a flag indicating whether the tag was matched.

Usage

processTag(
  tag,
  field_name,
  pattern_rows,
  line,
  vars,
  extractor = NULL,
  mode = "replace"
)

Arguments

Value

A list with updated 'vars' and a 'matched' flag.

Read a GEDCOM File

Description

Ingests a GEDCOM genealogy file, identifies individual records, and parses person-level identifiers, names, life events, attributes, and family relationships into a structured data frame. Optional post-processing can infer parental IDs from family relationships, reconcile redundant name fields, and remove uninformative columns from the parsed output.

Usage

readGedcom(
  file_path,
  verbose = FALSE,
  post_process = TRUE,
  add_parents = TRUE,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  skinny = FALSE,
  parse_dates = FALSE,
  impute_partial_dates = TRUE,
  clean_names = TRUE,
  update_rate = 1000,
  ...
)

readGed(
  file_path,
  verbose = FALSE,
  post_process = TRUE,
  add_parents = TRUE,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  skinny = FALSE,
  parse_dates = FALSE,
  impute_partial_dates = TRUE,
  clean_names = TRUE,
  update_rate = 1000,
  ...
)

readgedcom(
  file_path,
  verbose = FALSE,
  post_process = TRUE,
  add_parents = TRUE,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  skinny = FALSE,
  parse_dates = FALSE,
  impute_partial_dates = TRUE,
  clean_names = TRUE,
  update_rate = 1000,
  ...
)

Arguments

Details

'readGedcom()' is a line-oriented parser tuned to common GEDCOM 5.5 and 5.5.1 structures. Individual records are identified from blocks that begin with an '@ INDI' line. Each individual block is passed to an internal parser that uses simple GEDCOM tag pattern matches to extract identifiers, names, life events, attributes, and family relationships.

Name information is parsed primarily from the GEDCOM 'NAME' tag, which often encodes given names and surnames using slash-delimited surname notation, such as 'NAME John /Smith/'. The parser extracts the given name, surname, and a cleaned full name. Additional name components are parsed when present, including name prefix, name suffix, nickname, and married surname.

Birth and death events are recognized from 'BIRT' and 'DEAT' tags. Event details are parsed by collecting all child lines whose GEDCOM level equals the event level plus one (direct children), then looking up sub-fields by tag name. 'DATE', 'PLAC', and 'CAUS' are matched as direct children of the event. Coordinates ('LATI' and 'LONG') are searched across all descendant lines, which allows them to be located whether they appear as direct children (common in some GEDCOM 5.5.x exporters), under 'PLAC' (standard GEDCOM 5.5.1), or under a 'MAP' substructure under 'PLAC' (GEDCOM 7.x). Missing sub-fields leave the corresponding output columns as 'NA'.

Attribute tags such as 'OCCU', 'EDUC', 'RELI', 'CAST', 'NCHI', 'NMR', 'NATI', 'RESI', 'PROP', 'SSN', 'TITL', 'DSCR', and 'IDNO' are parsed directly into dedicated columns prefixed with 'attribute_'.

Family relationships are parsed from 'FAMC' and 'FAMS' tags. 'FAMC' identifies the family in which an individual is a child, and 'FAMS' identifies families in which an individual is a spouse. These raw family identifiers are retained in the parsed output unless removed during post-processing. When 'add_parents = TRUE', they are also used to infer 'momID' and 'dadID'.

If 'post_process = TRUE', 'readGedcom()' applies optional cleanup steps controlled by 'add_parents', 'combine_cols', 'remove_empty_cols', and 'skinny'. These steps can infer parent IDs, collapse redundant name fields, remove columns that are entirely missing, and drop raw family relationship columns for a slimmer output.

Value

A data frame containing information about individuals, with the following potential columns:

personID

Individual ID parsed from the '@ INDI' line.

momID

ID of the individual's mother, if inferred.

dadID

ID of the individual's father, if inferred.

sex

Sex of the individual.

name

Cleaned full name of the individual.

name_given

Given name parsed from the 'NAME' tag.

name_given_pieces

Given name parsed from a separate 'GIVN' tag, if present.

name_surn

Surname parsed from the 'NAME' tag.

name_surn_pieces

Surname parsed from a separate 'SURN' tag, if present.

name_marriedsurn

Married surname parsed from '_MARNM', if present.

name_nick

Nickname parsed from 'NICK', if present.

name_npfx

Name prefix parsed from 'NPFX', if present.

name_nsfx

Name suffix parsed from 'NSFX', if present.

birth_date

Birth date of the individual.

birth_lat

Latitude of the birthplace.

birth_long

Longitude of the birthplace.

birth_place

Birthplace of the individual.

chr_date

Christening date of the individual ('CHR' tag).

chr_place

Christening place of the individual.

death_caus

Cause of death.

death_date

Death date of the individual.

death_lat

Latitude of the place of death.

death_long

Longitude of the place of death.

death_place

Place of death of the individual.

burial_date

Burial date of the individual ('BURI' tag).

burial_lat

Latitude of the burial place.

burial_long

Longitude of the burial place.

burial_place

Burial place of the individual.

attribute_caste

Caste of the individual.

attribute_children

Number of children of the individual.

attribute_description

Description of the individual.

attribute_education

Education of the individual.

attribute_idnumber

Identification number of the individual.

attribute_marriages

Number of marriages of the individual.

attribute_nationality

Nationality of the individual.

attribute_occupation

Occupation of the individual.

attribute_property

Property owned by the individual.

attribute_religion

Religion of the individual.

attribute_residence

Residence of the individual.

attribute_ssn

Social Security number of the individual.

attribute_title

Title of the individual.

FAMC

ID or IDs of the family in which the individual is a child.

FAMS

ID or IDs of families in which the individual is a spouse.

If no individual records are found, the function returns 'NULL' with a warning.

Examples

# A small excerpt of the W. Henderson Waugh family tree
ged_file <- system.file("extdata", "waugh.ged", package = "tidygedcom")
ped <- readGedcom(ged_file, verbose = FALSE)
ped[, c("personID", "name", "sex", "birth_date", "momID", "dadID")]

# Keep every parsed column rather than the default slimmed output
full <- readGedcom(ged_file, verbose = FALSE, remove_empty_cols = FALSE)
ncol(full)

Read Family Records from a GEDCOM File

Description

Parses 'FAM' records from a GEDCOM file and returns a tidy data frame with one row per family unit. Captures husband, wife, children, marriage event, and divorce event details.

Usage

readGedcomFamilies(
  file_path,
  verbose = FALSE,
  parse_dates = FALSE,
  remove_empty_cols = TRUE,
  ...
)

Arguments

Value

A data frame with one row per 'FAM' record and the following columns:

famID

Family identifier from the '@ FAM' line.

husbID

Person ID of the husband ('HUSB' tag).

wifeID

Person ID of the wife ('WIFE' tag).

children

Comma-separated person IDs of children ('CHIL' tags).

marr_date

Marriage date ('MARR/DATE').

marr_place

Marriage place ('MARR/PLAC').

marr_lat

Marriage latitude ('MARR/.../LATI').

marr_long

Marriage longitude ('MARR/.../LONG').

div_date

Divorce date ('DIV/DATE').

div_place

Divorce place ('DIV/PLAC').

Returns 'NULL' with a warning if no family records are found.

Examples

fam <- readGedcomFamilies(
  system.file("extdata", "waugh.ged", package = "tidygedcom"),
  verbose = FALSE
)
fam

Read Wiki Family Tree

Description

Read Wiki Family Tree

Usage

readWikifamilytree(text = NULL, verbose = FALSE, file_path = NULL, ...)

Arguments

Value

A list containing the summary, members, structure, and relationships of the family tree.

Examples

tree_text <- paste(
  "{{familytree/start |summary=A three-generation example.}}",
  "{{familytree | | | | GMa |~|y|~| GPa | | GMa=Gladys|GPa=Sydney}}",
  "{{familytree | | | | | | | |)|-|-|-|.| }}",
  "{{familytree | | | MOM |y| DAD | |AUNT| MOM=Mom|DAD=Dad|AUNT=Aunt Daisy}}",
  "{{familytree | |,|-|-|-|.| | | | | | }}",
  "{{familytree | JOE | | ME  | | JOE=Joe|ME=Me}}",
  "{{familytree/end}}",
  sep = "\n"
)

tree <- readWikifamilytree(text = tree_text)
tree$summary
head(tree$members)

Apply a List of Hand-Verified Fixes to a Pedigree

Description

Applies a set of manual corrections to a pedigree data frame, recording the provenance of each edit in 'manual_fix' and 'manual_fix_comment' columns and refusing to let two fixes silently touch the same row. This is the repair counterpart to BGmisc's automated [BGmisc::repairIDs()] / [BGmisc::repairSex()]: for the cases a human has to resolve by hand, it keeps the edits reproducible and auditable.

Usage

repairManually(ped, fixes)

Arguments

Details

Each element of 'fixes' is itself a list with three parts:

rows

A quoted expression (see [rlang::quo()]) that evaluates within 'ped' to a logical row selector, e.g. 'rlang::quo(ID == 348700)'.

changes

A named list of 'column = new_value' pairs to assign to the selected rows.

comment

A short human-readable note explaining the fix.

Value

'ped' with the fixes applied and the 'manual_fix' / 'manual_fix_comment' provenance columns populated.

Examples

# The messy example file omits Laura Watkins's SEX line, so she cannot be
# resolved as a mother during parsing.
ped <- readGedcom(
  system.file("extdata", "waugh_messy.ged", package = "tidygedcom"),
  verbose = FALSE
)
ped$sex[ped$personID == 6]

fixes <- list(
  laura_sex = list(
    rows = rlang::quo(personID == 6),
    changes = list(sex = "F"),
    comment = "Sex absent from source export; confirmed by 1880 census."
  )
)
ped <- repairManually(ped, fixes)
ped[ped$personID == 6, c("personID", "name", "sex", "manual_fix")]

Royal pedigree data from 1992

Description

This dataset builds on an existing dataset created by Denis Reid of the Royal Families of Europe. That data was originally published in 1992 and is available on the internet. This version has been updated to combine duplicate entries and to include additional information on birth and death dates, as well as titles. This dataset is intended for educational and illustrative use in software demonstrations involving pedigree diagrams, inheritance structures, and kinship modeling. This dataset is not intended to represent any real individuals or families beyond the original source data, and it is provided solely for educational purposes.

Usage

data(royal92)

Format

A data frame with 3010 observations

Details

The variables are as follows:

• personID: Person identification variable

• momID: ID of the mother

• dadID: ID of the father

• famID: ID of the extended family

• twinID: ID of the twin, if applicable

• name: Name of the person

• sex: Biological sex

• birth_date: Date of birth

• death_date: Date of death

• title: Title of the person

Slice a Pedigree Down to the Rows Referencing an ID

Description

Given a pedigree data frame, returns every row in which any of the supplied IDs appears as the individual themselves, a parent, or a spouse. This is a diagnostic aid for inspecting a person's full household before and after manually repairing links in GEDCOM-derived pedigrees. The result is a subset of 'ped' with the same columns..

Usage

sliceByID(ped, ID, sort = TRUE)

Arguments

Details

Incoming column names are normalized with BGmisc's internal column standardizer, so the common variants ('ID'/'personID', 'dadID'/'pid_fath', 'momID'/'pid_moth', 'spID'/'pid_spouse1', ...) are all recognized without the caller naming them. Because BGmisc's canonical schema is single-spouse but GEDCOM-derived pedigrees often record remarriages in extra columns, any additional spouse-like columns (matching 'spID2', 'pid_spouse2', ...) are detected and searched too. The returned rows keep the caller's original column names.

Value

A data frame: the subset of 'ped' rows in which any of 'ID' appears in a linking column, with the original columns and names preserved.

Examples

ped <- readGedcom(
  system.file("extdata", "waugh.ged", package = "tidygedcom"),
  verbose = FALSE
)

# Inspect William Pitt Waugh Sr. and everyone linked to him
sliceByID(ped, ID = 1)

Split GEDCOM Lines into Family Blocks

Description

Split GEDCOM Lines into Family Blocks

Usage

splitFamilies(lines, verbose = FALSE)

Arguments

Value

A list of character vectors, each representing one FAM record.

Split GEDCOM Lines into Individual Blocks

Description

This function partitions the GEDCOM file (as a vector of lines) into a list of blocks, where each block corresponds to a single individual starting with an "@ INDI" line.

Usage

splitIndividuals(lines, verbose = FALSE)

Arguments

Details

Each block runs until the next "@ INDI" line or end-of-file. Blocks are raw subsets of the file; no parsing occurs here.

Value

A list of character vectors, each representing one individual.

Strip Calendar Escapes and Approximation Qualifiers from GEDCOM Dates

Description

Removes calendar escape codes (e.g. '@#DGREGORIAN@') and the approximation qualifiers 'ABT', 'AFT', 'BEF', and 'BET' from GEDCOM date strings, leaving the bare date behind.

The qualifier may be followed either by a period or by a word boundary, because Ancestry.com exports write '"Abt. Jun 1880"' while the GEDCOM specification uses '"ABT JUN 1880"'. Requiring one or the other is what keeps the pattern from biting into ordinary words that merely begin with those letters, such as "before".

Usage

stripDateQualifiers(x)

Arguments

Value

A character vector of the same length, trimmed, with escapes and qualifiers removed.

Summarize a Parsed GEDCOM Data Frame

Description

Returns key counts and coverage statistics for a data frame produced by readGedcom().

Usage

summarizeGedcom(df)

Arguments

Value

An object of class "tidygedcom_summary" (a named list). Print the result for a human-readable overview.

Examples

df <- readGedcom(
  system.file("extdata", "waugh.ged", package = "tidygedcom"),
  verbose = FALSE
)
summarizeGedcom(df)

# Coverage drops on a file with missing records
messy <- readGedcom(
  system.file("extdata", "waugh_messy.ged", package = "tidygedcom"),
  verbose = FALSE
)
summarizeGedcom(messy)

Summarize Where One or More IDs Occur Across a List of Data Frames

Description

A count-level companion to [findIDs()]: instead of one row per hit, returns one row per (id, dataset, column) with the number of matches. Useful for a quick census of how many places an ID appears before drilling in with [findIDs()].

Usage

summarizeIDs(data_list, ID, ...)

summariseIDs(data_list, ID, ...)

Arguments

Value

A data frame with columns 'matched_id', 'dataset', 'matched_column', and 'n_matches'.

Examples

clean <- readGedcom(
  system.file("extdata", "waugh.ged", package = "tidygedcom"),
  verbose = FALSE
)
messy <- readGedcom(
  system.file("extdata", "waugh_messy.ged", package = "tidygedcom"),
  verbose = FALSE
)

# Count references per dataset and column
summarizeIDs(list(clean = clean, messy = messy), ID = 3)

Trace paths between individuals in a family tree grid

Description

Trace paths between individuals in a family tree grid

Usage

traceTreePaths(tree_long, deduplicate = TRUE)

Arguments

Value

A data.frame with columns: from_id, to_id, direction, path_length, intermediates

Examples

# Two individuals joined by a horizontal connector
tree_long <- data.frame(
  Row = rep(1, 3),
  Column = 1:3,
  Value = c("A", "+", "B"),
  id = c("A", NA, "B")
)

traceTreePaths(tree_long)