README.Rmd

---
output: github_document
---

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# rollupTree

<!-- badges: start -->

[![CRAN status](https://www.r-pkg.org/badges/version/rollupTree)](https://CRAN.R-project.org/package=rollupTree)
[![R-CMD-check](https://github.com/jsjuni/rollupTree/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jsjuni/rollupTree/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/jsjuni/rollupTree/graph/badge.svg)](https://app.codecov.io/gh/jsjuni/rollupTree)
<!-- badges: end -->

rollupTree implements a general function for computations in which some property of a parent element is a combination of corresponding properties of its child elements. The mass of an assembly, for example, is the sum of the masses of its subassemblies, and the mass of each subassembly is the sum of masses of its parts, etc.

rollupTree can perform computations specified by arbitrarily-shaped (but well-formed) trees, arbitrarily-defined properties and property-combining operations. Defaults are provided to simplify common cases (atomic numerical properties combined by summing), but functional programming techniques allow the caller to pass arbitrary update methods as required.

Despite its name, rollupTree can operate on directed acyclic graphs that are not trees if instructed to apply less stringent validation rules to its input.

## Installation

```{r eval = FALSE}
install.packages("rollupTree")
```

You can install the development version of rollupTree from [GitHub](https://github.com/) with:

```{r eval = FALSE}
# install.packages("pak")
pak::pak("jsjuni/rollupTree")
```

## Example

Suppose we have this data frame representing a work breakdown structure:

```{r echo = FALSE}
library(rollupTree)
wbs_table$work <- NULL
```
```{r}
library(rollupTree)
wbs_table
```

and this tree with edges representing child-parent relations in the breakdown:

```{r}
igraph::E(wbs_tree)
```
We can sum the budget numbers as follows:

```{r}
rollup(
  tree=wbs_tree,
  ds=wbs_table,
  update=function(d, t, s) update_df_prop_by_id(df=d, target=t, sources=s, prop="budget"),
  validate_ds=function(t, d) validate_df_by_id(tree=t, df=d, prop="budget")
)
```