---
title: "Family group records"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Family group records}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

Adding family groups to a tidyged object can be achieved with the `add_famg()` function. The main arguments are about defining the members of the family group. The `husband`, `wife`, and `children` parameters can be xrefs to other Individual records, or calls to the `find_indi_*()` family of functions (see `vignette("cross_references")`). The `number_of_children` parameter describes the total number of known children in this family, regardless of whether they are defined.

The family group records do not need to describe traditional marriage unions - they can describe non-marital relationships and same-sex relationships. Children also do not have to be biological. The parameter names are a legacy from previous versions of the GEDCOM specification, which have not yet been updated.

```{r}
library(tidyged)

simpson_indis <- gedcom(subm("Me")) |> 
  add_indi(qn = "Homer Simpson", sex = "M") |> 
  add_indi(qn = "Marge Simpson", sex = "F") |> 
  add_indi(qn = "Lisa Simpson", sex = "F") |> 
  add_indi(qn = "Bart Simpson", sex = "M") |> 
  add_note("These records have not yet been joined in a family group record")

simpson_famg <- simpson_indis |> 
  add_famg(husband = "@I1@", wife = find_indi_name(simpson_indis, "Marge"), 
           children = find_indi_name_all(simpson_indis, "Bart|Lisa"), number_of_children = 3)

knitr::kable(dplyr::filter(simpson_famg, record == "@F1@"))
```

As with other records, various types of user-defined references can be defined (`user_reference_numbers`), as well as links to multimedia and notes.

A Family Group record can be removed using the `remove_famg()` function.

## Family events

Events associated with a family group, such as marriages and censuses, are created using the `add_famg_event()` function. The full list of events that can be created are given in the Details section of the function help page.

There are some types of event; census and residence, that can apply for Individuals and Family Groups. It is highly recommended you do not use these events for family groups, only for individuals. It may intuitively be more efficient to define an event for an entire family group, but other GEDCOM parsers can have difficulty with this, and defining these events for each individual separately is recommended. Despite the name, Family Group records are actually more about the union of two people, rather than the family unit as a whole, and so the remaining events are related to marriages and divorces.

In the example below, a relationship is added. The default type of relationship is a marriage, but this can be changed using the `classification` parameter. Ages of the couple when they got married can be defined used the `husband_age` and `wife_age` parameters. Unlike the GEDCOM specification, in a tidyged object these ages are given on single lines instead of being split across multiple lines; however they do revert to the specification on export.

```{r}
simpson_famg |> 
  add_famg_event("rel", date = date_calendar(1986, 5, 11),
                 husband_age = "20y", wife_age = "19y") |> 
  dplyr::filter(record == "@F1@") |> 
  knitr::kable()
```

The `descriptor` parameter is used only for miscellaneous other events ("eve").

You can see a summary of all events associated with a family group with the `df_famg_facts()` function.

## Family links

The `tidyged` package seeks to make cross-referencing as painless and automated as possible. When adding a Family Group record, as well as creating the record, it will also create the relevant links to the family group in the Individual record for each member of the family:

```{r}
dplyr::filter(simpson_famg, tag %in% c("FAMS", "FAMC")) |> 
  knitr::kable()
```

The lines above show particular lines in the Individual records where they are linked to the Family Group record either as a spouse (FAMS) or as a child (FAMC).

If the Family Group record is subsequently removed, then these links will also be removed:

```{r}
simpsons_no_fam <- simpson_famg |> 
  remove_famg() 

dplyr::filter(simpsons_no_fam, tag %in% c("FAMS", "FAMC"))

waldo::compare(simpson_indis, simpsons_no_fam, ignore_attr = TRUE)
```


When removing a Family Group record, the user also has the option of removing all trace of the individuals within the family group as well:

```{r}
simpsons_no_fam_purge <- simpson_famg |> 
  remove_famg(remove_individuals = TRUE) 

str(simpsons_no_fam_purge)
```

Note that as well as having no families defined, we also now have no individuals.

<p style="text-align: right;"><a href="https://jl5000.github.io/tidyged/articles/repository_records.html">Next article: Repository records ></a></p>