Title: Hierarchical Methods for Differential Equations
Version: 1.4.0
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.3
Biarch: true
Depends: R (≥ 4.1.0)
Imports: methods, dplyr, ggplot2, Rcpp (≥ 0.12.19), RcppParallel (≥ 5.0.1), rlang, rstan (≥ 2.18.1), rstantools (≥ 2.3.1.1), tibble, cowplot, knitr, purrr (≥ 1.2.0)
LinkingTo: BH (≥ 1.66.0), Rcpp (≥ 0.12.19), RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.18.1), StanHeaders (≥ 2.18.0)
SystemRequirements: GNU make
Suggests: rmarkdown, testthat (≥ 3.0.0), withr, mnormt, here, patchwork, deSolve, 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: 2026-05-04 04:07:50 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: 2026-05-04 04:50:02 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

Estimates object of class hmde_estimates for Canham fit. Contains 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 hmde_estimates object:

model_name

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

model_level

A character string stating that the model is fit to multiple individuals.

method

A character string stating that the model was fit with MCMC sampling.

runtime

A matrix giving the runtime of each chain.

fit_summary

A character string summarising the model fitting.

measurement_ests

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

individual_ests

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

population_ests

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

error_ests

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

prior_pars

A list contianing details of the prior parameters used for the model fit.

par_names

A list containing the names of estimated parameters at each level of the hierarchical model.

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

generic error_ests getter

Description

generic error_ests getter

generic error_ests setter

Usage

error_ests(x)

error_ests(x) <- value

Arguments

x

hmde_estimates class object

value

tibble of error parameter estimates

generic fit_summary getter

Description

generic fit_summary getter

generic fit_summary setter

Usage

fit_summary(x)

fit_summary(x) <- value

Arguments

x

hmde_estimates class object

value

character string description of fit

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

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

hmde_data_template class An S4 class to prepare input data for a hmde model.

Description

Validation function for hmde_data_template class.

Usage

## S4 method for signature 'hmde_data_template'
model_name(x)

## S4 replacement method for signature 'hmde_data_template'
model_name(x) <- value

## S4 method for signature 'hmde_data_template'
model_level(x)

## S4 replacement method for signature 'hmde_data_template'
model_level(x) <- value

## S4 method for signature 'hmde_data_template'
obs_data(x)

## S4 replacement method for signature 'hmde_data_template'
obs_data(x) <- value

## S4 method for signature 'hmde_data_template'
prior_pars(x)

## S4 replacement method for signature 'hmde_data_template'
prior_pars(x) <- value

## S4 method for signature 'hmde_data_template'
par_names(x)

## S4 replacement method for signature 'hmde_data_template'
par_names(x) <- value

hmde_data_template(
  model_name,
  obs_data = NULL,
  prior_pars = NULL,
  model_level = NA_character_,
  ...
)

## S4 method for signature 'hmde_data_template'
show(object)

## S4 method for signature 'hmde_data_template'
print(x)

## S4 method for signature 'hmde_data_template'
summary(object)

## S4 method for signature 'hmde_data_template,ANY'
plot(x)

Arguments

x

hmde_data_template class object

value

list

model_name

character string name of a hmde model

obs_data

list or tibble containing observational data vectors

prior_pars

list containing prior parameters

model_level

character string specifying whether single or multiple inds

...

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

object

hmde_data_template class object

Value

hmde_data_template class object

Slots

model_name

character string

model_level

character string

obs_data

list of input data

prior_pars

list of prior parameters

par_names

list of model paramter names at each level

Examples

# basic usage of hmde_data_template
hmde_data_template("constant_single_ind")

# basic usage of hmde_data_template with data input
hmde_data_template("constant_single_ind",
  obs_data = list(
    n_obs = 3,
    y_obs = c(1,1,1),
    obs_index = 1:3,
    time = 0:2
  )
)

#basic usage of hmde_data_template with prior input
hmde_data_template("constant_single_ind",
  prior_pars = list(
    prior_pars_ind_beta = c(1,2),
    prior_pars_global_error_sigma = c(1,3)
  )
)

hmde_estimates class An S4 class to contain model information and parameter estimates for a hmde model.

Description

Validator function for hmde_estimates class objects.

Usage

## S4 method for signature 'hmde_estimates'
model_name(x)

## S4 replacement method for signature 'hmde_estimates'
model_name(x) <- value

## S4 method for signature 'hmde_estimates'
model_level(x)

## S4 replacement method for signature 'hmde_estimates'
model_level(x) <- value

## S4 method for signature 'hmde_estimates'
method(x)

## S4 replacement method for signature 'hmde_estimates'
method(x) <- value

## S4 method for signature 'hmde_estimates'
runtime(x)

## S4 replacement method for signature 'hmde_estimates'
runtime(x) <- value

## S4 method for signature 'hmde_estimates'
fit_summary(x)

## S4 replacement method for signature 'hmde_estimates'
fit_summary(x) <- value

## S4 method for signature 'hmde_estimates'
measurement_ests(x)

## S4 replacement method for signature 'hmde_estimates'
measurement_ests(x) <- value

## S4 method for signature 'hmde_estimates'
individual_ests(x)

## S4 replacement method for signature 'hmde_estimates'
individual_ests(x) <- value

## S4 method for signature 'hmde_estimates'
population_ests(x)

## S4 replacement method for signature 'hmde_estimates'
population_ests(x) <- value

## S4 method for signature 'hmde_estimates'
error_ests(x)

## S4 replacement method for signature 'hmde_estimates'
error_ests(x) <- value

## S4 method for signature 'hmde_estimates'
prior_pars(x)

## S4 replacement method for signature 'hmde_estimates'
prior_pars(x) <- value

