Title: Hierarchical Methods for Differential Equations
Version: 1.2.1
Description: Wrapper for Stan that offers a number of in-built models to implement a hierarchical Bayesian longitudinal model for repeat observation data. Model choice selects the differential equation that is fit to the observations. Single and multi-individual models are available. O'Brien et al. (2024) <doi:10.1111/2041-210X.14463>.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.2
Biarch: true
Depends: R (≥ 4.1.0)
Imports: methods, dplyr, ggplot2, purrr, Rcpp (≥ 0.12.0), RcppParallel (≥ 5.0.1), rlang, rstan (≥ 2.18.1), rstantools (≥ 2.3.1.1)
LinkingTo: BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.18.1), StanHeaders (≥ 2.18.0)
SystemRequirements: GNU make
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0), withr, mnormt, here, patchwork, deSolve, cowplot, mixtools, MASS
VignetteBuilder: knitr
Config/testthat/edition: 3
LazyData: true
URL: https://traitecoevo.github.io/hmde/
BugReports: https://github.com/traitecoevo/hmde/issues
NeedsCompilation: yes
Packaged: 2025-06-30 03:03:43 UTC; tess
Author: Daniel Falster ORCID iD [aut, ctb], Tess O'Brien ORCID iD [aut, cre, cph], Fonti Kar ORCID iD [ctb], David Warton ORCID iD [aut, ctb]
Maintainer: Tess O'Brien <tess_obrien@fastmail.com>
Repository: CRAN
Date/Publication: 2025-07-04 19:20:06 UTC

The 'hmde' package.

Description

A package to implement a selection of hierarchical Bayesian longitudinal models for inverse Bayesian problems.

Author(s)

Maintainer: Tess O'Brien tess_obrien@fastmail.com (ORCID) [copyright holder]

Authors:

Other contributors:

References

Stan Development Team (NA). RStan: the R interface to Stan. R package version 2.26.23. https://mc-stan.org

See Also

Useful links:

Skink size data - Lampropholis delicata

Description

A subset of data from Kar, Nakagawa, and Noble (2024), used to model growth behaviour in a skink species. Observations are of the length from the tip of the nose to the start of the cloaca. Data was prepared by taking a simple random sample with replacement of 50 individual IDs among individuals with at least 5 observations each. Data was then transformed to conform to the needs of a model data set in the package.

Usage

Lizard_Size_Data

Format

Lizard_Size_Data

A data frame with 336 rows and 4 columns:

ind_id

ID number for individual

time

Days since first observation.

y_obs

Individual size in mm.

obs_index

Index of observations for individual

Source

https://osf.io/hjkxd/

Garcinia recondita - Barro Colorado Island data

Description

A subset of data from the Barro Colorado Island long term forest plot managed by the Smithsonian Tropical Research Institute (Condit et al. 2019). Data was prepared by taking a simple random sample without replacement of 30 individual IDs from Garcinia recondita. The sampling frame was restricted to individuals with 6 observations since 1990, and a difference between observed first and last sizes of more than 3cm in order to avoid identifiability issues. Data was then transformed and renamed to match the required structure to act as demonstration for the package.

Usage

Tree_Size_Data

Format

Tree_Size_Data

A data frame with 300 rows and 4 columns:

ind_id

ID number for individual

time

Years since first observation.

y_obs

Individual diameter at breast height (DBH) in centimetres.

obs_index

Index of observations for individual

Source

doi:10.15146/5xcp-0d46

References

doi:10.1002/ecy.4140

Garcinia recondita model estimates - Barro Colorado Island data

Description

Estimated sizes, individual growth parameters, and population-level hyper-parameters for Garcinia recondita fit with a Canham growth function hierarchical model. The data used to fit the model is the Tree_Size_Data object.

Usage

Tree_Size_Ests

Format

Tree_Size_Ests

A list with 5 elements:

model

A character string giving the model name - Canham with multiple individuals.

measurement_data

A tibble with 5 columns that gives information on size observations and estimates.

individual_data

A tibble with 13 columns that gives posterior estimates for individual growth parameters.

error_data

A tibble with 5 columns that gives posterior estimates of the error parameter.

population_data

A tibble with 5 columns that gives posterior estimates for population-level hyper-parameters.

SUSTAIN Salmo trutta data

Description

A subset of data from the SUSTAIN trout capture-recapture data set from Moe et al. (2020). Observations are of total body length in centimetres. Data prepared by taking a stratified sample of individual IDs based on the number of observations per individual: 25 individuals with 2 observations, 15 with 3, 10 with 4. Within the groups a simple random sample without replacement was used. Data was then transformed and renamed to match the required structure to act as demonstration for the package.

Usage

Trout_Size_Data

Format

Trout_Size_Data

A data frame with 135 rows and 4 columns:

ind_id

ID number for individual

time

Years since first capture and tagging of individual.

y_obs

Individual length in centimetres.

obs_index

Index of observations for individual

Source

doi:10.3897/BDJ.8.e52157

Differential equation for affine growth single individual model

Description

Differential equation for affine growth single individual model

Usage

hmde_affine_de(y = NULL, pars = NULL)

Arguments

y

input real

pars

list of parameters beta_0, beta_1

Value

value of differential equation at y

Assign data to template for chosen model

Description

Assign data to template for chosen model

Usage

hmde_assign_data(model_template, data = NULL, ...)

Arguments

model_template

output from hmde_model

data

Input data tibble with columns including time, y_obs, obs_index, and additionally ind_id for multi-individual models

...

data-masking name-value pairs allowing specific input of elements

Value

