Reference and Utility Functions for BioequivalencePower

This is the module of the package:

BioequivalencePower — Module

BioequivalencePower

This module offers power and sample size calculations for bioequivalence (BE) studies.

This function summarizes the key features of the package:

BioequivalencePower.supported_designs_and_studies — Function

supported_designs_and_studies()::NamedTuple{(:designs, :studies, :legend, :methods), Tuple{DataFrame, DataFrame, DataFrame, DataFrame}}

Returns a named tuple of four dataframes, :designs, :studies, :legend, and :methods. These dataframes summarize the available designs and studies that match them.

General

These types help with input and output of arguments:

BioequivalencePower.HTRealParam — Type

const HTRealParam = Union{Real, Vector{Float64}, Nothing}

Can be a real value, or a vector of real values (Float64 values) or Nothing. Used for input of real values (e.g. CV), or vectors of real values (e.g. CVs for different treatments), or nothing if not defined.

BioequivalencePower.HTIntParam — Type

const HTIntParam = Union{Int, Vector{Int}, Nothing}

Can be a an integer value, or a vector of integers, or Nothing. Used for input of integer values (e.g. total sample size), or vectors of integer values (e.g. sample sizes for different sequences), or nothing if not defined.

BioequivalencePower.HTAssumptions — Type

const HTAssumptions = Union{NamedTuple,Nothing}

Can be a NamedTuple, or Nothing. Used for input of assumptions or nothing if not defined.

BioequivalencePower.HypothesisTestMetaParams — Type

HypothesisTestMetaParams(α::Float64 = 0.05,
                         n::HTIntParam = nothing,
                         assumptions::HTAssumptions = nothing,
                         target_power::HTRealParam = 0.8,
                         achieved_power::HTRealParam = nothing,
                         n_g::HTIntParam = 1)

An object for meta parameters of an hypothesis test or study. Used as output of functions and as input when using the complete API. The object can be constructed with any order of the keyword arguments. Z

Arguments:

α: The specified type I error for the study/test - or may be interpreted as the α which affects confidence level.
n: The total number of subjects (in all sequences), or a vector of the number of subjects per sequence.
assumptions: Any special assumptions in the test (see details below)
target_power: The desired power
achieved_power: The achieved power in the test for the sample size n.
n_g: The number of groups (physical testing sites) default is 1 site which means no groups. May be a vector as well and then should have sum(n_g) == n.
study: The associated study and its parameters. Especially useful when HypothesisTestMetaParams is a return type. Default is nothing.
result_of: This marks what the object is a result of (assuming computation was carried out to create it).
result_details: In certain cases has additional details of the last computation.

BioequivalencePower.BioequivalencePowerStudy — Type

An abstraction of a bioequivalence hypothesis test power analysis.

Sample size

BioequivalencePower.samplesize — Function

samplesize( ht::T, 
            hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
            power_method::PowerCalculationMethod = default_power_method(T),
            init_guess::Union{Int, Nothing} = nothing,
            count_iter::Bool = false,
            set_study_type_in_return::Bool = true,
            verbose = false,
            min_num_sims_for_2_phase = 10^4,
            num_sims_on_first_phase_for_2_phase = 2*10^3) where T <: BioequivalencePowerStudy

Find the sample size for a given problem.

count_iter = true implies a tuple is returned where the second element counts how many power evaluations were performed.
init_guess can be used as an initial guess n. Default is nothing
min_num_sims_for_2_phase and num_sims_on_first_phase_for_2_phase are constants used in the algorithm.
set_study_type_in_return implies the study is copied to the return value. Default is true

samplesize(::Type{BS}, ::Type{D} = EDDefaultDesign, 
           ::Type{BW} = EmptyBayesianWrapper, ::Type{PP} = EmptyPriorParameters;
           kwargs...
           ) where {BS <: BioequivalencePowerStudy, D <: ExperimentalDesign, BW <: BayesianWrapper, PP <:PriorParameters}

This is the easy-API samplesize method. Its interface is designed to be as easy and simple to use as possible. However, since it encompasses all of the sample size functionality of the package, the docstring is long.

There are two mandatory positional arguments, first the study type BS and then the design type D. Type names are used for these arguments. For example:

samplesize(RatioTOST, ED2x2x3ReplicateCrossover, ...)

