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

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

## Introduction

Adding individuals to a tidyged object can be achieved with the `add_indi()` function. The sex of the individual can be specified with the `sex` parameter, which is a single letter: M(ale), F(emale), (Interse)X, U(nknown), N(ot recorded). If no sex is specified, a value of "U" is used.

As with other records, various types of user-defined references can be defined (`user_reference_numbers`).

Individuals can be removed with the `remove_indi()` function.

## Individual names

Individuals can be given more than one name. These can be different kinds of name such as birth name or adoptive name, or if there is uncertainty, variants of these based on conflicting evidence sources. There is also the ability to provide phonetic and romanised variants of names. Given this complexity, the name is usually not immediately defined when creating an Individual record.

There is a quick and dirty way of adding a name with the `qn` parameter, but this is just for use in quick demonstrations and should not be used for serious genealogical recording. The function will crudely place the entire string as the given name of the individual:

```{r}
library(tidyged)

gedcom(subm("Me")) |> 
  add_indi(qn = "Leia Skywalker") |> 
  dplyr::filter(record == "@I1@") |> 
  knitr::kable()
```

### Adding individual names

The main function for providing names for an individual is `add_indi_names()`. The main argument is a `name_pieces()` object giving the components of the name. If you're going to add a name, at least provide a given name or surname:

```{r}
leia <- gedcom(subm("Me")) |> 
  add_indi() |> 
  add_indi_names(name_pieces(given = "Leia", surname = "Skywalker"), type = "birth")

knitr::kable(dplyr::filter(leia, record == "@I1@") )
```

In the GEDCOM specification, all names should be provided by a set of name pieces, specifying the given name, surname, nickname, etc. The function will then automatically construct a formatted full name from this information (surrounding surnames with forward slashes - as given in the specification). Nicknames are not included.

An individual's name (and name pieces) can be removed using the `remove_indi_name()` function. Even though the `add_indi_names()` function surrounds the surname with forward slashes, these are not required to specify the name to remove:

```{r}
leia |> 
  remove_indi_name("Leia Skywalker") |> 
  dplyr::filter(record == "@I1@") |> 
  knitr::kable()
```

This name needs to match exactly to the one to remove.

### Phonetic and romanised names

Once we have defined a name for an individual, we can also define phonetic and romanised versions of the name. For this, we use the `add_indi_names_var()` function. As a minimum, the original name, variant name pieces, derivation method, and whether it is a phonetic or romanised variation should be given. The original name must be given exactly as it is represented in the file without forward slashes ("Leia Skywalker"):

```{r}
leia_var <- leia |> 
  add_indi_names_var("Leia Skywalker", method = "As spoken",
                     name_pieces(given = "Laya", surname = "Skywalker"), phonetic_variation = TRUE) 

knitr::kable(dplyr::filter(leia_var, record == "@I1@"))
```

An individual's name variation can be removed using the `remove_indi_name_var()` function.

### Name types

The `type` parameter can also define different names for the individual. Below we add a line to define an adoptive name (the parameter can take any value):

```{r}
leia_adop <- leia_var |> 
  add_indi_names(name_pieces(given = "Leia", surname = "Organa"), type = "adoptive") 

knitr::kable(dplyr::filter(leia_adop, record == "@I1@"))
```

### Conflicting names

GEDCOM files can also record different names *of the same type*, perhaps due to conflicting evidence. Below we define a name of Leia Skywaker (with no l) indicating some kind of transcription error:

```{r}
leia_conf <- leia_adop |> 
  add_indi_names(name_pieces(given = "Leia", surname = "Skywaker"), type = "birth")

knitr::kable(dplyr::filter(leia_conf, record == "@I1@"))
```

Generally, conflicting names are arranged in order of confidence; the first name is more likely to be correct. If you want to promote a name to occur first in the record, you can use the `primary_indi_name()` function:

```{r}
leia_conf_first <- primary_indi_name(leia_conf, "Leia Skywaker")

knitr::kable(dplyr::filter(leia_conf_first, record == "@I1@"))
```

Note that the subrecords of the Individual record (those at level 1) can appear in any order.

## Individual attributes and events

Attributes and events associated with an individual, such as birth and death, are created using the `add_indi_fact()` function. The full list of facts that can be created are given in the Details section of the function help page.

This function allows you to define a fact, together with associated date, cause, place/address, and the age of the individual when the fact applied (among other aspects). In the example below, we add a residence for an individual. The first argument is given as "residence" for readability even though only the first 3 letters are used:

```{r}
res <- gedcom(subm("Me")) |> 
  add_indi(sex = "M") |> 
  add_indi_fact("residence", date = date_period(start_date = date_calendar(2000, 5, 7),
                                                end_date = date_calendar(2004, 5, 6)),
                fact_address = address(local_address_lines = "23 Penny Lane",
                                       city = "Orlando",
                                       state = "Florida",
                                       country = "United States of America"),
                notes = "Co-habited with brother Henry")

knitr::kable(dplyr::filter(res, record == "@I1@"))
```

If the full address is not known, a more general `place` argument can be used which uses a `place()` object.

The example below defines a death event (in 2006) and a religion attribute (from 1978):

```{r}
dea_rel <- gedcom(subm("Me")) |> 
  add_indi(sex = "M") |> 
  add_indi_fact("death", date = date_calendar(2006, 2, 17),
                fact_place = place(name = "London, England"),
                cause = "Pneumonia",
                age = "68y") |> 
  add_indi_fact("religion", descriptor = "Christian", classification = "Catholic",
                date = date_period(start_date = date_calendar(1978)))

knitr::kable(dplyr::filter(dea_rel, record == "@I1@"))
```

You can see a summary of all facts associated with an individual with the `df_indi_facts()` function.

```{r}
df_indi_facts(dea_rel, "@I1@") |> knitr::kable()
```

## Family links

Typically when constructing a file, you would create all of the individuals in a family first, and then reference them when creating a Family Group record - this takes care of all of the appropriate record links for you. However, sometimes you want to retrospectively add an individual to a Family Group record that already exists. In this case you use the `add_indi_links_to_families()` function.

In the example below, we create Joe Bloggs and add him as a husband to a family. We then create Jess Bloggs and retrospectively add her as a wife to Joe. 

```{r}
ged_with_joe <- gedcom(subm("Me")) |> 
  add_indi("M") |> 
  add_indi_names(name_pieces(given = "Joe", surname = "Bloggs"))

joe_xref <- find_indi_name(ged_with_joe, "Joe")

ged_with_husb <- add_famg(ged_with_joe, husband = joe_xref)

ged_with_jess <- ged_with_husb |>
  add_indi("F") |> 
  add_indi_names(name_pieces(given = "Jess", surname = "Bloggs"))

jess_xref <- find_indi_name(ged_with_jess, "Jess")
  
both <- add_indi_links_to_families(ged_with_jess, spouse = joe_xref)

knitr::kable(dplyr::filter(both, record %in% c("@F1@", "@I2@")))
```

Notice that Jess (@I2@) has now been defined as a wife in the Family Group record, and her record is linked to the Family Group record as a spouse (FAMS).

As well as defining the relationship as a spouse, you can also link individuals to Family Group records by providing the children or parents of the individual.

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