updated named list with your data assigned to Stan model parameters

Examples

# basic usage of hmde_assign_data
hmde_model("constant_single_ind") |> hmde_assign_data(Trout_Size_Data)

Differential equation for Canham growth single and multi- individual models

Description

Differential equation for Canham growth single and multi- individual models

Usage

hmde_canham_de(y = NULL, pars = NULL)

Arguments

y

input real

pars

list of parameters g_max, S_max, k

Value

value of differential equation at y

Differential equation for constant growth single and multi- individual models

Description

Differential equation for constant growth single and multi- individual models

Usage

hmde_const_de(y = NULL, pars = NULL)

Arguments

y

input real

pars

list of parameter beta

Value

value of differential equation at y

Extract samples and return measurement, individual, and population-level estimates

Description

Extract samples and return measurement, individual, and population-level estimates

Usage

hmde_extract_estimates(fit = NULL, input_measurement_data = NULL)

Arguments

fit

fitted model Stan fit

input_measurement_data

data used to fit the model with ind_id, y_obs, time, obs_index tibble

Value

named list with data frames for measurement, individual, population-level, and error parameter estimates

Examples

# basic usage of hmde_extract_estimates
hmde_model("constant_single_ind") |>
  hmde_assign_data(Trout_Size_Data)|>
  hmde_run(chains = 1, iter = 1000,
           verbose = FALSE, show_messages = FALSE) |>
  hmde_extract_estimates(Trout_Size_Data)

Select data configuration template for hmde supported model

Description

Select data configuration template for hmde supported model

Usage

hmde_model(model = NULL)

Arguments

model

model name character string

Value

named list that matches Stan model parameters

Examples

# basic usage of hmde_model
hmde_model("constant_single_ind")

Function to select DE given model name

Description

Function to select DE given model name

Usage

hmde_model_des(model = NULL)

Arguments

model

character string model name

Value

DE function corresponding to specific model

Examples

# basic usage of hmde_model_des
hmde_model_des("constant_single_ind")

Returns names of available models.

Description

Returns names of available models.

Usage

hmde_model_names()

Value

vector of character strings for model names.

Examples

# basic usage of hmde_model_names
hmde_model_names()

Show parameter list for hmde supported model

Description

Show parameter list for hmde supported model

Usage

hmde_model_pars(model = NULL)

Arguments

model

model name character string

Value

named list that matches Stan model parameters

Examples

# basic usage of hmde_model_pars
hmde_model_pars("constant_single_ind")

Plot pieces of chosen differential equation model for each individual. Structured to take the individual data tibble that is built by the hmde_extract_estimates function using the ind_par_name_mean estimates. Function piece will go from the first fitted size to the last. Accepted ggplot arguments will change the axis labels, title, line colour, alpha

Description

Plot pieces of chosen differential equation model for each individual. Structured to take the individual data tibble that is built by the hmde_extract_estimates function using the ind_par_name_mean estimates. Function piece will go from the first fitted size to the last. Accepted ggplot arguments will change the axis labels, title, line colour, alpha

Usage

hmde_plot_de_pieces(
  estimate_list = NULL,
  xlab = "Y(t)",
  ylab = "f",
  title = NULL,
  colour = "#006600",
  alpha = 0.4
)

Arguments

estimate_list

list output from hmde_extract_estimates

xlab

character string for replacement x axis label

ylab

character string for replacement y axis label

title

character string for replacement plot title

colour

character string for replacement line colour

alpha

real number for replacement alpha value

Value

ggplot object

Examples

# basic usage of hmde_plot_de_pieces
hmde_plot_de_pieces(estimate_list = Tree_Size_Ests)

Plot estimated and observed values over time for a chosen number of individuals based on posterior estimates. Structured to take in the measurement_data tibble constructed by the hmde_extract_estimates function.

Description

Plot estimated and observed values over time for a chosen number of individuals based on posterior estimates. Structured to take in the measurement_data tibble constructed by the hmde_extract_estimates function.

Usage

hmde_plot_obs_est_inds(
  estimate_list = NULL,
  measurement_data = NULL,
  ind_id_vec = NULL,
  n_ind_to_plot = NULL,
  xlab = "Time",
  ylab = "Y(t)",
  title = NULL
)

Arguments

estimate_list

list output of hmde_extract_estimates

measurement_data

tibble with estimated measurements

ind_id_vec

vector with list of ind_id values

n_ind_to_plot

integer giving number of individuals to plot if not specified

xlab

character string for replacement x axis label

ylab

character string for replacement y axis label

title

character string for replacement plot title

Value

ggplot object

Examples

# basic usage of hmde_plot_obs_est_inds
hmde_plot_obs_est_inds(estimate_list = Tree_Size_Ests,
                       n_ind_to_plot = 5)

Run chosen pre-built model in Stan

Description

Run chosen pre-built model in Stan

Usage

hmde_run(model_template, ...)

Arguments

model_template

model template generated by hmde_model and updated by hmde_assign_data

...

additional arguments passed to rstan::sampling

Value

Stanfit model output

Examples

# basic usage of hmde_run
hmde_model("constant_single_ind") |>
  hmde_assign_data(Trout_Size_Data)|>
  hmde_run(chains = 1, iter = 1000,
           verbose = FALSE, show_messages = FALSE)

Differential equation for von Bertalanffy growth single and multi- individual models

Description

Differential equation for von Bertalanffy growth single and multi- individual models

Usage

hmde_vb_de(y = NULL, pars = NULL)

Arguments

y

input real

pars

list of parameters Y_max, growth_rate

Value

value of differential equation at y