Another two optional positional arguments are the prior type BW and its parameters PP. Use these only if a you wish to compute sample size using expected power in the Bayesian context. For example:

samplesize(RatioTOST, ED2x2x3ReplicateCrossover, CVSEPrior, DegreesOfFreedomPriorParameters, ...)

After these positional arguments, the remaining arguments are indicated in the method signature via kwargs (key word arguments). With these keywords we always need to set the variability parameter, CV (can also be SE in certain cases). The order of the keywords does not matter. Many other keywords are also possible (see below). Here is a minimal working example:

samplesize(RatioTOST, ED2x2x3ReplicateCrossover, CV = 0.32)

The essence of the easy-API is that the it uses the complete-API under the hood, yet presents a simple interface. For example here, behind the scenes, CV = 0.32 is set in a RatioTOST{ED2x2x3ReplicateCrossover} object which is passed to a samplesize method for such objects. These details are hidden from the user. The easy-API sees which arguments are supplied and constructs the objects based on these arguments before invoking the complete-API internally.

Here is a full list of arguments:

1st argument: bioequivalence power study type. One of:
- Standard (average) bioequivalence: RatioTOST or DifferenceTOST
- Reference scaling and/or expanding limits: ReferenceScaledRatioTOST or ExpandingLimitsRatioTOST
- Tests for NTID (Narrow Therapeutic Index Drug): NarrowTherapeuticIndexDrugRatioTOST
- Tests in the context of fiducial inference: FiducialRatioTOST
- Tests with two end points: TwoDifferenceTOSTs or TwoRatioTOSTs
- Dose proportionality: DoseProportionalityStudy
- Non-inferiority tests: NonInferiorityRatioOST or NonInferiorityDifferenceOST
2nd argument: design.
- For the study types RatioTOST, DifferenceTOST, TwoDifferenceTOSTs, TwoRatioTOSTs, NonInferiorityRatioOST or NonInferiorityDifferenceOST, use one of: ED2Parallel, ED2x2Crossover, ED3x3Crossover, ED3x6x3Crossover, ED4x4Crossover,ED2x2x3ReplicateCrossover, ED2x2x4ReplicateCrossover, ED2x4x4ReplicateCrossover, ED2x3x3PartialReplicate, ED2x4x2Balaam,ED2x2x2RepeatedCrossover, or EDPaired.
- For the study types ExpandingLimitsRatioTOST or ReferenceScaledRatioTOST use one of: ED2x2x3ReplicateCrossover, ED2x2x4ReplicateCrossover, or ED2x3x3PartialReplicate.
- For the study type NarrowTherapeuticIndexDrugRatioTOST use one of ED2x2x3ReplicateCrossover or ED2x2x4ReplicateCrossover.
- For the study type FiducialRatioTOST use one of ED2Parallel or ED2x2Crossover.
- For the study type DoseProportionalityStudy use one of EDGeneralCrossover, EDGeneralParallel, or EDGeneral.
3rd argument (optional) prior type:
- This argument can only be used with study types RatioTOST, DifferenceTOST, NonInferiorityRatioOST, or NonInferiorityDifferenceOST and should be one of CVSEPrior, θ0Prior, or BothCVSEandθ0Prior, to indicate a prior on the variability parameter (CV or SE), on θ₀, or on both, respectively.
- If this argument is set, you must set the 4th argument.
4th argument (optional) prior distribution type:
- This argument is relevant if and only if the 3rd argument (prior type) is set.
- If the prior type is CVSEPrior use DegreesOfFreedomPriorParameters or CategoricalPriorParameters.
- If the prior type is θ0Prior use StandardErrorPriorParameters or CategoricalPriorParameters.
- If the prior type is BothCVSEandθ0Prior use DegreesOfFreedomAndStandardErrorPriorParameters or TwoWayCategoricalPriorParameters.

The keyword arguments following the initial arguments are always set in the form KEY = VALUE, where for example KEY can be CV and value can be 0.32. Here is a full list, starting with mandatory arguments and following with optional arguments.

Mandatory Arguments

