README.md

equationer

Build
Status Coverage
status

lifecycle CRAN
status

The goal of the package equationer is to implement an environment to consistently generate the estimations from the equations reported in the paper “Review of Equations of Energy Requirements” by the Unit of Biostatistics, Epidemiology and Public Health of the University of Padova.

Installation

You can install the development version of equationer from GitHub with the following procedure:

# install.packages("devtools")
devtools::install_github("UBESP-DCTV/equationer")

Hot to use it

library(equationer)

First of all define some equations. Please note that equations must be named and that equations’ names must be different each other. Moreover, you have to supply strata as a named list defining in each equation which level of the strata it consider. Note that strata levels can be of different class inside an equation (e.g. character, numeric, …) but, obviously, you cannot provide multiple strata with the same name or a strata with more than one level in each equation.

eq1 <- eq(age = 0.3, bmi = -0.5, name = "eq-1", outcome = "kcal/day",
    strata = list(sex = "male", nyha = 1)
)
eq2 <- eq(age = 0.5, bmi = -0.3, name = "eq-2", outcome = "kcal/day",
    strata = list(sex = "female", nyha = 1)
)
eq3 <- eq(age = -0.3, bmi = 0.5, name = "eq-3", outcome = "kcal/day",
    strata = list(sex = "male", nyha = 2)
)
eq4 <- eq(age = -0.5, bmi = 0.3, name = "eq-4", outcome = "kcal/day",
    strata = list(sex = "female", nyha = 2)
)


eq9 <- eq(age = -0.1, weight = 0.2, name = "eq-9", outcome = "kcal/month",
    strata = list(sex = "female")
)
eq10 <- eq(age = -0.2, weight = 0.1, name = "eq-10", outcome = "kcal/month",
    strata = list(sex = "male")
)
eq11 <- eq(age = 0.1, weight = -0.2, name = "eq-11", outcome = "kcal/day",
    strata = list(sex = "female")
)
eq12 <- eq(age = 0.2, weight = -0.2, name = "eq-12", outcome = "kcal/day",
    strata = list(sex = "male")
)

When you visualize an equation the main characteristics will be highlighted

eq1
#> 
#> ● Equation 'eq-1': kcal/day = 0.3 age + -0.5 bmi
#> Strata: sex = 'male'
#> Strata: nyha = 1
eq2
#> 
#> ● Equation 'eq-2': kcal/day = 0.5 age + -0.3 bmi
#> Strata: sex = 'female'
#> Strata: nyha = 1
eq3
#> 
#> ● Equation 'eq-3': kcal/day = -0.3 age + 0.5 bmi
#> Strata: sex = 'male'
#> Strata: nyha = 2

eq9
#> 
#> ● Equation 'eq-9': kcal/month = -0.1 age + 0.2 weight
#> Strata: sex = 'female'

We can evaluate an equation providing (in a natural non quoted language) the values for each . Please note that we have to provide “at least” the covariate included in the equation (or we get an error that tell us which ones we have missed). If we provide more covariates than the ones included in the equation it does not matter for the resulting estimation and its value will be returned in the output data frame too.

evaluate_at(eq1, age = 35)
#> ✖ Covariate(s) missing: 'bmi'
#> Error: Not all equation's covariates are included in the set supplied.
evaluate_at(eq1, age = 35, bmi = 18)
#> # A tibble: 1 x 7
#>     age   bmi sex    nyha outcome  estimation eq_name
#>   <dbl> <dbl> <chr> <dbl> <chr>         <dbl> <chr>  
#> 1    35    18 male      1 kcal/day        1.5 eq-1
evaluate_at(eq9, age = 35, bmi = 18, weight = 84)
#> # A tibble: 1 x 6
#>     age weight sex    outcome    estimation eq_name
#>   <dbl>  <dbl> <chr>  <chr>           <dbl> <chr>  
#> 1    35     84 female kcal/month       13.3 eq-9

Equations must be aggregated in group, basically because the strata which cannot suit well in maths: i.e. each different combination of strata (i.e. categorical level) there is an equation. For consistency, even single equation with no strata must be grouped in a group (singleton). Even for the groups of equations we have to provide (distinct) names for each group. Moreover, you can optionally associate a reference (i.e. a single character string) to groups.

When we print a group, a summary of the characteristics were shown including each equation itself

eqs1 <- eqs(eq1, eq2, eq3, eq4, name = "eqs-a", reference = "ref-a")
eqs2 <- eqs(eq9, eq10, eq11, eq12, name = "eqs-b", reference = "ref-b")

eqs1
#> 
#> Equations group 'eqs-a':
#> 
#> Strata sex w/ levels: 'female', 'male'
#> Strata nyha w/ levels: '1', '2'
#> 
#> 
#> ● Equation 'eq-1': kcal/day = 0.3 age + -0.5 bmi
#> Strata: sex = 'male'
#> Strata: nyha = 1
#> 
#> 
#> ● Equation 'eq-2': kcal/day = 0.5 age + -0.3 bmi
#> Strata: sex = 'female'
#> Strata: nyha = 1
#> 
#> 
#> ● Equation 'eq-3': kcal/day = -0.3 age + 0.5 bmi
#> Strata: sex = 'male'
#> Strata: nyha = 2
#> 
#> 
#> ● Equation 'eq-4': kcal/day = -0.5 age + 0.3 bmi
#> Strata: sex = 'female'
#> Strata: nyha = 2
#> 
#> 
#> Main reference: 'ref-a'

