statsjunk.samplesize¶

PMSampleSize is a single entry point that dispatches to the right calculation based on outcome_type. Prefer calling compute_binary_sample_size, compute_continuous_sample_size, or compute_survival_sample_size directly — the class exists for parity with the R pmsampsize package's single-function ergonomics.

PMSampleSize ¶

Bases: BaseModel

Minimum sample size for developing a multivariable prediction model.

What this solves

Before collecting data to build any prediction model — continuous, binary, or time-to-event — you need to know how many subjects to enroll. Too few, and the model will overfit — look accurate on the data it was built on, then perform much worse in practice. This is a single entry point that dispatches to the right calculation for your outcome type. Prefer calling compute_binary_sample_size, compute_continuous_sample_size, or compute_survival_sample_size directly — this class exists for parity with the R pmsampsize package's single-function ergonomics.

Implements the criteria proposed by Riley et al. 2019/2020 for minimum sample size when developing a new multivariable prediction model, for continuous, binary, or survival (time-to-event) outcomes.

References

Riley, R.D., Snell, K.I.E., Ensor, J., Burke, D.L., Harrell, F.E. Jr, Moons, K.G., & Collins, G.S. (2019). "Minimum sample size required for developing a multivariable prediction model: Part I continuous outcomes." Statistics in Medicine, 38(7), 1262-1275.
Riley, R.D., Snell, K.I.E., Ensor, J., Burke, D.L., Harrell, F.E. Jr, Moons, K.G., & Collins, G.S. (2019). "Minimum sample size required for developing a multivariable prediction model: Part II binary and time-to-event outcomes." Statistics in Medicine, 38(7), 1276-1296.
Riley, R.D., Van Calster, B., & Collins, G.S. (2020). "A note on estimating the Cox-Snell R2 from a reported C statistic (AUROC) to inform sample size calculations for developing a prediction model with a binary outcome." Statistics in Medicine, 40(4), 859-864.

binary ¶

BinarySampleSizeResult ¶

Bases: BaseModel

Minimum sample size for developing a binary outcome prediction model.

BinaryCriterion ¶

Bases: BaseModel

One row of the binary sample size calculation's criterion breakdown.

compute_binary_sample_size ¶

compute_binary_sample_size(
    parameters: int,
    prevalence: float,
    csrsquared: float | None = None,
    nagrsquared: float | None = None,
    cstatistic: float | None = None,
    shrinkage: float = 0.9,
    seed: int = 123456,
) -> BinarySampleSizeResult

Minimum sample size for developing a binary outcome prediction model.

What this solves