## S4 method for signature 'hmde_estimates'
par_names(x)

## S4 replacement method for signature 'hmde_estimates'
par_names(x) <- value

hmde_estimates(fit, obs_data)

## S4 method for signature 'hmde_estimates'
show(object)

## S4 method for signature 'hmde_estimates'
print(x)

## S4 method for signature 'hmde_estimates'
summary(object)

## S4 method for signature 'hmde_estimates,ANY'
plot(x)

Arguments

x

hmde_estimates class object

value

vector

fit

stanfit class object

obs_data

tbl_df class object with variables for ind_id, time, y_obs

object

hmde_estimates object to be validated

Value

hmde_estimates class object

Slots

model_name

name of the hmde model

model_level

whether the model functions at the single or multi-ind level

method

sampling method eg. MCMC

runtime

matrix of chain runtime

fit_summary

description of the fit

measurement_ests

tibble of measurement-level estimates

individual_ests

tibble of individual-level estimates

population_ests

list of population_level estimates

error_ests

tibble of error parameter estimates

prior_pars

list of prior parameters

par_names

list of model paramter names at each level

Examples

# basic usage of hmde_estimates
hmde_data_template("constant_single_ind",
                   obs_data = Trout_Size_Data[1:4,]) |>
  hmde_run(chains = 1, iter = 1000,
           verbose = FALSE, show_messages = FALSE) |>
  hmde_estimates(obs_data = Trout_Size_Data[1:4,])

Calculate Rhat statistics for a hmde_fit object

Description

Calculate Rhat statistics for a hmde_fit object

Usage

hmde_extract_Rhat(fit)

Arguments

fit

hmde_fit fitted model object, output of hmde_run

Value

named vector of Rhat values

Examples

# basic usage of hmde_extract_Rhat
hmde_data_template("constant_single_ind",
                   obs_data = Trout_Size_Data[1:4,])|>
  hmde_run(chains = 2, iter = 1000,
           verbose = FALSE, show_messages = FALSE) |>
  hmde_extract_Rhat()

helper function for hmde_data_template that provides data structure for model, Also used to guide the user on the required structure for the model they want.

Description

helper function for hmde_data_template that provides data structure for model, Also used to guide the user on the required structure for the model they want.

Usage

hmde_model(model = NULL)

Arguments

model

model name character string

Value

hmde_data_template class that suits Stan model input

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 histogram of R_hat values for hmde_fit object.

Description

Plot histogram of R_hat values for hmde_fit object.

Usage

hmde_plot_Rhat_hist(fit)

Arguments

fit

hmde_fit object output from hmde_run

Value

ggplot object

Examples

# basic usage of hmde_plot_Rhat_hist
hmde_data_template("constant_single_ind",
  Trout_Size_Data[1:4,]) |>
  hmde_run(chains = 2, iter = 1000,
           verbose = FALSE, show_messages = FALSE) |>
  hmde_plot_Rhat_hist()

Plot pieces of chosen differential equation model for each individual. Structured to take the individual data tibble that is built by the hmde_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_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(
  estimates = NULL,
  xlab = "Y(t)",
  ylab = "f",
  title = NULL,
  colour = "#006600",
  alpha = 0.4
)

Arguments

estimates

hmde_estimates object

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(estimates = 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(
  estimates = NULL,
  ind_id_vec = NULL,
  n_ind_to_plot = NULL,
  xlab = "Time",
  ylab = "Y(t)",
  title = NULL
)

Arguments

estimates

hmde_estimates class object

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(estimates = 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(data_template, ...)

Arguments

data_template

hmde_data_template class object

...

additional arguments passed to rstan::sampling

Value

Stanfit S4 object

Examples

# basic usage of hmde_run
hmde_data_template("constant_single_ind",
                   obs_data = Trout_Size_Data[1:4,]) |>
  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

generic individual_ests getter

Description

generic individual_ests getter

generic individual-ests setter

Usage

individual_ests(x)

individual_ests(x) <- value

Arguments

x

hmde_estimates class object

value

tibble of individaul-level parameter estimates

generic measurement_ests getter

Description

generic measurement_ests getter

generic measurement_ests setter

Usage

measurement_ests(x)

measurement_ests(x) <- value

Arguments

x

hmde_estimates class object

value

tibble of measurement-level estimates

generic method getter

Description

generic method getter

generic method setter

Usage

method(x)

method(x) <- value

Arguments

x

hmde_estimates class object

value

character string name of object

generic model_level setter

Description

generic model_level setter

generic model_level setter

generic obs_data setter

generic obs_data setter

Usage

model_level(x)

model_level(x) <- value

obs_data(x)

obs_data(x) <- value

Arguments

x

hmde hmde_data_template

value

character string

generic model_name getter

Description

generic model_name getter

generic model_name setter

Usage

model_name(x)

model_name(x) <- value

Arguments

x

hmde special class object

value

character string

generic par_names getter

Description

generic par_names getter

generic par_names setter

Usage

par_names(x)

par_names(x) <- value

Arguments

x

hmde special class object

value

vector of parameter names

generic population_ests setter

Description

generic population_ests setter

generic population_ests setter

Usage

population_ests(x)

population_ests(x) <- value

Arguments

x

hmde_estimates class object

value

tibble of population-level estimates

generic prior_pars getter

Description

generic prior_pars getter

generic prior_pars setter

Usage

prior_pars(x)

prior_pars(x) <- value

Arguments

x

hmde special class object

value

list of prior parameters

generic runtime getter

Description

generic runtime getter

generic runtime setter

Usage

runtime(x)

runtime(x) <- value

Arguments

x

hmde_estimates class object

value

matrix of chains for runtimes