`BioequivalencePower` Docstrings

BioequivalencePower.BioequivalencePower — Module

BioequivalencePower

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

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.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.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.BioequivalencePowerStudy — Type

An abstraction of a bioequivalence hypothesis test power analysis.

BioequivalencePower.BothCVSEandθ0Prior — Type

BothCVSEandθ0Prior{T <: BioequivalencePowerStudy, R <: PriorParameters}(ht::T, pp::R)

A prior both on the CV (or SE) and on the θ₀, for some test ht and prior parameters pp.

BioequivalencePower.CVSEPrior — Type

CVSEPrior{T <: BioequivalencePowerStudy, R <: PriorParameters}(ht::T, pp::R)

A prior on the CV (or SE), for some test ht and prior parameters pp.

BioequivalencePower.CategoricalPriorParameters — Type

CategoricalPriorParameters(param_values::HTRealParam = nothing,
                           param_probabilities::HTRealParam = nothing)

Used for a distribution over a finite set of param values as a prior.

BioequivalencePower.DefaultPowerCalculation — Type

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

BioequivalencePower.DegreesOfFreedomAndStandardErrorPriorParameters — Type

DegreesOfFreedomAndStandardErrorPriorParameters(df::HTRealParam = nothing,
                                                SE::HTRealParam = nothing)

BioequivalencePower.DegreesOfFreedomAndStandardErrorPriorParameters — Method

DegreesOfFreedomAndStandardErrorPriorParameters(    n_prior::HTIntParam, 
                                                    design_prior::Type{D}, 
                                                    used_SE_prior::Float64, 
                                                    robust_prior_for_df::Bool = false,
                                                    robust_prior_for_se::Bool = false) where D <: ExperimentalDesign

Construct a DegreesOfFreedomAndStandardErrorPriorParameters object based on sample size of previous study, n_prior and the design D. The flag robust_prior indicates if to compute the degrees of freedom and standard error via a robust assumption.

BioequivalencePower.DegreesOfFreedomPriorParameters — Type

DegreesOfFreedomPriorParameters(df::HTRealParam = nothing)

Used for a distribution using an inverse gamma using previous degrees of freedom.

BioequivalencePower.DegreesOfFreedomPriorParameters — Method

DegreesOfFreedomPriorParameters(    n_prior::HTIntParam, 
                                    design_prior::Type{D}, 
                                    robust_prior::Bool = false) where D <: ExperimentalDesign

Construct a DegreesOfFreedomPriorParameters object based on sample size of previous study, n_prior and the design D. The flag robust_prior indicates if to compute the degrees of freedom via a robust assumption.

BioequivalencePower.DifferenceTOST — Type

DifferenceTOST{D}(  peθ₀::HTRealParam = 0.05,
                    θ₁::HTRealParam = -0.2,
                    θ₂::HTRealParam = -θ₁,
                    SE::HTRealParam = nothing) where D <: ExperimentalDesign

A bioequivalence power study with a difference formulation. As in all bioequivalence power studies, θ₁ and θ₂ are the limits, and peθ₀ is the postulated value of the difference for which power (or sample size) is to be evaluated. SE is the standard error.

BioequivalencePower.DoseProportionalityStudy — Type

DoseProportionalityStudy{D}(doses::Union{Nothing, Vector{Int}} = nothing,                            
                            peβ₀::HTRealParam =  1 + log(0.95)/log(maximum(doses) / minimum(doses)), 
                            θ₁::HTRealParam = 0.8,                                                   
                            θ₂::HTRealParam = 1 / θ₁,                                                
                            CV::HTRealParam = nothing,                                               
                            CVb::HTRealParam = 2CV,                                                  
                            design::Union{Nothing, D} = nothing                                     
                            ) where D <: Union{EDGeneralCrossover, EDGeneralParallel, EDGeneral}

A dose proprotionality study.

BioequivalencePower.EmptyBayesianWrapper — Type

Used to indicate no bayesian wrapper.

BioequivalencePower.EmptyPriorParameters — Type

Used to indicate no prior parameters.

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.ExpandingLimitsRatioTOST — Type

ExpandingLimitsRatioTOST{D}(peθ₀::HTRealParam = 0.9,                                 
                            θ₁::HTRealParam = 0.8,                            
                            θ₂::HTRealParam = 1/θ₁,                             
                            CV::HTRealParam = nothing,
                            reg::RegulatoryConstants = RegulatoryConstants(:ema)
                            ) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}

