Package 'hmde'

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:

• Daniel Falster [email protected] (ORCID) [contributor]

• David Warton [email protected] (ORCID) [contributor]

Other contributors:

• Fonti Kar [email protected] (ORCID) [contributor]

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:

• https://traitecoevo.github.io/hmde/

• Report bugs at https://github.com/traitecoevo/hmde/issues

---

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

---

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

---

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

---

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

---

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/

---

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

---

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

---