Package 'hmde'

Title: Hierarchical Methods for Differential Equations
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.
Authors: Daniel Falster [aut, ctb] , Tess O'Brien [aut, cre, cph] (XXXX-XXXX-XXXX-XXXX), Fonti Kar [ctb] , David Warton [aut, ctb]
Maintainer: Tess O'Brien <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2024-12-10 01:36:37 UTC
Source: https://github.com/traitecoevo/hmde

Help Index

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 [email protected] (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

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

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 parametera 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(model = NULL, fit = NULL, input_measurement_data = NULL)

Arguments

model

model name character string
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

Differential equation for linear growth single individual model

Description

Differential equation for linear growth single individual model

Usage

hmde_linear_de(y = NULL, pars = NULL)

Arguments

y

input real
pars

list of parameters beta_0, beta_1

Value

value of differential equation at y

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

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

Returns names of available models.

Description

Returns names of available models.

Usage

hmde_model_names()

Value

vector of character strings for 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

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(
  model = NULL,
  individual_data = NULL,
  measurement_data = NULL,
  xlab = "Y(t)",
  ylab = "f",
  title = NULL,
  colour = "#006600",
  alpha = 0.4
)

Arguments

model

model name character string
individual_data

tibble with estimated DE parameters
measurement_data

tibble with estimated measurements
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

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

Arguments

ind_id_vec

vector with list of ind_id values
n_ind_to_plot

integer giving number of individuals to plot if not speciried
measurement_data

tibble with estimated measurements
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

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

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 parameteters Y_max, growth_rate

Value

value of differential equation at y

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

https://doi.org/10.15146/5xcp-0d46

References

https://doi.org/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 4 elements:

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

https://doi.org/10.3897/BDJ.8.e52157