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.
You can install the development version of equationer
from
GitHub with the following procedure:
# install.packages("devtools")
devtools::install_github("UBESP-DCTV/equationer")
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>
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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.