We can evaluate a group of equation all together as it is a single one. We will get a data frame of results with one row each possible equation. Possible equation were decided with respect to the outcome requested (default all the possible one), i.e. if some equation in a group cannot provide an outcome, clearly those equation will not evaluate it. At the same time we can considered for the evaluation only equations which assume particular level of some strata. In this case if we ask for a stratum to assume a level it does not have nothing will be computed (anyway the resulting object still a data frame of zero rows, for consistency of the output class). On the other hand if we ask for a strata that does not exist at all in the equation in the group it will be ignored in the computation and the level selected will be reported in the output data frame.

# not enough values
evaluate_at(eqs1, age = 38)
#> ✖ Covariate(s) missing: 'bmi'
#> Error: Not all equation's covariates are included in the set supplied.

# enough values, no filter
evaluate_at(eqs1, age = 38, bmi = 18)
#> # A tibble: 4 x 9
#>     age   bmi sex     nyha outcome  estimation eq_name eq_group reference
#>   <dbl> <dbl> <chr>  <dbl> <chr>         <dbl> <chr>   <chr>    <chr>    
#> 1    38    18 male       1 kcal/day        2.4 eq-1    eqs-a    ref-a    
#> 2    38    18 female     1 kcal/day       13.6 eq-2    eqs-a    ref-a    
#> 3    38    18 male       2 kcal/day       -2.4 eq-3    eqs-a    ref-a    
#> 4    38    18 female     2 kcal/day      -13.6 eq-4    eqs-a    ref-a

# more values, no filter
evaluate_at(eqs1, age = 38, bmi = 18, weight = 81, height = 184)
#> # A tibble: 4 x 9
#>     age   bmi sex     nyha outcome  estimation eq_name eq_group reference
#>   <dbl> <dbl> <chr>  <dbl> <chr>         <dbl> <chr>   <chr>    <chr>    
#> 1    38    18 male       1 kcal/day        2.4 eq-1    eqs-a    ref-a    
#> 2    38    18 female     1 kcal/day       13.6 eq-2    eqs-a    ref-a    
#> 3    38    18 male       2 kcal/day       -2.4 eq-3    eqs-a    ref-a    
#> 4    38    18 female     2 kcal/day      -13.6 eq-4    eqs-a    ref-a

# filter by a strata level
evaluate_at(eqs1, age = 38, bmi = 18, sex = "female")
#> # A tibble: 2 x 9
#>     age   bmi sex     nyha outcome  estimation eq_name eq_group reference
#>   <dbl> <dbl> <chr>  <dbl> <chr>         <dbl> <chr>   <chr>    <chr>    
#> 1    38    18 female     1 kcal/day       13.6 eq-2    eqs-a    ref-a    
#> 2    38    18 female     2 kcal/day      -13.6 eq-4    eqs-a    ref-a

# filter by a strata nonexistent level
evaluate_at(eqs1, age = 38, bmi = 18, sex = "unknown")
#> Warning: Some strata's levels requested are not included in the equations in
#> eqs-a. They won't be evaluated.
#> ✖ Values 'unknown' is not present in the sex's strata possible levels.
#> ● Possible values for sex are: 'female', 'male'.
#> # A tibble: 0 x 9
#> # … with 9 variables: age <dbl>, bmi <dbl>, sex <fct>, nyha <fct>,
#> #   outcome <chr>, estimation <dbl>, eq_name <chr>, eq_group <chr>,
#> #   reference <chr>

# Ask only for a specific outcome (please note the DOT)
evaluate_at(eqs2, age = 38, weight = 81, .outcome = "kcal/day")
#> # A tibble: 2 x 8
#>     age weight sex    outcome  estimation eq_name eq_group reference
#>   <dbl>  <dbl> <chr>  <chr>         <dbl> <chr>   <chr>    <chr>    
#> 1    38     81 female kcal/day     -12.4  eq-11   eqs-b    ref-b    
#> 2    38     81 male   kcal/day      -8.60 eq-12   eqs-b    ref-b

# Ask only for a specific nonexistent outcome
evaluate_at(eqs2, age = 38, weight = 81, .outcome = "kcal")
#> Warning: Only equations with possible outcome (if any) will be considered for
#> 'eqs-b'.
#> ✖ Outcome 'kcal' is not present in the equations eqs-b
#> ● Possible outcomes are: 'kcal/month', 'kcal/day'.
#> # A tibble: 0 x 8
#> # … with 8 variables: age <dbl>, weight <dbl>, sex <fct>, outcome <chr>,
#> #   estimation <dbl>, eq_name <chr>, eq_group <chr>, reference <chr>