Before collecting data to build a prediction model for a yes/no outcome (e.g. "will this patient be readmitted?"), you need to know how many subjects to enroll. Too few, and the model will overfit — look accurate on the data it was built on, then perform much worse on new patients. This calculates the minimum sample size needed to avoid that, based on how many candidate predictors you plan to consider and how well you expect the model to perform (which you provide via a rough estimate from a previous study — csrsquared, nagrsquared, or cstatistic, any one of which works; you don't need to understand the difference to use one).

Implements the criteria of Riley et al. 2019 ("Minimum sample size required for developing a multivariable prediction model: Part II binary and time-to-event outcomes"):

small overfitting, defined by shrinkage of predictor effects of 10% or less (i.e. shrinkage or higher);
small absolute difference (<= 0.05) between the model's apparent and adjusted Nagelkerke's R^2;
precise estimation (within +/- 0.05) of the average outcome risk in the population.

Exactly one of csrsquared, nagrsquared, or cstatistic must be given, as the anticipated performance of the new model:

csrsquared: the expected Cox-Snell R^2 directly, e.g. taken from the adjusted R^2 of a previous model in the same field.
nagrsquared: the expected Nagelkerke's R^2 (Cox-Snell R^2 rescaled to [0, 1]), converted to Cox-Snell R^2 using prevalence.
cstatistic: a reported C-statistic (AUC), converted to an approximate Cox-Snell R^2 via the Monte Carlo method of Riley, Van Calster & Collins (2020) — see _csrsquared_from_cstatistic.

Parameters:

Name	Type	Description	Default
`parameters`	`int`	Number of candidate predictor parameters for the new model.	required
`prevalence`	`float`	Overall outcome proportion expected in the development dataset, in (0, 1).	required
`csrsquared`	`float`	Exactly one must be given — see above.	`None`
`nagrsquared`	`float`	Exactly one must be given — see above.	`None`
`cstatistic`	`float`	Exactly one must be given — see above.	`None`
`shrinkage`	`float`	Target shrinkage factor at internal validation, in (0, 1].	`0.9`
`seed`	`int`	Seed for the C-statistic Monte Carlo approximation. Ignored unless `cstatistic` is given.	`123456`

Returns:

Type	Description
`BinarySampleSizeResult`	`sample_size` (the maximum across all three criteria) plus the full per-criterion breakdown.

Raises:

Type	Description
`ValueError`	If: - not exactly one of csrsquared/nagrsquared/cstatistic is given - parameters < 1 - prevalence is not in (0, 1) - shrinkage is not in (0, 1] - the resulting csrsquared is <= 0, >= 1, or exceeds the maximum Cox-Snell R^2 attainable at this prevalence - shrinkage is lower than csrsquared

References

Riley, R.D., Snell, K.I.E., Ensor, J., Burke, D.L., Harrell, F.E. Jr, Moons, K.G., & Collins, G.S. (2019). "Minimum sample size required for developing a multivariable prediction model: Part II binary and time-to-event outcomes." Statistics in Medicine, 38(7), 1276-1296.
Riley, R.D., Van Calster, B., & Collins, G.S. (2020). "A note on estimating the Cox-Snell R2 from a reported C statistic (AUROC) to inform sample size calculations for developing a prediction model with a binary outcome." Statistics in Medicine, 40(4), 859-864.

continuous ¶

ContinuousSampleSizeResult ¶

Bases: BaseModel

Minimum sample size for developing a continuous outcome prediction model.

ContinuousCriterion ¶

Bases: BaseModel

One row of the continuous sample size calculation's criterion breakdown.

compute_continuous_sample_size ¶

compute_continuous_sample_size(
    parameters: int,
    rsquared: float,
    intercept: float,
    sd: float,
    shrinkage: float = 0.9,
    mmoe: float = 1.1,
) -> ContinuousSampleSizeResult

Minimum sample size for developing a continuous outcome prediction model.

What this solves

Before collecting data to build a prediction model for a numeric outcome (e.g. predicting blood pressure from a set of risk factors), you need to know how many subjects to enroll. Too few, and the model will overfit — look accurate on the data it was built on, then perform much worse on new subjects. This calculates the minimum sample size needed to avoid that, based on how many candidate predictors you plan to consider and how well you expect the model to perform (a rough R^2 estimate from a previous study is enough).

Implements the criteria of Riley et al. 2018 ("Minimum sample size required for developing a multivariable prediction model: Part I continuous outcomes"):

small overfitting, defined by shrinkage of predictor effects of 10% or less (i.e. shrinkage or higher);
small absolute difference (<= 0.05) between the model's apparent and adjusted R^2;
precise estimation of the residual standard deviation (>= 234 observations, per Riley et al.);
precise estimation of the average outcome value (intercept), within a mmoe multiplicative margin of error.

Parameters:

Name	Type	Description	Default
`parameters`	`int`	Number of candidate predictor parameters for the new model.	required
`rsquared`	`float`	Anticipated (adjusted) R^2 of the new model, in (0, 1).	required
`intercept`	`float`	Average outcome value in the population of interest. Must be nonzero, since the margin-of-error criterion is expressed as a ratio to it.	required
`sd`	`float`	Standard deviation of outcome values in the population.	required
`shrinkage`	`float`	Target shrinkage factor at internal validation, in (0, 1].	`0.9`
`mmoe`	`float`	Acceptable multiplicative margin of error for the intercept (1.1 = 10%). Must be greater than 1.	`1.1`

Returns:

Type	Description
`ContinuousSampleSizeResult`	`sample_size` (the maximum across all four criteria) plus the full per-criterion breakdown and the intercept's confidence interval at the final sample size.

Raises:

Type	Description
`ValueError`	If: - parameters < 1 - rsquared is not in (0, 1) - sd is not positive - intercept is zero - shrinkage is not in (0, 1] - mmoe is not greater than 1

References

Riley, R.D., Snell, K.I.E., Ensor, J., Burke, D.L., Harrell, F.E. Jr, Moons, K.G., & Collins, G.S. (2019). "Minimum sample size required for developing a multivariable prediction model: Part I continuous outcomes." Statistics in Medicine, 38(7), 1262-1275.

survival ¶

SurvivalSampleSizeResult ¶

Bases: BaseModel

Minimum sample size for developing a survival outcome prediction model.

SurvivalCriterion ¶

Bases: BaseModel

One row of the survival sample size calculation's criterion breakdown.

compute_survival_sample_size ¶

compute_survival_sample_size(
    parameters: int,
    rate: float,
    timepoint: float,
    meanfup: float,
    csrsquared: float | None = None,
    nagrsquared: float | None = None,
    shrinkage: float = 0.9,
) -> SurvivalSampleSizeResult

Minimum sample size for developing a survival outcome prediction model.

What this solves

Before collecting data to build a prediction model for a time-to-event outcome (e.g. "how long until a patient relapses?"), you need to know how many subjects — and how many observed events — to plan for. Too few, and the model will overfit — look accurate on the data it was built on, then perform much worse on new subjects. This calculates the minimum sample size needed to avoid that, based on how many candidate predictors you plan to consider, the event rate and follow-up time you expect, and a rough estimate of how well the model should perform (from a previous study in the same area).

Implements the criteria of Riley et al. 2019 ("Minimum sample size required for developing a multivariable prediction model: Part II binary and time-to-event outcomes"), analogous to the binary case but based on the expected number of events rather than the number of observations.

Parameters:

Name	Type	Description	Default
`parameters`	`int`	Number of candidate predictor parameters for the new model.	required
`rate`	`float`	Overall event rate expected in the population, in the same time units as `meanfup` and `timepoint`.	required
`timepoint`	`float`	Timepoint of interest for prediction, same time units as `meanfup`.	required
`meanfup`	`float`	Average (mean) follow-up time anticipated in the development dataset, same time units as `timepoint`.	required
`csrsquared`	`float`	Exactly one must be given, as the anticipated Cox-Snell or Nagelkerke's R^2 of the new model — see `binary.compute_binary_sample_size` for how these relate.	`None`
`nagrsquared`	`float`	Exactly one must be given, as the anticipated Cox-Snell or Nagelkerke's R^2 of the new model — see `binary.compute_binary_sample_size` for how these relate.	`None`
`shrinkage`	`float`	Target shrinkage factor at internal validation, in (0, 1].	`0.9`

Returns:

Type	Description
`SurvivalSampleSizeResult`	`sample_size` (the maximum across all criteria) plus the full per-criterion breakdown and the estimated risk at `timepoint`.

Raises:

Type	Description
`ValueError`	If: - not exactly one of csrsquared/nagrsquared is given - parameters < 1 - rate, timepoint, or meanfup is not positive - shrinkage is not in (0, 1] - the resulting csrsquared is <= 0, >= 1, or exceeds the maximum Cox-Snell R^2 attainable at this rate/follow-up - shrinkage is lower than csrsquared

References

Riley, R.D., Snell, K.I.E., Ensor, J., Burke, D.L., Harrell, F.E. Jr, Moons, K.G., & Collins, G.S. (2019). "Minimum sample size required for developing a multivariable prediction model: Part II binary and time-to-event outcomes." Statistics in Medicine, 38(7), 1276-1296.