Variability arguments: The typical variability argument is CV, but in certain cases SE is used instead. In other cases secondary variability arguments are required or optional. Here is a complete list of variability arguments. Note that variability arguments are always positive and in certain cases they are given as a vector.
- RatioTOST, DoseProportionalityStudy, and NonInferiorityRatioOST: Specify CV as a single value.
- ReferenceScaledRatioTOST, ExpandingLimitsRatioTOST, and NarrowTherapeuticIndexDrugRatioTOST: Specify CV as a single value, or if wishing to consider heteroscedasticity, specify as a vector of length 2, with the first entry for the test formulation and the second entry for the reference formulation.
- DifferenceTOST, and NonInferiorityDifferenceOST: Specify SE as a single value.
- FiducialRatioTOST: Specify both SE and SEb, each as a single value.
- TwoRatioTOSTs: Specify CV as a vector of length 2 matching the two end points of the study.
- TwoDifferenceTOSTs: Specify SE as a vector of length 2 matching the two end points of the study.
- DoseProportionalityStudy: Specify CV as a single value. Optionally, specify CVb as a single value (default value of CVb if not specified is twice CV.)
For DoseProportionalityStudy you must also specify the vector of doses via doses. This is a vector of integer values, e.g. doses = [1, 2, 8].
In case of a prior distribution (3rd and 4th arguments used) there are other mandatory arguments. See specific description below.

Argument for "test/reference" ratio or difference

A key input to the sample size computation is the ratio or difference between the test and reference formulation. That is, sample size is computed based on such a postulated point. It is typically denoted θ₀ with variable name peθ₀, except for the context of dose proportionality studies where it is denoted β₀ with variable name peβ₀. All of the study types set default for this argument, and you can naturally override that default.

Ratio formulation defaults:

peθ₀ for RatioTOST, FiducialRatioTOST, NonInferiorityRatioOST: Default is at 0.95.
peθ₀ for ReferenceScaledRatioTOST, ExpandingLimitsRatioTOST: Default is at 0.9.
peθ₀ for NarrowTherapeuticIndexDrugRatioTOST: Default is at 0.975 if highly_variable = false (default), and at 0.95 otherwise (the HVNTID case).
peθ₀ for TwoRatioTOSTs: Default is at the vector [0.95, 0.95].

Difference formulation defaults:

peθ₀ for DifferenceTOST: Default is at 0.05.
peθ₀ for NonInferiorityDifferenceOST: Default is at -0.05.
peθ₀ for TwoDifferenceTOSTs: Default is at the vector [0.05, 0.05].

Dose proportionality default:

peβ₀ for DoseProportionalityStudy is set at 1 + log(0.95)/log(maximum(doses) / minimum(doses)).

Argument for limits

Most of the study types have set limits values θ₁ and θ₂ with θ₁ < θ₂. The non-inferiority types has the single limit θmargin, and the two simultaneous end points studies have θ₁ and θ₂, each as a vector of length 2. Default values are set for all of these, and you can set your own values to override the defaults. Note that in most cases θ₂ is defined in terms of θ₁. Hence you may set θ₁ and as a result, θ₂ will be adjusted accordingly, or you may set only θ₂, or set both.

For RatioTOST, ReferenceScaledRatioTOST, ExpandingLimitsRatioTOST, NarrowTherapeuticIndexDrugRatioTOST, FiducialRatioTOST,and DoseProportionalityStudy we have that θ₁ and θ₂ are each scalar values with defaults θ₁ = 0.8 and θ₂ = 1/θ₁ (this is 1.25).
For DifferenceTOST we have that θ₁ and θ₂ are each scalar values with defaults θ₁ = -0.2 and θ₂ = -θ₁ (this is 0.2).
For TwoRatioTOSTs and TwoDifferenceTOSTs we have that θ₁ and θ₂ are each vectors of length 2 with default individual entries corresponding to RatioTOST and DifferenceTOST. For example for TwoRatioTOSTs we have θ₁ = [0.8, 0.8] and θ₂ = 1 ./ θ₁.
For NonInferiorityRatioOST the default value is θmargin = 0.8.
For NonInferiorityDifferenceOST the default value is θmargin = -0.2.

Optional Arguments for hypothesis test meta parameters (including assumptions)