Finally, a bag of (grouped) equations can be created to have a complete bag!

bag1 <- eqs_bag(eqs1, eqs2, name = "ubesp19",
    reference = "DG et.al 2019"
)

bag1
#> 
#> Equations bag 'ubesp19' (last update `2020-07-08`)
#> 
#> Variable included: 'age', 'bmi', 'weight'
#> Strata: sex w/ levels: 'female', 'male'
#> Strata: nyha w/ levels: 1, 2
#> Outcome considered: 'kcal/day', 'kcal/month'
#> Number of equation groups: 2
#> Overall numeber of equations: 8
#> 
#> Main reference: 'DG et.al 2019'

For a complete bag (which is supposed to be quite huge) we can ask an estimation both by providing directly the covariates value (i.e. one patient by one patient), and by passing the information (of one or more patients) using a data frame! In the latter case, a column which keep track of the original row in the sourced dataframe will be added

evaluate_at(bag1,
    age = 35, bmi = 18, weight = 81, sex = "female"
)
#> Warning: Only equations with possible outcome (if any) will be considered for
#> 'eqs-a'.
#> ✖ Outcome 'kcal/month' is not present in the equations eqs-a
#> ● Possible outcomes are: 'kcal/day'.
#> # A tibble: 4 x 10
#>     age   bmi sex     nyha outcome  estimation eq_name eq_group reference weight
#>   <dbl> <dbl> <chr>  <dbl> <chr>         <dbl> <chr>   <chr>    <chr>      <dbl>
#> 1    35    18 female     1 kcal/day       12.1 eq-2    eqs-a    ref-a         NA
#> 2    35    18 female     2 kcal/day      -12.1 eq-4    eqs-a    ref-a         NA
#> 3    35    NA female    NA kcal/mo…       12.7 eq-9    eqs-b    ref-b         81
#> 4    35    NA female    NA kcal/day      -12.7 eq-11   eqs-b    ref-b         81

one_patient <- dplyr::tribble(
    ~age, ~bmi, ~weight,     ~sex,
      35,   18,      81,  "female"
)

evaluate_at(bag1, one_patient)
#> Warning: Only equations with possible outcome (if any) will be considered for
#> 'eqs-a'.
#> ✖ Outcome 'kcal/month' is not present in the equations eqs-a
#> ● Possible outcomes are: 'kcal/day'.
#> # A tibble: 4 x 10
#>     age   bmi sex     nyha outcome  estimation eq_name eq_group reference weight
#>   <dbl> <dbl> <chr>  <dbl> <chr>         <dbl> <chr>   <chr>    <chr>      <dbl>
#> 1    35    18 female     1 kcal/day       12.1 eq-2    eqs-a    ref-a         NA
#> 2    35    18 female     2 kcal/day      -12.1 eq-4    eqs-a    ref-a         NA
#> 3    35    NA female    NA kcal/mo…       12.7 eq-9    eqs-b    ref-b         81
#> 4    35    NA female    NA kcal/day      -12.7 eq-11   eqs-b    ref-b         81



more_patients <- dplyr::tribble(
    ~age, ~bmi, ~weight,     ~sex,
      35,   18,      81,  "female",
      27,   20,      93,    "male"
)

evaluate_at(bag1, more_patients)
#> Warning: Only equations with possible outcome (if any) will be considered for
#> 'eqs-a'.
#> ✖ Outcome 'kcal/month' is not present in the equations eqs-a
#> ● Possible outcomes are: 'kcal/day'.
#> Warning: Only equations with possible outcome (if any) will be considered for
#> 'eqs-a'.
#> ✖ Outcome 'kcal/month' is not present in the equations eqs-a
#> ● Possible outcomes are: 'kcal/day'.
#> # A tibble: 8 x 11
#>     age   bmi sex    nyha outcome estimation eq_name eq_group reference weight
#>   <dbl> <dbl> <chr> <dbl> <chr>        <dbl> <chr>   <chr>    <chr>      <dbl>
#> 1    35    18 fema…     1 kcal/d…       12.1 eq-2    eqs-a    ref-a         NA
#> 2    35    18 fema…     2 kcal/d…      -12.1 eq-4    eqs-a    ref-a         NA
#> 3    35    NA fema…    NA kcal/m…       12.7 eq-9    eqs-b    ref-b         81
#> 4    35    NA fema…    NA kcal/d…      -12.7 eq-11   eqs-b    ref-b         81
#> 5    27    20 male      1 kcal/d…       -1.9 eq-1    eqs-a    ref-a         NA
#> 6    27    20 male      2 kcal/d…        1.9 eq-3    eqs-a    ref-a         NA
#> 7    27    NA male     NA kcal/m…        3.9 eq-10   eqs-b    ref-b         93
#> 8    27    NA male     NA kcal/d…      -13.2 eq-12   eqs-b    ref-b         93
#> # … with 1 more variable: .source_row <int>

Code of Conduct

Please note that the equationer project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.



UBESP-DCTV/equationer documentation built on Jan. 17, 2021, 6:30 p.m.