Reference and Utility Functions for BioequivalencePower
This is the module of the package:
BioequivalencePower
— ModuleBioequivalencePower
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
— Functionsupported_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
— Typeconst 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
— Typeconst 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
— Typeconst HTAssumptions = Union{NamedTuple,Nothing}
Can be a NamedTuple
, or Nothing
. Used for input of assumptions or nothing
if not defined.
BioequivalencePower.HypothesisTestMetaParams
— TypeHypothesisTestMetaParams(α::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 powerachieved_power
: The achieved power in the test for the sample sizen
.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 havesum(n_g) == n
.study
: The associated study and its parameters. Especially useful whenHypothesisTestMetaParams
is a return type. Default isnothing
.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
— TypeAn abstraction of a bioequivalence hypothesis test power analysis.
Sample size
BioequivalencePower.samplesize
— Functionsamplesize( 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 isnothing
min_num_sims_for_2_phase
andnum_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 istrue
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
orDifferenceTOST
- Reference scaling and/or expanding limits:
ReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
- Tests for NTID (Narrow Therapeutic Index Drug):
NarrowTherapeuticIndexDrugRatioTOST
- Tests in the context of fiducial inference:
FiducialRatioTOST
- Tests with two end points:
TwoDifferenceTOSTs
orTwoRatioTOSTs
- Dose proportionality:
DoseProportionalityStudy
- Non-inferiority tests:
NonInferiorityRatioOST
orNonInferiorityDifferenceOST
- Standard (average) bioequivalence:
2nd argument: design.
- For the study types
RatioTOST
,DifferenceTOST
,TwoDifferenceTOSTs
,TwoRatioTOSTs
,NonInferiorityRatioOST
orNonInferiorityDifferenceOST
, use one of:ED2Parallel
,ED2x2Crossover
,ED3x3Crossover
,ED3x6x3Crossover
,ED4x4Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
,ED2x4x4ReplicateCrossover
,ED2x3x3PartialReplicate
,ED2x4x2Balaam
,ED2x2x2RepeatedCrossover
, orEDPaired
. - For the study types
ExpandingLimitsRatioTOST
orReferenceScaledRatioTOST
use one of:ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
, orED2x3x3PartialReplicate
. - For the study type
NarrowTherapeuticIndexDrugRatioTOST
use one ofED2x2x3ReplicateCrossover
orED2x2x4ReplicateCrossover
. - For the study type
FiducialRatioTOST
use one ofED2Parallel
orED2x2Crossover
. - For the study type
DoseProportionalityStudy
use one ofEDGeneralCrossover
,EDGeneralParallel
, orEDGeneral
.
- For the study types
3rd argument (optional) prior type:
- This argument can only be used with study types
RatioTOST
,DifferenceTOST
,NonInferiorityRatioOST
, orNonInferiorityDifferenceOST
and should be one ofCVSEPrior
,θ0Prior
, orBothCVSEandθ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.
- This argument can only be used with study types
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
useDegreesOfFreedomPriorParameters
orCategoricalPriorParameters
. - If the prior type is
θ0Prior
useStandardErrorPriorParameters
orCategoricalPriorParameters
. - If the prior type is
BothCVSEandθ0Prior
useDegreesOfFreedomAndStandardErrorPriorParameters
orTwoWayCategoricalPriorParameters
.
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 casesSE
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
, andNonInferiorityRatioOST
: SpecifyCV
as a single value.ReferenceScaledRatioTOST
,ExpandingLimitsRatioTOST
, andNarrowTherapeuticIndexDrugRatioTOST
: SpecifyCV
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
, andNonInferiorityDifferenceOST
: SpecifySE
as a single value.FiducialRatioTOST
: Specify bothSE
andSEb
, each as a single value.TwoRatioTOSTs
: SpecifyCV
as a vector of length 2 matching the two end points of the study.TwoDifferenceTOSTs
: SpecifySE
as a vector of length 2 matching the two end points of the study.DoseProportionalityStudy
: SpecifyCV
as a single value. Optionally, specifyCVb
as a single value (default value ofCVb
if not specified is twiceCV
.)
- For
DoseProportionalityStudy
you must also specify the vector of doses viadoses
. 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θ₀
forRatioTOST
,FiducialRatioTOST
,NonInferiorityRatioOST
: Default is at0.95
.peθ₀
forReferenceScaledRatioTOST
,ExpandingLimitsRatioTOST
: Default is at0.9
.peθ₀
forNarrowTherapeuticIndexDrugRatioTOST
: Default is at0.975
ifhighly_variable = false
(default), and at0.95
otherwise (the HVNTID case).peθ₀
forTwoRatioTOSTs
: Default is at the vector[0.95, 0.95]
.
Difference formulation defaults:
peθ₀
forDifferenceTOST
: Default is at0.05
.peθ₀
forNonInferiorityDifferenceOST
: Default is at-0.05
.peθ₀
forTwoDifferenceTOSTs
: Default is at the vector[0.05, 0.05]
.
Dose proportionality default:
peβ₀
forDoseProportionalityStudy
is set at1 + 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
,andDoseProportionalityStudy
we have thatθ₁
andθ₂
are each scalar values with defaultsθ₁ = 0.8
andθ₂ = 1/θ₁
(this is1.25
). - For
DifferenceTOST
we have thatθ₁
andθ₂
are each scalar values with defaultsθ₁ = -0.2
andθ₂ = -θ₁
(this is0.2
). - For
TwoRatioTOSTs
andTwoDifferenceTOSTs
we have thatθ₁
andθ₂
are each vectors of length 2 with default individual entries corresponding toRatioTOST
andDifferenceTOST
. For example forTwoRatioTOSTs
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 is0.8
. The function will search forn
that hastarget_power ≤ achieved_power
.α
: By default,α = 0.05
for most studies with the exception ofFiducialRatioTOST
,NonInferiorityRatioOST
, andNonInferiorityDifferenceOST
where it is set at0.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 defaultn_g = 1
. For standard (average) bioequivalence formulated as a ratio, namelyRatioTOST
, we may use other values ofn_g
if carrying out subject level simulations (subject_level = true
). See more details withsubject_level
below.robust
: Set this to true for a determination of degrees of freedom using a robust formulation. Default isfalse
.test_group_effect
: Set this to true for the specific caseRatioTOST
withn_g
set to greater than one andsubeject_level = true
. In this case a model for testing group effect is first executed. Default isfalse
.
Special arguments for reference scaling and/or expanding limits
reg_symbol
: This is the symbol for theRegulatoryConstants
object set in eitherReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
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 defaultfalse
determines if the study is an NTDI or HVNTDI study. The casehighly_variable
= true yields different behavior for the hypothesis test.regulatory_constant
: Default is-log(0.9)/0.10
(which is about1.053605
), used only inhighly_variable = false
.ratio_threshold
: Default is2.5
.
Special arguments for two simultaneous end points
ρ
: When usingTwoRatioTOSTs
orTwoDifferenceTOSTs
, this is the assumed correlation coefficient between the two endpoints. Default is0.0
and it can be set to any value such that-1 ≤ ρ ≤ 1
.
Special arguments for dose proportionality study
design_matrix
: Use this only withDoseProportionalityStudy
andEDGeneral
specified in the 1st and 2nd arguments respectively. In this casedesign_matrix
should be set to anEDGeneral
design object which encapsulates adesign_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 is1e5
.seed
: This is the simulation seed to use for reproducibility. The default value is an arbitrary1984
value, yet can be set to any integer value. Settingseed = 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 isfalse
.subject_level
: This argument is by defaultfalse
and this implies simulations are based on randomly generating statistics. If set totrue
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 setsubject_level = true
only for the following cases:RatioTOST
, yet only with one of the designsED2x2Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
, orED2x3x3PartialReplicate
.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
— TypeAn empty struct that indicates to use the default power calculation in contrast to specifying a specific method.
BioequivalencePower.ExactPowerCalculation
— TypeExactPowerCalculation(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
— TypeMonteCarloPowerCalculation(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
— Functiondistribute_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
— Functionmultiple_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
— Functioncv2mse(cv::Real) = log(1 + cv^2)
Convert CV of log-normal data to MSE.
BioequivalencePower.mse2cv
— Functionmse2cv(mse::Real) = √(exp(mse) - 1)
Convert MSE of log-normal data to CV.
BioequivalencePower.cv2se
— Functioncv2se(cv::Real) = √cv2mse(cv)
Convert CV of log-normal data to SE.
BioequivalencePower.se2cv
— Functionse2cv(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
— Functionci2cv( ::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
— Functionci2se( 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
— Functionconfint_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
— Functionconfint_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
— Functionpool_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 vector
nor the vector
dfwhich are of the same dimension of
cvs` 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
— Functionunpool_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
— Functionscaled_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
— Functionupper_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
— Functionpower(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
).
See easy-API method doc for full description of the power
function.
power(ht::RatioTOST{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 RatioTOST
. Must set CV
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
).
See easy-API method doc for full description of the power
function.
power(ht::TwoDifferenceTOSTs{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Calculate the power for TwoDifferenceTOSTs
. Must set the vector of length 2, SE
in ht
, and must set n
in hp
. Only MonteCarloPowerCalculation
is supported for power_method
.
See easy-API method doc for full description of the power
function.
power(ht::TwoRatioTOSTs{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Calculate the power for TwoRatioTOSTs
. Must set the vector of length 2, CV
in ht
, and must set n
in hp
. Only MonteCarloPowerCalculation
is supported for power_method
.
See easy-API method doc for full description of the power
function.
power(ht::FiducialRatioTOST{ED2Parallel},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams
Calculate power for a parallel ratio TOST using Fiducial inference. Must set SE
in ht
and must set n
in hp
.
Only MonteCarloPowerCalculation
is supported for power_method
. Uses formula (14), (15), and surrounding formulas, from 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.
See easy-API method doc for full description of the power
function.
power(ht::FiducialRatioTOST{ED2x2Crossover},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams
Calculate power for a 2x2 crossover ratio TOST using Fiducial inference. Must set SE
and SEb
in ht
and must set n
in hp
.
Only MonteCarloPowerCalculation
is supported for power_method
. Uses formulas (14), (17) and (18) from 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.
See easy-API method doc for full description of the power
function.
power(ht::NonInferiorityDifferenceOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = ExactPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Calculate power for a NonInferiorityDifferenceOST
(one sided t-test). Must set SE
and in ht
and must set n
in hp
. The power_method
must be ExactPowerCalculation
.
See easy-API method doc for full description of the power
function.
power(ht::NonInferiorityRatioOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = ExactPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Calculate power for a NonInferiorityRatioOST
(one sided t-test). Must set CV
and in ht
and must set n
in hp
. The power_method
must be ExactPowerCalculation
.
See easy-API method doc for full description of the power
function.
power(ht::NarrowTherapeuticIndexDrugRatioTOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
) where D <: Union{ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}
Calculate power for a NarrowTherapeuticIndexDrugRatioTOST
. NTID is with ht.highly_variable = false
and HVNTID (highly variable) is with ht.highly_variable = true
. Must set CV
and in ht
and must set n
in hp
. The power_method
must be MonteCarloPowerCalculation
.
See easy-API method doc for full description of the power
function.
power(ht::ReferenceScaledRatioTOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}
Calculate power for a ReferenceScaledRatioTOST
study. Must set CV
and in ht
and must set n
in hp
. The power_method
must be MonteCarloPowerCalculation
yet there is the power_method.subject_level = false
case for approximate statistic level simulation and the power_method.subject_level = true
case for subject level simulation.
See easy-API method doc for full description of the power
function.
power(ht::ExpandingLimitsRatioTOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = MonteCarloPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}
Calculate power for an ExpandingLimitsRatioTOST
study. Must set CV
and in ht
and must set n
in hp
. The power_method
must be MonteCarloPowerCalculation
yet there is the power_method.subject_level = false
case for approximate statistic level simulation and the power_method.subject_level = true
case for subject level simulation.
See easy-API method doc for full description of the power
function.
power(ht::DoseProportionalityStudy{EDGeneralCrossover},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = ExactPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams
Calculate power for a DoseProportionalityStudy
with a crossover design. Must set doses
and CV
in ht
, and must set n
in hp
. The power_method
must be MonteCarloPowerCalculation
.
See easy-API method doc for full description of the power
function.
power(ht::DoseProportionalityStudy{EDGeneralParallel},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = ExactPowerCalculation(),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams
Calculate power for a DoseProportionalityStudy
with a parallel design. Must set doses
and CV
in ht
, and must set n
in hp
. The power_method
must be MonteCarloPowerCalculation
.
See easy-API method doc for full description of the 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
.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{DifferenceTOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{DifferenceTOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when SE has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{DifferenceTOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{DifferenceTOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when θ₀ has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{DifferenceTOST{D}, TwoWayCategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{DifferenceTOST{D}, TwoWayCategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when both SE and θ₀ have a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{RatioTOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{RatioTOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a ratio TOST when CV has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{RatioTOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{RatioTOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a ratio TOST when θ₀ has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{RatioTOST{D}, TwoWayCategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{RatioTOST{D}, TwoWayCategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a ratio TOST when both CV and θ₀ have a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{DifferenceTOST{D}, DegreesOfFreedomPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{DifferenceTOST{D}, DegreesOfFreedomPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when SE has a degrees of freedom prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{DifferenceTOST{D}, StandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{DifferenceTOST{D}, StandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when θ₀ has a standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{DifferenceTOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{DifferenceTOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when both SE and θ₀ have a degrees of freedom and standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{RatioTOST{D}, DegreesOfFreedomPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{RatioTOST{D}, DegreesOfFreedomPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a ratio TOST when CV has a degrees of freedom prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{RatioTOST{D}, StandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{RatioTOST{D}, StandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a difference TOST when θ₀ has a standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{RatioTOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{RatioTOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a ratio TOST when both CV and θ₀ have a degrees of freedom and standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{NonInferiorityDifferenceOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{NonInferiorityDifferenceOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority difference one sided test when SE has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{NonInferiorityDifferenceOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{NonInferiorityDifferenceOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority difference one sided test when θ₀ has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{NonInferiorityDifferenceOST{D}, TwoWayCategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{NonInferiorityDifferenceOST{D}, TwoWayCategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority difference one sided test when both SE and θ₀ have a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{NonInferiorityRatioOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{NonInferiorityRatioOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority ratio one sided test when CV has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{NonInferiorityRatioOST{D}, CategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{NonInferiorityRatioOST{D}, CategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority ratio one sided test when when θ₀ has a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{NonInferiorityRatioOST{D}, TwoWayCategoricalPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{NonInferiorityRatioOST{D}, TwoWayCategoricalPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority ratio one sided test when both CV and θ₀ have a categorical prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{NonInferiorityDifferenceOST{D}, DegreesOfFreedomPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{NonInferiorityDifferenceOST{D}, DegreesOfFreedomPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority difference one sided test when SE has a degrees of freedom prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{NonInferiorityDifferenceOST{D}, StandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{NonInferiorityDifferenceOST{D}, StandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority difference one sided test when θ₀ has a standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{NonInferiorityDifferenceOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{NonInferiorityDifferenceOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority difference one sided test when both CV and θ₀ have a degrees of freedom and standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::CVSEPrior{NonInferiorityRatioOST{D}, DegreesOfFreedomPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(CVSEPrior{NonInferiorityRatioOST{D}, DegreesOfFreedomPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority ratio one sided test when CV has a degrees of freedom prior.
See easy-API method doc for full description of the power
function.
power(ht::θ0Prior{NonInferiorityRatioOST{D}, StandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(θ0Prior{NonInferiorityRatioOST{D}, StandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority ratio one sided test when θ₀ has a standard error prior.
See easy-API method doc for full description of the power
function.
power(ht::BothCVSEandθ0Prior{NonInferiorityRatioOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = default_power_method(BothCVSEandθ0Prior{NonInferiorityRatioOST{D}, DegreesOfFreedomAndStandardErrorPriorParameters}),
set_study_type_in_return::Bool = true,
verbose = true
)::HypothesisTestMetaParams where D <: ExperimentalDesign
Expected power of a non inferiority ratio one sided test when both CV and θ₀ have a degrees of freedom and standard error prior.
See easy-API method doc for full description of the power
function.
power(::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 power
method. Its interface is designed to be as easy and simple to use as possible. However, since it encompasses all of the power functionality of the package, the docstring is long.
There are two positional arguments, first the study type BS
and then the design type D
. Type names are used for these arguments. For example:
power(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 expected power in the Bayesian context. For example:
power(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 number of subjects, n
, and 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:
power(RatioTOST, ED2x2x3ReplicateCrossover, n = 20, 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, the number of subjects, n = 20
is automatically set in an HypothesisTestMetaParams
object, and the coefficient of variation CV = 0.32
is set in a RatioTOST{ED2x2x3ReplicateCrossover}
object. These objects 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
orDifferenceTOST
- Reference scaling and/or expanding limits:
ReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
- Tests for NTID (Narrow Therapeutic Index Drug):
NarrowTherapeuticIndexDrugRatioTOST
- Tests in the context of fiducial inference:
FiducialRatioTOST
- Tests with two end points:
TwoDifferenceTOSTs
orTwoRatioTOSTs
- Dose proportionality:
DoseProportionalityStudy
- Non-inferiority tests:
NonInferiorityRatioOST
orNonInferiorityDifferenceOST
- Standard (average) bioequivalence:
2nd argument: design.
- For the study types
RatioTOST
,DifferenceTOST
,TwoDifferenceTOSTs
,TwoRatioTOSTs
,NonInferiorityRatioOST
orNonInferiorityDifferenceOST
, use one of:ED2Parallel
,ED2x2Crossover
,ED3x3Crossover
,ED3x6x3Crossover
,ED4x4Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
,ED2x4x4ReplicateCrossover
,ED2x3x3PartialReplicate
,ED2x4x2Balaam
,ED2x2x2RepeatedCrossover
, orEDPaired
. - For the study types
ExpandingLimitsRatioTOST
orReferenceScaledRatioTOST
use one of:ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
, orED2x3x3PartialReplicate
. - For the study type
NarrowTherapeuticIndexDrugRatioTOST
use one ofED2x2x3ReplicateCrossover
orED2x2x4ReplicateCrossover
. - For the study type
FiducialRatioTOST
use one ofED2Parallel
orED2x2Crossover
. - For the study type
DoseProportionalityStudy
use one ofEDGeneralCrossover
,EDGeneralParallel
, orEDGeneral
.
- For the study types
3rd argument (optional) prior type:
- This argument can only be used with study types
RatioTOST
,DifferenceTOST
,NonInferiorityRatioOST
, orNonInferiorityDifferenceOST
and should be one ofCVSEPrior
,θ0Prior
, orBothCVSEandθ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.
- This argument can only be used with study types
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
useDegreesOfFreedomPriorParameters
orCategoricalPriorParameters
. - If the prior type is
θ0Prior
useStandardErrorPriorParameters
orCategoricalPriorParameters
. - If the prior type is
BothCVSEandθ0Prior
useDegreesOfFreedomAndStandardErrorPriorParameters
orTwoWayCategoricalPriorParameters
.
The keyword arguments following the initial arguments are always set in the form KEY = VALUE
, where for example KEY
can be n
and value can be 20
for indicating the number of subjects. Here is a full list, starting with mandatory arguments and following with optional arguments.
Mandatory Arguments
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 thedistribute_groups
function.- Variability arguments: The typical variability argument is
CV
, but in certain casesSE
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
, andNonInferiorityRatioOST
: SpecifyCV
as a single value.ReferenceScaledRatioTOST
,ExpandingLimitsRatioTOST
, andNarrowTherapeuticIndexDrugRatioTOST
: SpecifyCV
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
, andNonInferiorityDifferenceOST
: SpecifySE
as a single value.FiducialRatioTOST
: Specify bothSE
andSEb
, each as a single value.TwoRatioTOSTs
: SpecifyCV
as a vector of length 2 matching the two end points of the study.TwoDifferenceTOSTs
: SpecifySE
as a vector of length 2 matching the two end points of the study.DoseProportionalityStudy
: SpecifyCV
as a single value. Optionally, specifyCVb
as a single value (default value ofCVb
if not specified is twiceCV
.)
- For
DoseProportionalityStudy
you must also specify the vector of doses viadoses
. 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 power computation is the ratio or difference between the test and reference formulation. That is, power 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θ₀
forRatioTOST
,FiducialRatioTOST
,NonInferiorityRatioOST
: Default is at0.95
.peθ₀
forReferenceScaledRatioTOST
,ExpandingLimitsRatioTOST
: Default is at0.9
.peθ₀
forNarrowTherapeuticIndexDrugRatioTOST
: Default is at0.975
ifhighly_variable = false
(default), and at0.95
otherwise (the HVNTID case).peθ₀
forTwoRatioTOSTs
: Default is at the vector[0.95, 0.95]
.
Difference formulation defaults:
peθ₀
forDifferenceTOST
: Default is at0.05
.peθ₀
forNonInferiorityDifferenceOST
: Default is at-0.05
.peθ₀
forTwoDifferenceTOSTs
: Default is at the vector[0.05, 0.05]
.
Dose proportionality default:
peβ₀
forDoseProportionalityStudy
is set at1 + 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
,andDoseProportionalityStudy
we have thatθ₁
andθ₂
are each scalar values with defaultsθ₁ = 0.8
andθ₂ = 1/θ₁
(this is1.25
). - For
DifferenceTOST
we have thatθ₁
andθ₂
are each scalar values with defaultsθ₁ = -0.2
andθ₂ = -θ₁
(this is0.2
). - For
TwoRatioTOSTs
andTwoDifferenceTOSTs
we have thatθ₁
andθ₂
are each vectors of length 2 with default individual entries corresponding toRatioTOST
andDifferenceTOST
. For example forTwoRatioTOSTs
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)
α
: By default,α = 0.05
for most studies with the exception ofFiducialRatioTOST
,NonInferiorityRatioOST
, andNonInferiorityDifferenceOST
where it is set at0.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 defaultn_g = 1
. For standard (average) bioequivalence formulated as a ratio, namelyRatioTOST
, we may use other values ofn_g
if carrying out subject level simulations (subject_level = true
). See more details withsubject_level
below.robust
: Set this to true for a determination of degrees of freedom using a robust formulation. Default isfalse
.test_group_effect
: Set this to true for the specific caseRatioTOST
withn_g
set to greater than one andsubeject_level = true
. In this case a model for testing group effect is first executed. Default isfalse
.
Special arguments for reference scaling and/or expanding limits
reg_symbol
: This is the symbol for theRegulatoryConstants
object set in eitherReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
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 defaultfalse
determines if the study is an NTDI or HVNTDI study. The casehighly_variable
= true yields different behavior for the hypothesis test.regulatory_constant
: Default is-log(0.9)/0.10
(which is about1.053605
), used only inhighly_variable = false
.ratio_threshold
: Default is2.5
.
Special arguments for two simultaneous end points
ρ
: When usingTwoRatioTOSTs
orTwoDifferenceTOSTs
, this is the assumed correlation coefficient between the two endpoints. Default is0.0
and it can be set to any value such that-1 ≤ ρ ≤ 1
.
Special arguments for dose proportionality study
design_matrix
: Use this only withDoseProportionalityStudy
andEDGeneral
specified in the 1st and 2nd arguments respectively. In this casedesign_matrix
should be set to anEDGeneral
design object which encapsulates adesign_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 power calculation is used. 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. The default is1e5
.seed
: This is the simulation seed to use for reproducibility. The default value is an arbitrary1984
value, yet can be set to any integer value. Settingseed = nothing
, implies no random seed is set.details
: Set this to true to output additional simulation and/or computation output. Default isfalse
.subject_level
: This argument is by defaultfalse
and this implies simulations are based on randomly generating statistics. If set totrue
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 setsubject_level = true
only for the following cases:RatioTOST
, yet only with one of the designsED2x2Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
, orED2x3x3PartialReplicate
.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.
Return value
The return value is always an HypothesisTestMetaParams
object. The achieved_power
field specifies the power.
BioequivalencePower.power_analysis
— Functionpower_analysis(ht::RatioTOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = DefaultPowerCalculation(),
pac::PowerAnalysisConstants = PowerAnalysisConstants()
) where D <: ExperimentalDesign
Power analysis for a ratio TOST (average bio-equivalence).
See easy-API method doc for full description of the power_analysis
function.
poweranalysis(ht::ExpandingLimitsRatioTOST{D}, hp::HypothesisTestMetaParams = HypothesisTestMetaParams(); powermethod::PowerCalculationMethod = DefaultPowerCalculation(), pac::PowerAnalysisConstants = PowerAnalysisConstants() ) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}
Power analysis for an ExpandingLimitsRatioTOST
(expanding limits bio-equivalence).
See easy-API method doc for full description of the power_analysis
function.
power_analysis(ht::ReferenceScaledRatioTOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = DefaultPowerCalculation(),
pac::PowerAnalysisConstants = PowerAnalysisConstants()
) where D <: Union{ED2x3x3PartialReplicate, ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}
Power analysis for an ReferenceScaledRatioTOST
(reference scaled bio-equivalence).
See easy-API method doc for full description of the power_analysis
function.
power_analysis(ht::NarrowTherapeuticIndexDrugRatioTOST{D},
hp::HypothesisTestMetaParams = HypothesisTestMetaParams();
power_method::PowerCalculationMethod = DefaultPowerCalculation(),
pac::PowerAnalysisConstants = PowerAnalysisConstants()
) where D <: Union{ED2x2x4ReplicateCrossover, ED2x2x3ReplicateCrossover}
Power analysis for an HypothesisTestMetaParams
(bio-equivalence for NTID).
See easy-API method doc for full description of the power_analysis
function.
power_analysis(::Type{BS}, ::Type{D} = EDDefaultDesign;
kwargs...
) where {BS <: BioequivalencePowerStudy, D <: ExperimentalDesign}
This is the easy-API power_analysis
method. Its interface is designed to be as easy and simple to use as possible. However, since it encompasses all of the power_analysis 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:
power_analysis(RatioTOST, ED2x2x3ReplicateCrossover, ...)
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:
power_analysis(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 the coefficient of variation CV = 0.32
is set in a RatioTOST{ED2x2x3ReplicateCrossover}
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 some of the
BioequivalencePowerStudy
sub-types are supported). One of:- Standard (average) bioequivalence:
RatioTOST
- Reference scaling and/or expanding limits:
ReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
- Tests for NTID (Narrow Therapeutic Index Drug):
NarrowTherapeuticIndexDrugRatioTOST
- Standard (average) bioequivalence:
2nd argument: design.
- For the study type
RatioTOST
use one of:ED2Parallel
,ED2x2Crossover
,ED3x3Crossover
,ED3x6x3Crossover
,ED4x4Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
,ED2x4x4ReplicateCrossover
,ED2x3x3PartialReplicate
,ED2x4x2Balaam
,ED2x2x2RepeatedCrossover
, orEDPaired
. - For the study types
ExpandingLimitsRatioTOST
orReferenceScaledRatioTOST
use one of:ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
, orED2x3x3PartialReplicate
. - For the study type
NarrowTherapeuticIndexDrugRatioTOST
use one ofED2x2x3ReplicateCrossover
orED2x2x4ReplicateCrossover
.
- For the study type
The keyword arguments following the initial two 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 argument: This is
CV
. It should always be a single positive value. Note that vector CV for heteroscedasticity is not supported as part ofpower_analysis
.
Argument for "test/reference" ratio
A key input to the power analysis is the ratio between the test and reference formulation. That is, power is computed based on such a postulated point, and that point is varied. It is denoted θ₀ with variable name peθ₀
. All of the study types set default for this argument, and you can naturally override that default.
peθ₀
forRatioTOST
: Default is at0.95
.peθ₀
forReferenceScaledRatioTOST
,ExpandingLimitsRatioTOST
: Default is at0.9
.peθ₀
forNarrowTherapeuticIndexDrugRatioTOST
: Default is at0.975
ifhighly_variable = false
(default), and at0.95
otherwise (the HVNTID case).
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.
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 is0.8
. When initially determining the sample size,power_analysis
will search forn
that hastarget_power ≤ achieved_power
.α
: By default,α = 0.05
.robust
: Set this to true for a determination of degrees of freedom using a robust formulation. Default isfalse
.
Special arguments for reference scaling and/or expanding limits
reg_symbol
: This is the symbol for theRegulatoryConstants
object set in eitherReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
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 defaultfalse
determines if the study is an NTDI or HVNTDI study. The casehighly_variable
= true yields different behavior for the hypothesis test.regulatory_constant
: Default is-log(0.9)/0.10
(which is about1.053605
), used only inhighly_variable = false
.ratio_threshold
: Default is2.5
.
Arguments for simulation and computation
Note that the arguments num_sims
, seed
, and subject_level
are specific to a case where Monte Carlo power calculation is used. 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.
In the context of power_analysis
, the study type with default as exact calculation and an option for Monte Carlo is: RatioTOST
.
Similarly, the study types with only Monte Carlo are: ReferenceScaledRatioTOST
, ExpandingLimitsRatioTOST
, and NarrowTherapeuticIndexDrugRatioTOST
.
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 is1e5
.seed
: This is the simulation seed to use for reproducibility. The default value is an arbitrary1984
value, yet can be set to any integer value. Settingseed = 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 isfalse
.subject_level
: This argument is by defaultfalse
and this implies simulations are based on randomly generating statistics. If set totrue
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 setsubject_level = true
only for the following cases:ReferenceScaledRatioTOST
with any of the supported designs of the study.ExpandingLimitsRatioTOST
with any of the supported designs of the study.
Return value
The return value is a tuple that represents the power analysis information.
BioequivalencePower.adjusted_α
— Functionadjusted_α(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.
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.
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
orExpandingLimitsRatioTOST
.2nd argument: design. Use one of:
ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
, orED2x3x3PartialReplicate
.
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 isnothing
. 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 thedistribute_groups
function. If this argument is not given,adjusted_α
callssamplesize
to obtain this value.
Special arguments for reference scaling and/or expanding limits
reg_symbol
: This is the symbol for theRegulatoryConstants
object set in eitherReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
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 is1e5
.seed
: This is the simulation seed to use for reproducibility. The default value is an arbitrary1984
value, yet can be set to any integer value. Settingseed = 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 isfalse
.subject_level
: This argument is by defaultfalse
and this implies simulations are based on randomly generating statistics. If set totrue
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
— Functionadjusted_α_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.
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
, orED2x3x3PartialReplicate
.
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
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.
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 thedistribute_groups
function. If this argument is not given,adjusted_α_with_samplesize
callssamplesize
to obtain this value.
Special arguments for expanding limits
reg_symbol
: This is the symbol for theRegulatoryConstants
object set in eitherReferenceScaledRatioTOST
orExpandingLimitsRatioTOST
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 is1e5
.seed
: This is the simulation seed to use for reproducibility. The default value is an arbitrary1984
value, yet can be set to any integer value. Settingseed = 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 isfalse
.subject_level
: This argument is by defaultfalse
and this implies simulations are based on randomly generating statistics. If set totrue
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.
StatsAPI.confint
— Functionconfint(ht::DifferenceTOST{D}, hp::HypothesisTestMetaParams) where D <: ExperimentalDesign
Calculate a 1-2α CI associated with a differences bio-equivalence test. Only the point estimate and SE are used from ht
.
See easy-API method doc for full description of the confint
function.
confint(ht::RatioTOST{D}, hp::HypothesisTestMetaParams) where D <: ExperimentalDesign
Calculate a 1-2α CI associated with a ratio bio-equivalence test. Only the point estimate and CV are used from ht
.
See easy-API method doc for full description of the confint
function.
confint(ht::FiducialRatioTOST{ED2Parallel}, hp::HypothesisTestMetaParams)
Calculate a 1-2α fiducial CI associated. Only the point estimate and SE values are used from ht
.
See easy-API method doc for full description of the confint
function.
This method for FiducialRatioTOST{ED2Parallel}
uses formula (6) with reference = 1, from 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.
confint(ht::FiducialRatioTOST{ED2x2Crossover}, hp::HypothesisTestMetaParams)
Calculate a 1-2α fiducial CI associated. Only the point estimate and SE values are used from ht
.
See easy-API method doc for full description of the confint
function.
This method for FiducialRatioTOST{ED2x2Crossover}
uses formula (9) with reference = 1, from 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."
confint(::Type{BS}, ::Type{D} = EDDefaultDesign;
kwargs...
) where {BS <: BioequivalencePowerStudy, D <: ExperimentalDesign}
This is the easy-API confint
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:
confint(RatioTOST, ED2x2x3ReplicateCrossover, ...)
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 number of subjects, n
, the variability parameter, CV
(can also be SE
in certain cases), and the point estimate peθ₀
(note that the point estimate has a default value when we use the complete-API but with the easy-API we purposefully do not have a default value). The order of the keywords does not matter. Several other keywords are also possible (see below). Here is a minimal working example:
confint(RatioTOST, ED2x2x3ReplicateCrossover, n = 20, CV = 0.32, peθ₀ = 0.9)
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 number of subjects, n = 20
is automatically set in an HypothesisTestMetaParams
object, and the coefficient of variation CV = 0.32
is set in a RatioTOST{ED2x2x3ReplicateCrossover}
object, similarly for peθ₀
. These objects 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
orDifferenceTOST
- Tests in the context of fiducial inference:
FiducialRatioTOST
- Standard (average) bioequivalence:
2nd argument: design.
- For the study types
RatioTOST
orDifferenceTOST
, use one of:ED2Parallel
,ED2x2Crossover
,ED3x3Crossover
,ED3x6x3Crossover
,ED4x4Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
,ED2x4x4ReplicateCrossover
,ED2x3x3PartialReplicate
,ED2x4x2Balaam
,ED2x2x2RepeatedCrossover
, orEDPaired
. - For the study type
FiducialRatioTOST
use one ofED2Parallel
orED2x2Crossover
.
- For the study types
The keyword arguments following the initial arguments are always set in the form KEY = VALUE
, where for example KEY
can be n
and value can be 20
for indicating the number of subjects. Here is a full list, starting with mandatory arguments and following with optional arguments.
Mandatory Arguments
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 thedistribute_groups
function.- Variability arguments: The typical variability argument is
CV
, but in certain casesSE
is used instead. In other cases secondary variability arguments are required. Note that variability arguments are always positive.RatioTOST
: SpecifyCV
as a single value.DifferenceTOST
: SpecifySE
as a single value.FiducialRatioTOST
: Specify bothSE
andSEb
, each as a single value.
peθ₀
: This is the observed point estimate of the "test/reference" ratio or difference.
Optional Arguments for hypothesis test meta parameters (including assumptions)
α
: By default,α = 0.05
unless it usingFiducialRatioTOST
, where it is set at0.025
(note that this adjusted default is only applicable via the easy-API and not via the complete-API).robust
: Set this to true for a determination of degrees of freedom using a robust formulation. Default isfalse
.
Return value
The return value is a tuple that has the lower and upper limits of the confidence interval.
StatsAPI.pvalue
— Functionpvalue(ht::DifferenceTOST{D},
hp::HypothesisTestMetaParams;
both_p_values = false) where D <: ExperimentalDesign
Calculate the p-value for a Differences Bio-equivalence test.
See easy-API method doc for full description of the pvalue
function.
pvalue(ht::RatioTOST{D},
hp::HypothesisTestMetaParams;
both_p_values = false) where D <: ExperimentalDesign
Calculate the p-value for a Ratio Bio-equivalence test.
See easy-API method doc for full description of the pvalue
function.
pvalue(::Type{BS}, ::Type{D} = EDDefaultDesign;
kwargs...) where {BS <: BioequivalencePowerStudy, D <: ExperimentalDesign}
This is the easy-API pvalue
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:
pvalue(RatioTOST, ED2x2x3ReplicateCrossover, ...)
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 number of subjects, n
, the variability parameter, CV
or SE
, and the point estimate peθ₀
(note that the point estimate has a default value when we use the complete-API but with the easy-API we purposefully do not have a default value). The order of the keywords does not matter. Several other keywords are also possible (see below). Here is a minimal working example:
pvalue(RatioTOST, ED2x2x3ReplicateCrossover, n = 20, CV = 0.32, peθ₀ = 0.9)
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 number of subjects, n = 20
is automatically set in an HypothesisTestMetaParams
object, and the coefficient of variation CV = 0.32
is set in a RatioTOST{ED2x2x3ReplicateCrossover}
object, similarly for peθ₀
. These objects 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 and only standard (average) bioequivalence is supported. Hence the argument is one of
RatioTOST
orDifferenceTOST
.2nd argument: design. One of:
ED2Parallel
,ED2x2Crossover
,ED3x3Crossover
,ED3x6x3Crossover
,ED4x4Crossover
,ED2x2x3ReplicateCrossover
,ED2x2x4ReplicateCrossover
,ED2x4x4ReplicateCrossover
,ED2x3x3PartialReplicate
,ED2x4x2Balaam
,ED2x2x2RepeatedCrossover
, orEDPaired
.
The keyword arguments following the initial arguments are always set in the form KEY = VALUE
, where for example KEY
can be n
and value can be 20
for indicating the number of subjects. Here is a full list, starting with mandatory arguments and following with optional arguments.
Mandatory Arguments
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 thedistribute_groups
function.- Variability arguments: The typical variability argument is
CV
, but in certain casesSE
is used instead. Note that variability arguments are always positive.RatioTOST
: SpecifyCV
as a single value.DifferenceTOST
: SpecifySE
as a single value.
peθ₀
: This is the observed point estimate of the "test/reference" ratio or difference.
Optional Arguments for hypothesis test meta parameters (including assumptions)
robust
: Set this to true for a determination of degrees of freedom using a robust formulation. Default isfalse
.
Additional arguments
both_p_values
: Set this totrue
if you wish for the return value to be both the p-values (from each of the one sided tests that make up a TOST). Default is 'false'.
Return value
The return value is a p-value, unless both_p_values = true
in which case the return value is a tuple of two p-values.