target_power: This is the target power for which sample size should be determined. Default value is 0.8. The function will search for n that has target_power ≤ achieved_power.
α: By default, α = 0.05 for most studies with the exception of FiducialRatioTOST, NonInferiorityRatioOST, and NonInferiorityDifferenceOST where it is set at 0.025 (note that this adjusted default is only applicable via the easy-API and not via the complete-API).
n_g: This is the number of groups in the study (it is the number of location sites and should not to be confused with the number of sequences in a design). By default n_g = 1. For standard (average) bioequivalence formulated as a ratio, namely RatioTOST, we may use other values of n_g if carrying out subject level simulations (subject_level = true). See more details with subject_level below.
robust: Set this to true for a determination of degrees of freedom using a robust formulation. Default is false.
test_group_effect: Set this to true for the specific case RatioTOST with n_g set to greater than one and subeject_level = true. In this case a model for testing group effect is first executed. Default is false.

Special arguments for reference scaling and/or expanding limits

reg_symbol: This is the symbol for the RegulatoryConstants object set in either ReferenceScaledRatioTOST or ExpandingLimitsRatioTOST studies. For the former the default is :fda and for the latter it is :ema. You may set other regulatory constants objects if you wish.

Special arguments for narrow therapeutic drug index products

highly_variable: This boolean value with default false determines if the study is an NTDI or HVNTDI study. The case highly_variable = true yields different behavior for the hypothesis test.
regulatory_constant: Default is -log(0.9)/0.10 (which is about 1.053605), used only in highly_variable = false.
ratio_threshold: Default is 2.5.

Special arguments for two simultaneous end points

ρ: When using TwoRatioTOSTs or TwoDifferenceTOSTs, this is the assumed correlation coefficient between the two endpoints. Default is 0.0 and it can be set to any value such that -1 ≤ ρ ≤ 1.

Special arguments for dose proportionality study

design_matrix: Use this only with DoseProportionalityStudy and EDGeneral specified in the 1st and 2nd arguments respectively. In this case design_matrix should be set to an EDGeneral design object which encapsulates a design_matrix that can be specified.

Arguments for simulation and computation

Note that the arguments num_sims, seed, and subject_level are specific to a case where Monte Carlo sample size calculation is used (this means the power calculation used by samplesize uses Monte Carlo). In study types where exact power calculation is used by default and Monte Carlo is also supported, the default is overridden and the calculation is changed to Monte Carlo if one of these arguments is set. In other cases, where Monte Carlo is already the default, setting these parameters just updates the nature of the Monte Carlo.

The study types with default as exact calculation and an option for Monte Carlo are: RatioTOST, DifferenceTOST.

The study types with only numerical calculation are: DoseProportionalityStudy (note that this is an approximate calculation), NonInferiorityRatioOST, and NonInferiorityDifferenceOST.

The study types with only Monte Carlo are: ReferenceScaledRatioTOST, ExpandingLimitsRatioTOST, NarrowTherapeuticIndexDrugRatioTOST, FiducialRatioTOST, TwoRatioTOSTs, and TwoDifferenceTOSTs.

When using Monte Carlo, these are the possible arguments.

num_sims: This is the number of simulation runs to execute for each individual power calculation. The default is 1e5.
seed: This is the simulation seed to use for reproducibility. The default value is an arbitrary 1984 value, yet can be set to any integer value. Setting seed = nothing, implies no random seed is set. Warning: sample size search without a fixed seed is not recommended..
details: Set this to true to output additional simulation and/or computation output. Default is false.
subject_level: This argument is by default false and this implies simulations are based on randomly generating statistics. If set to true then it means that each simulation run randomly generates sample data and uses this random data to estimate the power. In general, subject_level = true is slower, yet in certain cases it yields better accuracy. You may set subject_level = true only for the following cases:
- RatioTOST, yet only with one of the designs ED2x2Crossover, ED2x2x3ReplicateCrossover, ED2x2x4ReplicateCrossover, or ED2x3x3PartialReplicate.
- ReferenceScaledRatioTOST with any of the supported designs of the study.
- ExpandingLimitsRatioTOST with any of the supported designs of the study.

Arguments for Bayesian computation

When setting the 3rd and 4th parameters for Bayesian computation, you must also supply prior parameters. See the Priors on parameters in power studies section of the docs for more details.

Counting iterations

An additional argument is count_iter with default value false. If set to true the return value is a tuple where the second argument is the number of power computations computed until finding the sample size.

