In erj22/FlippR: Analyze Life History Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(FlippR)
library(magrittr)
library(dplyr)

Introduction

The FlippR package is designed to work with life history data from long term animal research projects, modeled using life history data from the Shark Bay Dolphin Project's database of dolphin demographic data. FlippR allows the user to do simple data manipulation on data in the "life history data format". For the purposes of this package, life history data format means that data to be manipulated contains the following columns and data types:

knitr::kable(Your_Data) #our example dataset

IndividualID should contain character data with the identifier for the individual that a row's life history data corresponds to. In the case of the example dataset, this is a 3-letter code which is unique to the individual. MotherID should contain character data with the identifier for the individual's mother. For best functioning, every mother mentioned in the MotherID column should also have their own IndividualID row, but some functions in the package can still be run without that being true. The Sex column should contain character information with the individual's sex, either "MALE," "FEMALE," or "UNKNOWN." BirthDate should contain the date of birth in date format of the individual in that row's IndividualID and DeathDate should contain the date of death in date format of the same individual. For all columns, missing data should be filled with NA values, including the DeathDate of individuals in the population who are still presumed alive. There can be more columns than just the 5 required for the package that will be manipulated along with the columns of interest.

The packages that are required to run FlippR are dplyr and magrittr.

KnownInfoIndivs

The KnownInfoIndivs function is a sort of complete cases for demographic information pertinent to many analyses of life history data. Many long term animal research projects collect information on many individuals for whom full demographic data is not known, such as dolphin calves who died before sex could be determined or individuals who were adults at the time of the project's beginning and so for whom a birth date is not know. In some analyses, the inclusion of these individuals is problematic. KnownInfoIndivs filters life history data to only include individuals who we know the most important demographic information about: who their mother is, what their sex is, and when they were born. KnownInfoIndivs only requires the single dataset of individuals of interest as input and returns the same dataset with only the individuals who fit the criteria.

In the following example, we will take our initial dataframe and run it through KnownInfoIndivs to remove all individuals about whom there is too much unknown information for the sake of our analyses.

knitr::kable(Your_Data) #our original dataset

Your_Data.filtered = KnownInfoIndivs(Your_Data) #run it through the function to filter out indivs without enough info

knitr::kable(Your_Data.filtered)

Here we see that individual PIP was eliminated because we don't know who her mother was or when she was born, GET was eliminated because we don't know who her mother was, HEP was eliminated because we don't know their sex, and NOM was eliminated because we don't know who her mother was. Now, we can do our analyses knowing that we are analyzing only individuals about whom we have maternal, sex, and birth date information.

HasGrandma

The HasGrandma function is the first of a two function "Grandma suite" to identify which individuals in a population have grandmothers in the population, and later, who those grandmothers are. Finding grandmothers could be useful in, for example, studying maternal effects or constructing pedigrees of the individuals in the population. HasGrandma takes as input the same kind of life history data format dataframe containing the individuals of interest, and also requires the full life history data for the population (ex. which has not been filtered to remove individuals with incomplete data) in the same data format, in order to determine the generational relationships of the individuals of interest. HasGrandma will return the dataframe of individuals of interest back with only the individuals who have a grandmother with her own life history data entry in the data. Importantly, this function only works with complete life history data for the population where there is a life history entry for every mother. If an individual has a mother who does not have her own entry, the function will fail.

In this example, we will take our data filtered from the previous step and enter it into HasGrandma along with our full dataset which has not been filtered.

knitr::kable(Your_Data.filtered) #our starting data

Your_Data.WithGrandma = HasGrandma(Your_Data.filtered, Full_Data) #run it through the function to find individuals with grandmas

knitr::kable(Your_Data.WithGrandma)

In this case, only two individuals are returned because only two have traceable grandmothers. FLI's mother is KAT, KAT has her own entry which shows her mother is PIP, and PIP has her own entry. Similarly, GOP's mother is GAP, GAP's mother is GET, and GET has her own entry. All other individuals don't have traceable grandmother-grandchild relationships within the population's life history dataset.

Now that we've determined the subset of individuals who do have known grandmothers in the population, we can use the next function, WhosGrandma, to determine the identity of those grandmothers.

WhosGrandma

The WhosGrandma function is designed as the second function of the "Grandma suite". WhosGrandma will only work without throwing an error if a) HasGrandma has already run on the dataset or b) every individual of interest has a known grandmother. HasGrandma is not included within the WhosGrandma function because if an individual was eliminated due to not having a known grandma, the output of WhosGrandma would be a different length than the input data and it would not be possible to match up grandmothers with their grandchildren row-wise, as is possible when the input data contains only individuals with grandmothers.

WhosGrandma takes the life history data format dataframe of individuals of interest with grandmothers as well as the full life history for the population and locates the life history data for the grandmothers of the individuals of interest in the full life history dataset and returns the life history data entries for those grandmothers. In this example, we will take our filtered data output from HasGrandma and put it into WhosGrandma to identify who the grandmothers of those individuals are.

knitr::kable(Your_Data.WithGrandma) #the individuals of interest

Your_Data.Grandmas = WhosGrandma(Your_Data.WithGrandma, Full_Data) #run it through the function to get the grandmas

knitr::kable(Your_Data.Grandmas)

Here we can see that we've started with FLI and GOP and ended with PIP and GET, their grandmothers. FLI's mother is KAT and KAT's mother is PIP. GOP's mother is GAP and GAP's mother is GET, and now we have the demographic information of these grandmothers.

HowOld

Sometimes it might be useful to know how old an individual was on a certain date, for example to filter individuals to include only individuals who were in a certain age group during a specific period of observation. HowOld makes it simple to determine the age of individuals on specific dates. HowOld takes as input the life history data of the individuals of interest as well as a vector with the same number of entries as the number of rows in the input life history data, and returns a vector of the age of each of the individuals on the date specified in the input vector. The vector of dates can be a vector of all the same date or individually specific. The user has an option to return the age in days (default) or converted into decimal years (ex. 3.75 years old). If the individual of interest has not been born or has already died on the date specified, or is an individual for whom we don't know a birth date, then the entry for that individual will be NA in the output vector.

In this example we will calculate the age of each individual on a specific observation date.

knitr::kable(Your_Data) #original data for reference
print(Your_Dates) #our example observation dates

Your_Ages = HowOld(Your_Data, Your_Dates, Age = "Years")

print(Your_Ages)

FLI's age on that date in 2016 was 1 year, so Your_Ages shows an entry of 1. KAT was 5 years old on that date in 2005, so Your_Ages shows an entry of 5. We don't know PIP's birth date, so we cannot compute her age on that date in 2019 and the resulting Your_Ages entry is NA. GOP died in 2019 and the date we specified was 2020, so the resulting Your_Ages entry is NA. GAP was 10 years old on that date in 2012 so Your_Ages shows an entry of 10. GET died in 2005 and the date we specified was in 2020 so the resulting Your_Age entry is NA. Similarly, HEP died in 2008 so our date of 2009 results in an NA for a Your_Age entry. Finally, NOM was born in 1994 so she was 26 years old on that date in 2020 and the Your_Age entry shows a value of 26.

erj22/FlippR documentation built on Jan. 1, 2021, 1:09 a.m.