BE ratio decision using expanding (widened) limits (ABEL).

BioequivalencePower.FiducialRatioTOST — Type

FiducialRatioTOST{D}(peθ₀::HTRealParam = 0.95,        
                     θ₁::HTRealParam = 0.8,
                     θ₂::HTRealParam = 1/θ₁,
                     SE::HTRealParam = nothing,        
                     SEb::HTRealParam = nothing) where D <: Union{ED2Parallel, ED2x2Crossover}

Fiducial test for equivalence via ratio (not considered log scale). It works for a parallel or a 2x2 cross over design.

See Hauschke D, Kieser M, Diletti E, Burke M. Sample size determination for proving equivalence based on the ratio of two means for normally distributed data. Stat Med. 1999;18(1):93–105.

Note that in R's PowerTOST package the variability parameters are called CVs, but in the current package we call them SEs.

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

BioequivalencePower.NarrowTherapeuticIndexDrugRatioTOST — Type

NarrowTherapeuticIndexDrugRatioTOST{D}(highly_variable::Bool = false,                       
                                       peθ₀::HTRealParam = highly_variable ? 0.95 : 0.975,                                              
                                       θ₁::HTRealParam = 0.8,
                                       θ₂::HTRealParam = 1/θ₁
                                       CV::HTRealParam = nothing,                           
                                       regulatory_constant = -log(0.9)/0.10,                
                                       ratio_threshold = 2.5
                                       ) where D <: Union{ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}

BE ratio decision using the method intially introduced via FDA for narrow therapeutic index drugs (NTIDs). This also supports HVNTID (highly variable narrow therapeutic index drugs).

BioequivalencePower.NonInferiorityDifferenceOST — Type

NonInferiorityDifferenceOST{D}(peθ₀::HTRealParam = -0.05,
                               θmargin::HTRealParam = -0.2,
                               SE::HTRealParam = nothing) where D <: ExperimentalDesign

Non-inferiority difference OST (One Sided Test). This is a standard one sided t-test formulated as a difference.

In the typical case where θmargin is negative the test is:

H0: T - R diff ≤ θmargin H1: Otherwise.

So rejecting H0 (e.g. with θmargin = -0.2) implies: T - R > -0.2 or T > R - 0.2 which means it is "close enough" to the reference.

If θmargin is specified as positive then the test is taken as a "non-superiority difference OST" with:

H0: T - R diff ≥ θmargin H1: Otherwise.

So rejecting H0 (e.g. with θmargin = 0.2) implies: T - R < 0.2 or T < R + 0.2 which means it is "not superior" to the reference.

BioequivalencePower.NonInferiorityRatioOST — Type

NonInferiorityRatioOST{D}(  peθ₀::HTRealParam = 0.95,
                            θmargin::HTRealParam = 0.8,
                            CV::HTRealParam = nothing) where D <: ExperimentalDesign

Non-inferiority ratio OST (One Sided Test). This is a standard one sided t-test formulated as a ratio. Similarly to the difference case, in the common case where θmargin < 1, rejecting the test means non-inferiority. However if we set θmargin > 1, then the test is reversed rejecting it means non-superiority.

In the typical case where θmargin is less than 1, the test is:

H0: T/R ≤ θmargin H1: Otherwise.

So rejecting H0 (e.g. with θmargin = 0.8) implies: T/R > 0.8 or T > 0.8 * R which means it is "close enough" to the reference.

If θmargin is specified as greater than 1, then the test is taken as a "non-superiority ratio OST" with:

H0: T - R diff ≥ θmargin H1: Otherwise.

So rejecting H0 (e.g. with θmargin = 1.2) implies: T/R < 1.2 or T < 1.2*R which means it is "not superior" to the reference.

BioequivalencePower.PowerAnalysisConstants — Type

PowerAnalysisConstants(min_power::Float64 = 0.7,
                       CV_step::Float64 = 0.005,
                       θ₀_step::Float64 = 0.005,
                       CV_reduction_factor = 2/3,
                       min_n::Int = 12,
                       do_plot::Bool = true)

This struct contains some arguments used for the power_analysis function.

Arguments

'min_power': The minimal level of acceptable power. Power analysis is carried down to this level of power.
'CV_step': The increments of the CV when scanning the CV.
'θ₀_step': The increments of the θ₀ when scanning θ₀.
'CVreductionfactor': When computing the CV, we start at the given CV multiplied by this reduction factor. This is important for cases where power is not monotone in the CV.
'min_n': Samples smaller than this value are not allowed.
'do_plot': Plot the results (default is true). Otherwise only present textual output.

