---
title: "Summarising tidyged objects"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Summarising tidyged objects}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

The `tidyged` package comes with several functions for summarising and querying tidyged objects. The following object is used to illustrate the functionality:

```{r}
library(tidyged)

simpsons <- gedcom(subm("Me"), gedcom_description = "Some of the Simpsons",
                   gedcom_copyright = "No copyright") |> 
  add_indi(qn = "Homer Simpson", sex = "M") |> 
  add_indi_fact("bir", date = date_calendar(1960, 5, 14),
                fact_place = place(name = "Springfield, USA")) |> 
  add_indi(qn = "Marge Simpson", sex = "F") |> 
  add_indi_fact("bir", date = date_calendar(1960, 8, 24),
                fact_place = place(name = "Springfield, USA")) |> 
  add_indi(qn = "Lisa Simpson", sex = "F") |> 
  add_indi_fact("bir", date = date_calendar(1984, 12, 3),
                fact_place = place(name = "Springfield, USA")) |> 
  add_indi(qn = "Bart Simpson", sex = "M") |> 
  add_indi_fact("bir", date = date_calendar(1982, 3, 16),
                fact_place = place(name = "Springfield, USA"))

homer_xref <- find_indi_name(simpsons, "Homer")
marge_xref <- find_indi_name(simpsons, "Marge")
bart_lisa_xref <- find_indi_name_all(simpsons, "Bart|Lisa")

simpsons <- simpsons |>
  add_famg(husband = homer_xref, wife = marge_xref, 
           children = bart_lisa_xref, 
           number_of_children = 3) |> 
  add_note("This is a note") |> 
  add_note("This is another note") |> 
  add_media("123", "PDF") |> 
  add_media("456", "PDF") |>
  add_repo("A library") |> 
  add_sour(originator = "J.R. Hartley", title = "A History of the Simpsons") |>
  add_sour(originator = "Prof. J Frink", title = "The screaming and the pain and the hoyvenglaven")
```

## Global summaries

The `str()` and `summary()` functions give a high level overview of tidyged objects:

```{r}
summary(simpsons)
str(simpsons)
```

## Record type summaries

The `num_*()` family of functions count the number of records of a particular type:

```{r}
num_indi(simpsons)
num_famg(simpsons)
num_media(simpsons)
```

The `xrefs_*()` family of functions return the xrefs of records of a particular type:

```{r}
xrefs_indi(simpsons)
xrefs_note(simpsons)
xrefs_sour(simpsons)
```

These functions are the workhorse of the `str()` function.

The `df_*()` family of functions provide a tabular summary of all records of a particular type:

```{r}
df_indi(simpsons) |> knitr::kable()
df_famg(simpsons) |> knitr::kable()
df_media(simpsons) |> knitr::kable()
```


## Individual record summaries

The `is_*()` family of functions determine whether an xref is a record of a particular type:

```{r}
is_indi(simpsons, "@I1@")
is_famg(simpsons, "@F1@")
is_repo(simpsons, "@N1@")
```

The `describe_*()` family of functions give a description of certain records:

```{r}
describe_indi(simpsons, find_indi_name(simpsons, "Bart"))
describe_indi(simpsons, find_indi_name(simpsons, "Lisa"), name_only = TRUE)
describe_indi(simpsons, find_indi_name(simpsons, "Homer"), short_desc = TRUE)
describe_famg(simpsons, "@F1@")
```

Whilst this family of functions can only operate on one record at a time, the `describe_records()` function can take a whole vector of xrefs, potentially of different types (header, trailer, and duplicate records are ignored by this function):

```{r}
describe_records(simpsons, simpsons$record)
```

As with the record-specific functions, setting `short_desc = TRUE` gives a shorter description.

```{r}
describe_records(simpsons, simpsons$record, short_desc = TRUE)
```

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