Package 'biodosetools'

Title: An R Shiny Application for Biological Dosimetry
Description: A tool to perform all different statistical tests and calculations needed by Biological Dosimetry Laboratories. Detailed documentation is available in <https://biodosetools-team.github.io/documentation/> and the paper by Hernández et al. (2023) <doi:10.1080/09553002.2023.2176564>.
Authors: Alfredo Hernández [aut, cre] , David Endesfelder [aut], Pere Puig [aut]
Maintainer: Alfredo Hernández <[email protected]>
License: GPL-3
Version: 3.6.1.9000
Built: 2025-02-23 05:34:16 UTC
Source: https://github.com/biodosetools-team/biodosetools

Help Index

Calculate AIC (Akaike's 'An Information Criterion')

Description

Calculate AIC (Akaike's 'An Information Criterion')

Usage

AIC_from_data(
  general_fit_coeffs,
  data,
  dose_var = "dose",
  yield_var = "yield",
  fit_link = "identity"
)

Arguments

general_fit_coeffs

Generalised fit coefficients matrix.
data

Data (dose, yield) to calculate AIC from.
dose_var

Name of the dose variable (enquoted).
yield_var

Name of the yield variable (enquoted).
fit_link

A specification for the model link function.

Value

Numeric value of AIC.

biodosetools package

Description

Shiny App To Be Used By Biological Dosimetry Laboratories

Details

See the README on GitHub

Aberration calculation functions

Description

Aberration calculation functions

Usage

calculate_aberr_power(data, aberr_prefix = "C", power = 1)

calculate_aberr_mean(X, N)

calculate_aberr_var(X, X2, N)

calculate_aberr_disp_index(mean, var)

calculate_aberr_u_value(X, N, mean, var, assessment_u = 1)

init_aberr_table(
  data,
  type = c("count", "case"),
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

data

Count or case data.
aberr_prefix

Prefix of the aberrations in the data.
power

Power of aberration.
X

Sum of detected aberrations.
N

Number of cells analysed.
X2

Quadratic sum of detected aberrations.
mean

Mean.
var

Variance.
assessment_u

Expected uu-value of the assessment. For a Poisson distribution this should be unity.
type

Type of input data. Either "count" and "case".
aberr_module

Aberration module.

Calculate aberrations table

Description

Calculate aberrations table

Usage

calculate_aberr_table(
  data,
  type = c("count", "case"),
  aberr_module = c("dicentrics", "translocations", "micronuclei"),
  assessment_u = 1
)

Arguments

data

Count or case data.
type

Type of input data. Either "count" and "case".
aberr_module

Aberration module, required for type = "case".
assessment_u

Expected uu-value of the assessment. For a Poisson distribution this should be unity.

Value

Data frame containing cell count (NN), aberrations (XX), and other coefficients (dispersion index, uu-value, ...), as well as raw count or case data.

Calculate characteristic limits

Description

Calculate characteristic limits

Usage

calculate_characteristic_limits(mu0, n1, alpha = 0.05, beta = 0.1)

Arguments

mu0

Background rate
n1

Number of cells that will be analysed.
alpha

Type I error rate, 0.05 by default.
beta

Type II error rate, 0.1 by default.

Value

List of characteristic limits (decision_threshold, detection_limit).

Calculate genomic conversion factor

Description

Method based on the paper by Lucas, J. N. et al. (1992). Rapid Translocation Frequency Analysis in Humans Decades after Exposure to Ionizing Radiation. International Journal of Radiation Biology, 62(1), 53-63. <doi:10.1080/09553009214551821>.

Usage

calculate_genome_factor(dna_table, chromosomes, colors, sex)

Arguments

dna_table

DNA content fractions table. Can be dna_content_fractions_morton or dna_content_table_ihgsc.
chromosomes

Vector of stained chromosomes.
colors

Vector of colors of the stains.
sex

Sex of the individual.

Value

Numeric value of genomic conversion factor.

Calculate model statistics

Description

Calculate model statistics

Usage

calculate_model_stats(
  model_data,
  fit_coeffs_vec,
  glm_results = NULL,
  fit_algorithm = NULL,
  response = "yield",
  link = c("identity", "log"),
  type = c("theory", "raw"),
  Y = NULL,
  mu = NULL,
  n = NULL,
  npar = NULL,
  genome_factor = NULL,
  calc_type = c("fitting", "estimation")
)

Arguments

model_data

Data of the model.
fit_coeffs_vec

Vector of fitting coefficients.
glm_results

Results of glm.
fit_algorithm

String of the algorithm used.
response

Type of response.
link

Fit link.
type

Theoretical or raw glm model statistics.
Y

Y response (required in constraint-maxlik-optimization).
mu

mu response required in constraint-maxlik-optimization).
n

number of parameters (required in constraint-maxlik-optimization).
npar

number of parameters (required in constraint-maxlik-optimization).
genome_factor

Genomic conversion factor used in translocations.
calc_type

Calculation type, either "fitting" or "estimation".

Value

Data frame of model statistics.

Calculate manual translocation rate

Description

Calculate manual translocation rate

Usage

calculate_trans_rate_manual(cells, genome_factor, expected_aberr_value)

Arguments

cells

Number of cells N.
genome_factor

Genomic conversion factor.
expected_aberr_value

Expected aberrations.

Value

Numeric value of translocation rate.

Calculate Sigurdson's translocation rate

Description

Method based on the paper by Sigurdson, A. J. et al. (2008). International study of factors affecting human chromosome translocations. Mutation Research/Genetic Toxicology and Environmental Mutagenesis, 652(2), 112-121. <doi:10.1016/j.mrgentox.2008.01.005>.

Usage

calculate_trans_rate_sigurdson(
  cells,
  genome_factor,
  age_value,
  sex_bool = FALSE,
  sex_value = "none",
  smoker_bool = FALSE,
  ethnicity_value = "none",
  region_value = "none"
)

Arguments

cells

Number of cells N.
genome_factor

Genomic conversion factor.
age_value

Age of the individual.
sex_bool

If TRUE, sex_value will be used.
sex_value

Sex of the individual, either "male" of "female".
smoker_bool

Whether the individual smokes or not.
ethnicity_value

Ethnicity of the individual.
region_value

Region of the individual.

Value

Numeric value of translocation rate.

Calculate yield from dose

Description

Calculate yield from dose

Usage

calculate_yield(
  dose,
  type = c("estimate", "lower", "upper"),
  general_fit_coeffs,
  general_fit_var_cov_mat = NULL,
  protracted_g_value = 1,
  conf_int = 0.95
)

Arguments

dose

Numeric value of dose.
type

Type of yield calculation. Can be "estimate", "lower", or "upper".
general_fit_coeffs

Generalised fit coefficients matrix.
general_fit_var_cov_mat

Generalised variance-covariance matrix.
protracted_g_value

Protracted G(x)G(x) value.
conf_int

Curve confidence interval, 95% by default.

Value

Numeric value of yield.

Calculate theoretical yield infimum

Description

Calculate theoretical yield infimum

Usage

calculate_yield_infimum(
  type = c("estimate", "lower", "upper"),
  general_fit_coeffs,
  general_fit_var_cov_mat = NULL,
  conf_int = 0.95
)

Arguments

type

Type of yield calculation. Can be "estimate", "lower", or "upper".
general_fit_coeffs

Generalised fit coefficients matrix.
general_fit_var_cov_mat

Generalised variance-covariance matrix.
conf_int

Curve confidence interval, 95% by default.

Value

Numeric value of yield infimum.

Correct boundary of irradiated fractions to be bounded by 0 and 1

Description

Correct boundary of irradiated fractions to be bounded by 0 and 1

Usage

correct_boundary(x)

Arguments

x

Numeric value.

Value

Numeric value in [0, 1] range.

Correct yield confidence interval

Description

Correct yield confidence interval if simple method is required.

Usage

correct_conf_int(
  conf_int,
  general_fit_var_cov_mat,
  protracted_g_value = 1,
  type,
  dose = seq(0, 10, 0.2)
)

Arguments

conf_int

Confidence interval.
general_fit_var_cov_mat

Generalised variance-covariance matrix.
protracted_g_value

Protracted G(x)G(x) value.
type

Type of yield calculation. Can be "estimate", "lower", or "upper".
dose

Numeric value of dose.

Value

Numeric value of corrected confidence interval.

Correct negative values

Description

Correct negative values

Usage

correct_negative_vals(x)

Arguments

x

Numeric value.

Value

Numeric value corrected to zero if negative.

Correct yields if they are below the curve

Description

Correct yields if they are below the curve

Usage

correct_yield(
  yield,
  type = "estimate",
  general_fit_coeffs,
  general_fit_var_cov_mat,
  conf_int
)

Arguments

yield

Numeric value of yield.
type

Type of yield calculation. Can be "estimate", "lower", or "upper".
general_fit_coeffs

Generalised fit coefficients matrix.
general_fit_var_cov_mat

Generalised variance-covariance matrix.
conf_int

Curve confidence interval.

Value

Numeric value of corrected yield.

DNA Content Fractions of Human Chromosomes (IHGSC)

Description

Normalised DNA Content of Human Chromosomes from the International Human Genome Sequencing Consortium.

Usage

dna_content_fractions_ihgsc

Format

A data frame with 24 rows and 3 variables:

chromosome

Chromosome.

fraction_male

Normalised content of megabases on male human DNA.

fraction_female

Normalised content of megabases on female human DNA.

Details

Last accessed in July 2020.

Source

https://www.ncbi.nlm.nih.gov/grc/human/data

DNA Content Fractions of Human Chromosomes (Morton 1991)

Description

Normalised DNA Content of Human Chromosomes from Morton, N. E. (1991). Parameters of the human genome. Proceedings of the National Academy of Sciences, 88(17), 7474-7476.

Usage

dna_content_fractions_morton

Format

A data frame with 24 rows and 3 variables:

chromosome

Chromosome.

fraction_male

Normalised content of megabases on male human DNA.

fraction_female

Normalised content of megabases on female human DNA.

Source

doi:10.1073/pnas.88.17.7474

Heterogeneous dose estimation (Mixed Poisson model)

Description

Method based on the paper by Pujol, M. et al. (2016). A New Model for Biological Dose Assessment in Cases of Heterogeneous Exposures to Ionizing Radiation. Radiation Research, 185(2), 151-162. <doi:10.1667/RR14145.1>.

Usage

estimate_hetero_mixed_poisson(
  case_data,
  fit_coeffs,
  fit_var_cov_mat,
  conf_int = 0.95,
  protracted_g_value = 1,
  gamma,
  gamma_error
)

Arguments

case_data

Case data in data frame form.
fit_coeffs

Fitting coefficients matrix.
fit_var_cov_mat

Fitting variance-covariance matrix.
conf_int

Confidence interval, 95% by default.
protracted_g_value

Protracted G(x)G(x) value.
gamma

Survival coefficient of irradiated cells.
gamma_error

Error of the survival coefficient of irradiated cells.

Value

List containing estimated mixing proportions data frame, estimated yields data frame, estimated doses data frame, estimated fraction of irradiated blood data frame, AIC, and conf_int_* used.

Partial-body dose estimation (Dolphin's method)

Description

Method based on the paper by Dolphin, G. W. (1969). Biological Dosimetry with Particular Reference to Chromosome Aberration Analysis: A Review of Methods. International Atomic Energy Agency (IAEA) Retrieved from https://inis.iaea.org/search/search.aspx?orig_q=RN:45029080.

Usage

estimate_partial_body_dolphin(
  case_data,
  fit_coeffs,
  fit_var_cov_mat,
  conf_int = 0.95,
  protracted_g_value = 1,
  genome_factor = 1,
  gamma,
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

case_data

Case data in data frame form.
fit_coeffs

Fitting coefficients matrix.
fit_var_cov_mat

Fitting variance-covariance matrix.
conf_int

Confidence interval, 95% by default.
protracted_g_value

Protracted G(x)G(x) value.
genome_factor

Genomic conversion factor used in translocations, else 1.
gamma

Survival coefficient of irradiated cells.
aberr_module

Aberration module.

Value

List containing estimated doses data frame, observed fraction of cells scored which were irradiated, estimated fraction of irradiated blood data frame, AIC, and conf_int_* used.

Whole-body dose estimation (delta method)

Description

Method based on 2001 manual by the International Atomic Energy Agency (IAEA). Cytogenetic Analysis for Radiation Dose Assessment, Technical Reports Series (2001). Retrieved from https://www.iaea.org/publications/6303/cytogenetic-analysis-for-radiation-dose-assessment.

Usage

estimate_whole_body_delta(
  case_data,
  fit_coeffs,
  fit_var_cov_mat,
  conf_int = 0.95,
  protracted_g_value = 1,
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

case_data

Case data in data frame form.
fit_coeffs

Fitting coefficients matrix.
fit_var_cov_mat

Fitting variance-covariance matrix.
conf_int

Confidence interval, 95% by default.
protracted_g_value

Protracted G(x)G(x) value.
aberr_module

Aberration module.

Value

List containing estimated doses data frame, AIC, and conf_int used.

Whole-body dose estimation (Merkle's method)

Description

Method based on the paper by Merkle, W. (1983). Statistical methods in regression and calibration analysis of chromosome aberration data. Radiation and Environmental Biophysics, 21(3), 217-233. <doi:10.1007/BF01323412>.

Usage

estimate_whole_body_merkle(
  case_data,
  fit_coeffs,
  fit_var_cov_mat,
  conf_int_yield = 0.83,
  conf_int_curve = 0.83,
  protracted_g_value = 1,
  genome_factor = 1,
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

case_data

Case data in data frame form.
fit_coeffs

Fitting coefficients matrix.
fit_var_cov_mat

Fitting variance-covariance matrix.
conf_int_yield

Confidence interval of the yield, 83% by default.
conf_int_curve

Confidence interval of the curve, 83% by default.
protracted_g_value

Protracted G(x)G(x) value.
genome_factor

Genomic conversion factor used in translocations, else 1.
aberr_module

Aberration module.

Value

List containing estimated doses data frame, AIC, and conf_int_* used.

Perform dose-effect fitting algorithm

Description

Perform dose-effect fitting. A generalized linear model (GLM) is used by default, with a maximum likelihood estimation (MLE) as a fallback method.

Usage

fit(
  count_data,
  model_formula,
  model_family,
  fit_link = "identity",
  aberr_module = c("dicentrics", "translocations", "micronuclei"),
  algorithm = c("glm", "maxlik")
)

Arguments

count_data

Count data in data frame form.
model_formula

Model formula.
model_family

Model family.
fit_link

Family link.
aberr_module

Aberration module.
algorithm

Optional selection of algorithm to be used, either "glm" (for GLM) or "maxlik" (for MLE). By default, "glm" is used, with "maxlik" as a fallback method.

Details

The GLM method is based on the paper by Edwards, A. A. et al. (1979). Radiation induced chromosome aberrations and the Poisson distribution. Radiation and Environmental Biophysics, 16(2), 89-100. <doi:10.1007/BF01323216>.

The MLE method is based on the paperby Oliveira, M. et al. (2016). Zero-inflated regression models for radiation-induced chromosome aberration data: A comparative study. Biometrical Journal, 58(2), 259-279. <doi:10.1002/bimj.201400233>.

Value

List object containing fit results either using GLM or maxLik optimization.

Perform GLM (Generalised Linear Model) fitting

Description

Method based on the paper by Edwards, A. A. et al. (1979). Radiation induced chromosome aberrations and the Poisson distribution. Radiation and Environmental Biophysics, 16(2), 89-100. <doi:10.1007/BF01323216>.

Usage

fit_glm_method(
  count_data,
  model_formula,
  model_family = c("automatic", "poisson", "quasipoisson", "nb2"),
  fit_link = "identity",
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

count_data

Count data in data frame form.
model_formula

Model formula.
model_family

Model family.
fit_link

Family link.
aberr_module

Aberration module.

Value

List object containing GLM fit results.

Perform max-likelihood optimization fitting

Description

Method based on the paper by Oliveira, M. et al. (2016). Zero-inflated regression models for radiation-induced chromosome aberration data: A comparative study. Biometrical Journal, 58(2), 259-279. <doi:10.1002/bimj.201400233>.

Usage

fit_maxlik_method(
  data,
  model_formula,
  model_family = c("automatic", "poisson", "quasipoisson", "nb2"),
  fit_link,
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

data

Count data.
model_formula

Model formula.
model_family

Model family.
fit_link

Family link.
aberr_module

Aberration module.

Value

List object containing maxLik fit results.

Get standard errors using delta method

Description

Delta method for approximating the standard error of a transformation g(X)g(X) of a random variable X=(x1,x2,...)X = (x1, x2, ...), given estimates of the mean and covariance matrix of XX.

Usage

get_deltamethod_std_err(
  fit_is_lq,
  variable = c("dose", "fraction_partial", "fraction_hetero"),
  mean_estimate,
  cov_estimate,
  protracted_g_value = NA,
  d0 = NA
)

Arguments

fit_is_lq

Whether the fit is linear quadratic (TRUE) or linear (FALSE).
variable

Variable resulting of the transformation g(X)g(X).
mean_estimate

The estimated mean of XX.
cov_estimate

The estimated covariance matrix of XX.
protracted_g_value

Protracted G(x)G(x) value.
d0

Survival coefficient of irradiated cells.

Value

Numeric value containing the standard error of the dose estimate.

Include Markdown help

Description

Include Markdown help

Usage

include_help(...)

Arguments

...

Character vector specifying directory and or file to point to inside the current package.

Load RMarkdown report

Description

Load RMarkdown report

Usage

load_rmd_report(...)

Arguments

...

Character vector specifying directory and or file to point to inside the current package.

Plot dose estimation curve

Description

Plot dose estimation curve

Usage

plot_estimated_dose_curve(
  est_doses,
  fit_coeffs,
  fit_var_cov_mat,
  protracted_g_value = 1,
  conf_int_curve,
  aberr_name
)

Arguments

est_doses

List of dose estimations results from estimate_*() family of functions.
fit_coeffs

Fitting coefficients matrix.
fit_var_cov_mat

Fitting variance-covariance matrix.
protracted_g_value

Protracted G(x)G(x) value.
conf_int_curve

Confidence interval of the curve.
aberr_name

Name of the aberration to use in the y-axis.

Value

ggplot2 object.

Plot fit dose curve

Description

Plot fit dose curve

Usage

plot_fit_dose_curve(fit_results_list, aberr_name)

Arguments

fit_results_list

List of fit results.
aberr_name

Name of the aberration to use in the y-axis.

Value

ggplot2 object.

Prepare count data for max-likelihood optimization fitting

Description

Prepare count data for max-likelihood optimization fitting

Usage

prepare_maxlik_count_data(
  count_data,
  model_formula,
  aberr_module = c("dicentrics", "translocations", "micronuclei")
)

Arguments

count_data

Count data in data frame form.
model_formula

Model formula.
aberr_module

Aberration module.

Value

Data frame of parsed count data.

Project yield into dose-effect fitting curve

Description

Project yield into dose-effect fitting curve

Usage

project_yield(
  yield,
  type = "estimate",
  general_fit_coeffs,
  general_fit_var_cov_mat = NULL,
  protracted_g_value = 1,
  conf_int = 0.95
)

Arguments

yield

Yield to be projected.
type

Type of yield calculation. Can be "estimate", "lower", or "upper".
general_fit_coeffs

Generalised fit coefficients matrix.
general_fit_var_cov_mat

Generalised variance-covariance matrix.
protracted_g_value

Protracted G(x)G(x) value.
conf_int

Curve confidence interval, 95% by default.

Value

Numeric value of projected dose.

Calculate protracted function G(x)G(x)

Description

Calculation based on the paper by Lea, D. E. & Catcheside, D. G. (1942). The mechanism of the induction by radiation of chromosome aberrations inTradescantia. Journal of Genetics, 44(2-3), 216-245. <doi:10.1007/BF02982830>.

Usage

protracted_g_function(time, time_0 = 2)

Arguments

time

Time over which the irradiation occurred.
time_0

The mean lifetime of the breaks, which has been shown to be on the order of ~ 2 hours (default value).

Value

Numeric value of G(x)G(x).

Calculate R regression confidence factor

Description

Calculate R regression confidence factor depending on selected confidence interval and type of fit.

Usage

R_factor(general_fit_coeffs, conf_int = 0.95)

Arguments

general_fit_coeffs

Generalised fit coefficients matrix.
conf_int

Confidence interval, 95% by default.

Value

Numeric value of R regression confidence factor.

Run the Shiny Application

Description

Run the Shiny Application

Usage

run_app(...)

Arguments

...

A series of options to be used inside the app.

Value

Used for side-effect.

Calculate yield error

Description

Calculate yield error using Merkle's method

Usage

yield_error_fun(dose, general_fit_var_cov_mat = NULL, protracted_g_value = 1)

Arguments

dose

Numeric value of dose.
general_fit_var_cov_mat

Generalised variance-covariance matrix.
protracted_g_value

Protracted G(x)G(x) value.

Value

Numeric value of yield error.

Calculate yield

Description

Calculate yield

Usage

yield_fun(dose, general_fit_coeffs, protracted_g_value = 1)

Arguments

dose

Numeric value of dose.
general_fit_coeffs

Generalised fit coefficients matrix.
protracted_g_value

Protracted G(x)G(x) value.

Value

Numeric value of yield.