BioequivalencePower.RatioTOST — Type

RatioTOST{D}(peθ₀::HTRealParam = 0.95,
             θ₁::HTRealParam = 0.8,
             θ₂::HTRealParam = 1/θ₁,
             CV::HTRealParam = nothing) where D <: ExperimentalDesign

A bioequivalence power study with a ratio formulation. This is the standard (average) bioequivalence study. As in all bioequivalence power studies, θ₁ and θ₂ are the limits, and peθ₀ is the postulated value of the ratio for which power (or sample size) is to be evaluated. CV is the coefficient of variation.

BioequivalencePower.ReferenceScaledRatioTOST — Type

ReferenceScaledRatioTOST{D}(peθ₀::HTRealParam = 0.9,                                 
                            θ₁::HTRealParam = 0.8,                            
                            θ₂::HTRealParam = 1/θ₁,                             
                            CV::HTRealParam = nothing,
                            reg::RegulatoryConstants = RegulatoryConstants(:fda)
                            ) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}

BE ratio decision using reference scaled average bioequivalence (RSABE), initially recommended by FDA.

BioequivalencePower.RegulatoryConstants — Type

RegulatoryConstants(agency::Symbol = :user,
                    r_const::Float64, 
                    cv_switch::Float64 = 0.3,
                    cv_cap::Float64,
                    apply_pe_constraints::Bool = true,
                    estimation_method::Symbol = :anova)

An object that holds a few constants of a regulator.

Arguments

agency: One of :fda, :ema, :hc, :gcc, or :user.
r_const: The so-called "regulatory constant".
cv_switch: CV threshold for switching to widened acceptance limits (switch above this threshold.)
cv_cap: Maximal CV for widening acceptance limits (beyond this CV level is constant).
apply_pe_constraints: Indicates if point estimate constraints should be applied (true).
estimation_method: Either :anova or :isc (inter-subject contrasts).

BioequivalencePower.RegulatoryConstants — Method

RegulatoryConstants(agency::Symbol; apply_pe_constraints::Bool = true)

Construct a regulatory constants objects based on constants for a specific agency presented as a symbol from one of :fda, :ema, :hc, :gcc. You may modify the application of pe (Point Estimate) constraints via apply_pe_constraints.

BioequivalencePower.StandardErrorPriorParameters — Type

StandardErrorPriorParameters(SE::HTRealParam = nothing)

BioequivalencePower.StandardErrorPriorParameters — Method

StandardErrorPriorParameters(   n_prior::HTIntParam, 
                                design_prior::Type{D}, 
                                used_SE_prior::Float64, 
                                robust_prior::Bool = false) where D <: ExperimentalDesign

Construct a StandardErrorPriorParameters object based on sample size of previous study, n_prior and the design D. The flag robust_prior indicates if to compute the standard error via a robust assumption.

BioequivalencePower.TwoDifferenceTOSTs — Type

TwoDifferenceTOSTs{D}(peθ₀::HTRealParam = [0.05, 0.05],
                      θ₁::HTRealParam = [-0.2, -0.2],
                      θ₂::HTRealParam = -θ₁,
                      SE::HTRealParam = nothing, 
                      ρ::HTRealParam = 0.0) where D <: ExperimentalDesign

Two simultaneous hypotheses for equivalence via difference.

BioequivalencePower.TwoRatioTOSTs — Type

TwoDifferenceTOSTs{D}(peθ₀::HTRealParam = [0.95, 0.95],
                      θ₁::HTRealParam = [0.8, 0.8],
                      θ₂::HTRealParam = 1 ./ θ₁,
                      SE::HTRealParam = nothing, 
                      ρ::HTRealParam = 0.0) where D <: ExperimentalDesign

Two simultaneous hypotheses for equivalence via ratio (log scale).

BioequivalencePower.TwoWayCategoricalPriorParameters — Type

TwoWayCategoricalPriorParameters(param_values_1::HTRealParam = nothing,
                                 param_probabilities_1::HTRealParam = nothing,
                                 param_values_2::HTRealParam = nothing,
                                 param_probabilities_2::HTRealParam = nothing)

Used for a distribution over a two way (2d grid) of finite set of param values as a prior.

