README.Rmd

---
output: github_document
always_allow_html: yes
---

<!-- README.md is generated from README.Rmd. Please edit that file -->


```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

<!-- badges: start -->
[![Travis-CI Build Status](https://travis-ci.org/emillykkejensen/familyR.svg?branch=master)](https://travis-ci.org/emillykkejensen/familyR)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://www.tidyverse.org/lifecycle/#stable)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
<!-- badges: end -->

# familyR

The goal of familyR is to provide a fast way to get all parents, children and even the entire family tree of a node. It uses nothing but data.table and hence it is fast!

familyR consists of tree main functions:
1. get_familytree
2. get_parents
3. get_children

familyR is built so it is easy to visualize with visNetwork's hierarchical layout as both get_parents and get_children include the number of levels (or generations if you will), there are between the node you are looking and other nodes in the family.

## Installation

You can install familyR from github with:

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("emillykkejensen/familyR")
```

## How to use familyR

First load the package - note, that familyR relies heavily on data.table.

```{r}
library(familyR)
```

To use familyR you need a data.table of relations:

```{r}
my_network <- data.table::data.table(
  from = c("A", "A", "B", "B", "C", "C", "X", "Y"),
  to   = c("B", "C", "D", "E", "E", "B", "Y", "Z")
)
```

Note that in order for it to work, you need to name the two columns "from" and "to" - you can include others if you like, as long as you have from and to!

### The main functions

Now let's try to get the entire family tree of node B.

```{r}
my_familytree <- get_familytree(my_network, "C")

print(my_familytree$nodes)

print(my_familytree$edges)
```

As you can see the function not only returns the entire family tree of a node B, but also the level (or number of generations) between the node you are looking for (in this case "B") and the other nodes in the family.

By looking at the level column we can see, that node C is directly related to node A, E and B and is related in second generation with node D.

To show this with visNetwork all you need is:

```{r eval=FALSE}
library(visNetwork)

visNetwork(my_familytree$nodes, my_familytree$edges) %>%
  visEdges(arrows = "to")
```

If we are not interested in the entire family tree, but only want the parents of a node use get_parents()

```{r}
my_parents <- get_parents(my_network, "D")

print(my_parents$nodes)

print(my_parents$edges)
```

get_parents() not only returns the parents of a node, but also the grandparents, grand grandparents etc.

As with get_familytree() this function also returns both the node id and the level, but here you'll notice that the levels are given a negative value. This is to show the direction of the generation and comes in handy if you want to merge with get_children().

To get all children of a node use get_children(). This works exactly like get_parents(), but returns levels in positive numbers.

### Combining functions

If you don't want the entire family tree of a node, but would like to get both parents and children you can combine them using merge_family()

```{r}
my_parents <- get_parents(my_network, "C")

my_children <- get_children(my_network, "C")

my_family <- merge_family(my_parents, my_children)

print(my_family$nodes)

print(my_family$edges)
```

This will give you both parents (with a negative level value) and children (with a positive level value) of node C.

As you can see from my_family$edges, some nodes are internally related (node B and E). If you would like to show, only direct relations to node C and thus remove those inner relations, use the remove_inner_relations() function.

```{r}
my_new_family <- remove_inner_relations(my_family)

print(my_new_family$nodes)

print(my_new_family$edges)
```

Now you can use my_new_family with visNetwork's visHierarchicalLayout function, that uses the level column.

```{r eval=FALSE}
visNetwork(my_new_family$nodes, my_new_family$edges) %>% 
    visEdges(arrows = "to") %>%
    visHierarchicalLayout()
```

### Nice to know

familyR uses data.table and thus builds on the principle of changing input by reference. Therefor you need to specify, that you want to copy data from on data.table to another insted of just creating a new reference. To do this, use the copy_family() function.

```{r eval=FALSE}
my_copied_family <- copy_family(my_new_family)
```