Return value

The return value is an HypothesisTestMetaParams object. In this object, n is the determined sample size and the achieved_power field specifies the power obtained with such a sample size. If count_iter = true, the return value is a tuple with the first argument being an HypothesisTestMetaParams object, and the second argument being the number of iterations.

Computation types

Below are types specify how to compute power. The easy API uses these types automatically and in the complete API you can use them explicitly. In particular for certain study types you may switch between ExactPowerCalculation and MonteCarloPowerCalculation. In particular, the MonteCarloPowerCalculation types has in addition to typical Monte Carlo parameters (seed, num_sims), the parameter subject_level that modifies the type of Monte Carlo simulation. When subject_level = false then a statistic based simulation is carried out, and when it is true, individual subject data is simulated.

BioequivalencePower.DefaultPowerCalculation — Type

An empty struct that indicates to use the default power calculation in contrast to specifying a specific method.

BioequivalencePower.ExactPowerCalculation — Type

ExactPowerCalculation(details = false)

An indication to use numerical calculation (as exact as possible) for power calculation. If the details argument is set to to true then auxiliary information about the calculation is displayed. Default is false.

BioequivalencePower.MonteCarloPowerCalculation — Type

MonteCarloPowerCalculation(num_sims::Int = 1e5,
                           seed::Union{Int, Nothing} = 1984, 
                           subject_level::Bool = false,
                           details::Bool = false)

Naive Monte Carlo for testing. There are generally two possibilities. With subject_level = false, test statistics are simulated. With subject_level =true a study is simulated with subject level data.

Utilities for experimental designs

This function is useful for distributing subjects over groups, especially in unbalanced designs:

BioequivalencePower.distribute_groups — Function

distribute_groups(n::Int, g::Int)::Tuple{Vector{Int64}, Bool}

Partition n observations into g groups. If g divides n, the partition is uniform (constant number across groups), otherwise, the partition has one more observation in some of the groups.

Returns a tuple with the first element being a vector of integers representing the partition, and the second element a boolean which is true if the vector is uniform and otherwise false.

Examples

julia> distribute_groups(17, 3)
([6, 6, 5], false)

julia> distribute_groups(18, 3)
([6, 6, 6], true)

This function creates design matrices:

BioequivalencePower.multiple_treatment_design_matrix — Function

multiple_treatment_design_matrix(num_t::Int, num_p::Int)

Construct an incomplete block design matrix based on num_t treatments (either 3, 4, or 5), and num_p periods (2,..., num_t-1). The treatments are labeled in the matrix via 1,...,num_t.

Examples

julia> multiple_treatment_design_matrix(4, 3)
4×3 Matrix{Int64}:
 2  3  4
 3  4  1
 4  1  2
 1  2  3

Utilities for variability parameters

These are basic conversions between CV and the \sigma parameter of the log-normal distribution. Terms here are SE for \sigma and MSE for \sigma^2:

BioequivalencePower.cv2mse — Function

cv2mse(cv::Real) = log(1 + cv^2)

Convert CV of log-normal data to MSE.

BioequivalencePower.mse2cv — Function

mse2cv(mse::Real) = √(exp(mse) - 1)

Convert MSE of log-normal data to CV.

BioequivalencePower.cv2se — Function

cv2se(cv::Real) = √cv2mse(cv)

Convert CV of log-normal data to SE.

BioequivalencePower.se2cv — Function

se2cv(se::Real) = mse2cv(se^2)

Convert SE of log-normal data to CV.

These functions are useful for converting a specified confidence interval of CV, as sometimes appearing in previous studies, to a CV parameter:

BioequivalencePower.ci2cv — Function

ci2cv(  ::Type{D} = EDDefaultDesign; 
        n::HTIntParam = nothing, 
        robust::Bool = false,
        α = 0.05,
        pe::Union{Real,Nothing} = nothing, 
        lower::Union{Real,Nothing} = nothing,
        upper::Union{Real,Nothing} = nothing) where D <: ExperimentalDesign

This is an easy-API method for ci2cv with interface close to PowerTOST's CVfromCI or the alias CI2CV.

ci2cv(  hp::HypothesisTestMetaParams, ::Type{D};
        pe::Union{Real,Nothing} = nothing, 
        lower::Union{Real,Nothing} = nothing,
        upper::Union{Real,Nothing} = nothing) where D <: ExperimentalDesign