BioequivalencePower.θ0Prior — Type

θ0Prior{T <: BioequivalencePowerStudy, R <: PriorParameters}(ht::T, pp::R)

A prior on the θ₀, for some test ht and prior parameters pp.

Base.show — Method

Shows an HypothesisTestMetaParams object. If it has result_of == nothing then the set fields are displayed. Otherwise it is a result of an output procedure (power or samplesize), in which case specific output for the procedure is displayed.

BioequivalencePower.adjusted_α — Method

adjusted_α(ht::ExpandingLimitsRatioTOST{D},
           hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
           pre_specified_α = nothing, 
           power_method::PowerCalculationMethod = MonteCarloPowerCalculation()
           ) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}

Adjusts α (if needed) for ExpandingLimitsRatioTOST.

See easy-API method doc for full description of the adjusted_α function.

BioequivalencePower.adjusted_α — Method

adjusted_α(ht::ReferenceScaledRatioTOST{D},
           hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
           pre_specified_α = nothing, 
           power_method::PowerCalculationMethod = MonteCarloPowerCalculation()
           ) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}

Adjusts α (if needed) for ReferenceScaledRatioTOST.

See easy-API method doc for full description of the adjusted_α function.

BioequivalencePower.adjusted_α — Method

adjusted_α(::Type{BS}, ::Type{D} = EDDefaultDesign;
           kwargs...
           ) where {BS <: BioequivalencePowerStudy, D <: ExperimentalDesign}

This is the easy-API adjusted_α method. Its interface is designed to be as easy and simple to use as possible. However, since it encompasses all of the adjusted α 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:

adjusted_α(ReferenceScaledRatioTOST, ED2x2x4ReplicateCrossover, ...)

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. The order of the keywords does not matter. Many other keywords are also possible (see below). Here is a minimal working example:

adjusted_α(ReferenceScaledRatioTOST, ED2x2x4ReplicateCrossover, CV = 0.27)

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, the coefficient of variation CV = 0.27 is set in a ReferenceScaledRatioTOST{ED2x2x4ReplicateCrossover} object. This object is hidden from the user. The easy-API sees which arguments are supplied and constructs objects based on these arguments before invoking the complete-API internally.

Here is a full list of arguments:

1st argument: bioequivalence power study type (note that not only Reference scaling and/or expanding limits BioequivalencePowerStudy sub-types are supported). Hence choose one of: ReferenceScaledRatioTOST or ExpandingLimitsRatioTOST.
2nd argument: design. Use one of: ED2x2x3ReplicateCrossover, ED2x2x4ReplicateCrossover, or ED2x3x3PartialReplicate.

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.27. Here is a full list, starting with mandatory argument and following with optional arguments.

Mandatory Arguments

Variability argument: This is CV 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.

Argument for "test/reference" ratio

A key input is the ratio between the test and reference formulation. That is, power is computed based on such a postulated point. It is denoted θ₀ with variable name peθ₀. Default is at 0.9 and you can naturally override that default.

Argument for limits

These are set limits values θ₁ and θ₂ with θ₁ < θ₂. Default values are set for all of these with defaults θ₁ = 0.8 and θ₂ = 1/θ₁ (this is 1.25). 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.

Type I error and α

α: By default, α = 0.05. This is the desired type I error.
pre_specified_α: Default is nothing. You may set this value and then the function will compute sample size using this pre specified value.

Further optional Arguments for hypothesis test meta parameters (including assumptions)

n: Can be an integer denoting the total number of subjects or an array of the number of subjects per sequence group, e.g. n = [12, 8]. In the typical case where the total number of subjects is given, the subjects are distributed as uniformly as possible among sequences of the design using the distribute_groups function. If this argument is not given, adjusted_α calls samplesize to obtain this value.

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.

Arguments for simulation

Note that the arguments num_sims, seed, and subject_level are for Monte Carlo power calculation

When using Monte Carlo, these are the possible arguments.

num_sims: This is the number of simulation runs to execute. 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 or power analysis 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.

Return value

In case no adjustment is made, the return value is a named tuple similar to this:

(before_adjustment = (α = 0.05, type_I_error = 0.03331, achieved_power = 0.82244, n = [13, 13]), 
after_adjustment = :no_adjustment_made)

In case an adjustment is made, the return value is a named tuple similar to this:

