In UBESP-DCTV/equationer: Equations of Energy Requirements

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
library(DT)

equationer

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
eq2
eq3

eq9

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)
evaluate_at(eq1, age = 35, bmi = 18)
evaluate_at(eq9, age = 35, bmi = 18, weight = 84)

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

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)

# enough values, no filter
evaluate_at(eqs1, age = 38, bmi = 18)

# more values, no filter
evaluate_at(eqs1, age = 38, bmi = 18, weight = 81, height = 184)

# filter by a strata level
evaluate_at(eqs1, age = 38, bmi = 18, sex = "female")

# filter by a strata nonexistent level
evaluate_at(eqs1, age = 38, bmi = 18, sex = "unknown")

# Ask only for a specific outcome (please note the DOT)
evaluate_at(eqs2, age = 38, weight = 81, .outcome = "kcal/day")

# Ask only for a specific nonexistent outcome
evaluate_at(eqs2, age = 38, weight = 81, .outcome = "kcal")

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

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"
)

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

evaluate_at(bag1, one_patient)



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

evaluate_at(bag1, more_patients)

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.