Convert a ratio confidence interval to a CV. Specify two of (pe, lower, upper). The sample size and confidence level is specified in hp.

BioequivalencePower.ci2se — Function

ci2se(  hp::HypothesisTestMetaParams, ::Type{D};
        pe::Union{Real,Nothing} = nothing, 
        lower::Union{Real,Nothing} = nothing,
        upper::Union{Real,Nothing} = nothing) where D <: ExperimentalDesign

Like ci2cv but conversion to a standard error. This function does the "work" for ci2cv.

These functions provide confidence intervals for the variability parameters:

BioequivalencePower.confint_mse — Function

confint_mse(mse::Real, df::Real; side = :upper, α = 0.05)

Returns a 1-α confidence interval for the variance based on estimate mse and the degrees of freedom df. The option side can be set to :upper (default), :lower, or :two_sided. This function does the "work" for confint_cv.

BioequivalencePower.confint_cv — Function

confint_cv(cv::Real, df::Real, side = :upper, α = 0.05)

Returns a 1-α confidence interval for the CV based on estimate cv and the degrees of freedom df. The option side can be set to :upper (default), :lower, or :two_sided.

These functions deal with pooling of CV's:

BioequivalencePower.pool_cv — Function

pool_cv(cvs::Vector{Float64};n::Union{Vector{Int64}, Nothing} = nothing,
                             df::Any = nothing,
                             design::Any = ED2x2Crossover,
                             α::Real = 0.2,
                             robust::Bool = false,
                             log_scale::Bool = true)

Pools CVs from several studies with input CVs as given by cvs.

In addition to the vector cvs, the caller also needs to supply either the vectornor the vectordfwhich are of the same dimension ofcvs` determining the respective sample size or degrees of freedom.

If both n and df are supplied then df takes precedence.

The keyword argument designs is by default a simple 2x2 cross over design but can also be a vector with respective designs either as strings or as ExperimentalDesign types.

The argument α which by default is at 0.2 determines the upper confidence limit for CV.

You may also set robust to true and this affects the calculated degrees of freedom if n is given for some designs.

Note, if log_scale = false then cvs are treated as standard errors. The default is true.

Returns a named tuple with keys cv_pooled, cv_pooled_upper, α, and df (or keys named aptly for standard error if log_scale = false).

pool_cv(cvs_dataframe::DataFrame; 
        α::Real = 0.2, 
        robust::Bool = false,
        log_scale::Bool = true)

Pools CVs from several studies based on the information in a DataFrame. The data frame needs to have a cvs column and one of n or df. The dataframe can also have a design column.

BioequivalencePower.unpool_cv — Function

unpool_cv(pooled_cv::Real, ratio::Real)::Tuple{Float64, Float64}

Take a pooled CV pooled_cv assumed to come from treatment (T) and reference (R) and a ratio, of s^2(T)/s^2(R) ratio. Return a tuple of CVT and CVR.

Utilities for Reference scaling and/or expanding limits

BioequivalencePower.scaled_abel — Function

scaled_abel(cv::Float64, reg_const::RegulatoryConstants)

Returns the scaled average bioequivalence limits (ABEL) for a given cv and a given agency.

Returns the scaled average bioequivalence limits (ABEL) for a given cv and a given agency (given as a symbol).

BioequivalencePower.upper_expanded_limits_to_cvwr — Function

upper_expanded_limits_to_cvwr(upper_limit::Float64, reg_const::RegulatoryConstants)

Computes the intra-subject CV of the reference group from the upper expanded limit of a BE study.

Full list of method doc strings for key functions

BioequivalencePower.power — Function

power(ht::DifferenceTOST{D},
      hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
      power_method::PowerCalculationMethod = ExactPowerCalculation(),
      set_study_type_in_return::Bool = true,
      verbose = true
      )::HypothesisTestMetaParams  where D <: ExperimentalDesign

Calculate the power for DifferenceTOST. Must set SE in ht and must set n in hp. The power_method can be ExactPowerCalculation (this is default) for numerical integration or MonteCarloPowerCalculation. If MonteCarloPowerCalculation then may set subject_level to true if wishing execute subject level simulations (default is false).