(before_adjustment = (α = 0.05, type_I_error = 0.08269, achieved_power = 0.80225, n = [15, 15]), 
after_adjustment = (α = 0.028163596987724294, type_I_error = 0.05, achieved_power = 0.71536, n = [15, 15]))

BioequivalencePower.adjusted_α_with_samplesize — Method

adjusted_α_with_samplesize(ht::ExpandingLimitsRatioTOST{D},
                           hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
                           max_iter = 10, 
                           power_method::PowerCalculationMethod = MonteCarloPowerCalculation()
                           ) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}

Adjusts α (if needed) and recomputes sample size for target power (if needed). This is for ExpandingLimitsRatioTOST.

See easy-API method doc for full description of the adjusted_α_with_samplesize function.

BioequivalencePower.adjusted_α_with_samplesize — Method

adjusted_α_with_samplesize(::Type{BS}, ::Type{D} = EDDefaultDesign;
                           kwargs...
                           ) where {BS <: BioequivalencePowerStudy, D <: ExperimentalDesign}

This is the easy-API adjusted_α_with_samplesize method.

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:

adjusted_α_with_samplesize(ExpandingLimitsRatioTOST, ED2x3x3PartialReplicate, ...)

At the moment the only supported study type for BS is ExpandingLimitsRatioTOST.

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. The order of the keywords does not matter. Many other keywords are also possible (see below). Here is a minimal working example:

adjusted_α_with_samplesize(ExpandingLimitsRatioTOST, ED2x3x3PartialReplicate, CV = 0.35)

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, the coefficient of variation CV = 0.35 is set in a ExpandingLimitsRatioTOST{ED2x3x3PartialReplicate} object. This object is hidden from the user. The easy-API sees which arguments are supplied and constructs objects based on these arguments before invoking the complete-API internally.

Here is a full list of arguments:

1st argument: Must be ExpandingLimitsRatioTOST.
2nd argument: design. Use one of: ED2x2x3ReplicateCrossover, ED2x2x4ReplicateCrossover, or ED2x3x3PartialReplicate.

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.35. Here is a full list, starting with mandatory argument and following with optional arguments.

Mandatory Arguments

Variability argument: This is CV 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.

Argument for "test/reference" ratio

Argument for limits

Type I error and α

α: By default, α = 0.05. This is the desired type I error.

Further optional Arguments for hypothesis test meta parameters (including assumptions)

n: Can be an integer denoting the total number of subjects or an array of the number of subjects per sequence group, e.g. n = [12, 8]. In the typical case where the total number of subjects is given, the subjects are distributed as uniformly as possible among sequences of the design using the distribute_groups function. If this argument is not given, adjusted_α_with_samplesize calls samplesize to obtain this value.

Special arguments for 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.

Arguments for simulation

Note that the arguments num_sims, seed, and subject_level are for Monte Carlo power calculation

When using Monte Carlo, these are the possible arguments.

num_sims: This is the number of simulation runs to execute. 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 or power analysis 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.

Other arguments

The argument max_iter with a default value of 10 determines an upper bound on the number of adjusted_α function calls.

Return value

The same as adjusted_α yet with a corrected sample size if needed.

BioequivalencePower.ci2cv — Method

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.ci2cv — Method

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.

BioequivalencePower.ci2se — Method

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.

BioequivalencePower.confint_cv — Method

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.

BioequivalencePower.confint_mse — Method

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.cv2mse — Method

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

Convert CV of log-normal data to MSE.

BioequivalencePower.cv2se — Method

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

Convert CV of log-normal data to SE.

BioequivalencePower.distribute_groups — Method

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)

BioequivalencePower.init_single_trial_sim — Method

Monte Carlo simulate single experiment for differences in the case of two TOSTs.

BioequivalencePower.mse2cv — Method

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

Convert MSE of log-normal data to CV.

BioequivalencePower.multiple_treatment_design_matrix — Method

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

BioequivalencePower.pool_cv — Method

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.pool_cv — Method

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

BioequivalencePower.power — Function

power(ht::DoseProportionalityStudy{EDGeneral},
      hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
      power_method::PowerCalculationMethod = ExactPowerCalculation(),
      set_study_type_in_return::Bool = true,
      verbose = true
      )::HypothesisTestMetaParams

Calculate power for a DoseProportionalityStudy with a general design. The design needs to have design_matrix specified, and design needs to be set with ht. Must also set doses and CV in ht, and must set n in hp. The power_method must be MonteCarloPowerCalculation.