Variations & designs

AbstractVariation

Abstract type for variations.

Subtypes

ElementaryVariation, DiscreteVariation, DistributedVariation, CoVariation

AddGridVariationsResult <: AddVariationsResult

Result of addVariations with GridVariation: the full factorial grid.

Fields

• variation_ids::AbstractArray{VariationID}: One VariationID per grid point, i.e. per combination of the discrete variation values. The array's shape mirrors the grid axes (one dimension per varied parameter).

AddLHSVariationsResult <: AddVariationsResult

Result of addVariations with LHSVariation (Latin Hypercube Sampling).

Fields

• cdfs::Matrix{Float64}: The sampled CDF coordinates in [0, 1], one row per latent dimension and one column per sample point (shape (d, n)).
• variation_ids::Vector{VariationID}: One VariationID per sample point, in the same order as the columns of cdfs.

AddRBDVariationsResult <: AddVariationsResult

Result of addVariations with RBDVariation (Random Balance Design).

Fields

• variation_ids::AbstractArray{VariationID}: One VariationID per sampled point, in CDF-sample order.
• variation_matrix::Matrix{VariationID}: The same IDs re-sorted into the RBD layout — one column per latent parameter, rows ordered along each parameter's periodic RBD curve. This is the form consumed by the RBD-FAST spectral analysis.

AddSobolVariationsResult <: AddVariationsResult

Result of addVariations with SobolVariation (Sobol quasi-random sequence).

Fields

• cdfs::Array{Float64,3}: The Sobol CDF coordinates in [0, 1], indexed by latent dimension, sample, and design matrix.
• variation_ids::AbstractArray{VariationID}: One VariationID per sample, arranged with one row per sample and one column per design matrix (shape (n, n_matrices)).

AddVariationMethod

Abstract type for variation sampling methods.

Subtypes

GridVariation, LHSVariation, SobolVariation, RBDVariation

AddVariationsResult

Abstract type for the result of addVariations.

CoVariation{T<:ElementaryVariation} <: AbstractVariation

A co-variation of one or more ElementaryVariations that are varied together.

Each constituent variation must be of the same subtype (all DiscreteVariation or all DistributedVariation).

DiscreteVariation{T} <: ElementaryVariation

The location, target, and values of a discrete variation.

Fields

• location::Symbol: The location (input-folder category) for this variation.
• target::XMLPath: The XML path to the element being varied.
• values::Vector{T}: The possible values that the target can take on.

A singleton value can be passed in place of values for convenience.

location must be provided explicitly. Simulator packages (e.g. PhysiCellModelManager) may provide convenience constructors that infer location from the target.

DistributedVariation <: ElementaryVariation

The location, target, and distribution of a distributed variation.

Fields

• location::Symbol: The location (input-folder category) for this variation.
• target::XMLPath: The XML path to the element being varied.
• distribution::Distribution: The distribution of the variation.
• flip::Bool=false: Whether to flip the distribution (iCDF of 1-x instead of x).

location must be provided explicitly. Simulator packages (e.g. PhysiCellModelManager) may provide convenience constructors that infer location from the target.

ElementaryVariation <: AbstractVariation

The base type for variations of a single parameter.

GridVariation <: AddVariationMethod

Enumerate all combinations of discrete variation values (full factorial grid).

LHSVariation <: AddVariationMethod

Latin Hypercube Sampling.

Fields

• n::Int: Number of samples.
• add_noise::Bool=false: Whether to add noise within each bin.
• rng::AbstractRNG=Random.GLOBAL_RNG
• orthogonalize::Bool=true

LatentVariation{T<:Union{Vector{<:Real},<:Distribution}} <: AbstractVariation

A variation that uses latent parameters to generate target parameter values via mapping functions.

Whereas CoVariations enforce a 1D relationship between parameters, LatentVariations allow multi-dimensional relationships via user-supplied maps. The latent parameters themselves are not stored in the database; only the derived target values are.

Internally, ParsedVariations converts all variations to LatentVariations for processing.

Fields

• latent_parameters: Discrete value vectors or prior Distributions, one per latent dimension.
• latent_parameter_names: User-friendly names for each latent dimension.
• locations: XML location symbols, one per target.
• targets: XML paths to each target parameter.
• target_names: User-friendly display names for each target parameter. Derived from the source variation names when constructed via factory methods (DistributedVariation, CoVariation). For direct construction, supply via the target_names keyword; defaults to shortVariationName(location, columnName(target)) for each target.
• maps: Forward maps — each map_j(lp_vals::Vector) → scalar computes one target value from all latent values.
• inverse_maps: Optional inverse maps — each inv_map_i(target_vals::Vector{Float64}) → Float64 recovers the latent parameter value lp_i for latent dimension i from the full vector of target values (ordered by targets). The library applies cdf(dist_i, lp_i) internally to obtain the CDF coordinate. One inverse per latent dimension. Required for SimulationBank support with LVSource calibration parameters. Auto-constructed for DVSource/CVSource-backed LatentVariations. Supply via the inverse_maps keyword argument when constructing a user-defined LatentVariation{<:Distribution}. Monotonicity of the forward map is a user responsibility and is not validated at construction time beyond a round-trip accuracy check.
• types: Output eltype of each forward map's return value.
• name: User-supplied or default name.

Construction

From existing variation types (preferred for single-parameter calibration)

# From a DistributedVariation — inverse_maps auto-constructed
dv = DistributedVariation(:config, XMLPath(["tumor", "growth_rate"]), Uniform(0.01, 0.5))
lv = LatentVariation(dv)

# From a CoVariation{DistributedVariation} — inverse_maps auto-constructed
cv = CoVariation(DistributedVariation(:config, XMLPath(["k1"]), Uniform(0.1, 1.0)),
                 DistributedVariation(:config, XMLPath(["k2"]), Uniform(0.5, 5.0)))
lv = LatentVariation(cv)

Direct construction with continuous latent parameters

The positional arguments are: LatentVariation(latent_parameters, targets, maps, lp_names, locations; inverse_maps, name)

• 1 latent dim, 1 target — log-normal forward map:

# lp ~ Normal(0,1); target = exp(lp)
lv = LatentVariation(
    [Normal(0.0, 1.0)],
    XMLPath[XMLPath(["tumor", "growth_rate"])],
    Function[lp -> exp(lp[1])],
    ["log_growth_rate"],
    Symbol[:config];
    target_names=["growth rate"],
    inverse_maps=Function[tv -> log(tv[1])]   # returns lp, not CDF
)

• 2 latent dims, 2 targets — independent priors:

# lp1 ~ Uniform(0,1), lp2 ~ Uniform(0,1); target1 = 4*lp1, target2 = 2*lp2
lv = LatentVariation(
    [Uniform(0.0, 1.0), Uniform(0.0, 1.0)],
    XMLPath[XMLPath(["k1"]), XMLPath(["k2"])],
    Function[lp -> 4.0 * lp[1], lp -> 2.0 * lp[2]],
    ["lp1", "lp2"],
    Symbol[:config, :config];
    target_names=["rate k1", "rate k2"],
    inverse_maps=Function[tv -> tv[1] / 4.0, tv -> tv[2] / 2.0]
)

• 2 latent dims, 2 targets — coupled targets (e.g. p1 = lp1, p2 = lp1 + lp2):

lv = LatentVariation(
    [Uniform(0.0, 1.0), Uniform(0.0, 1.0)],
    XMLPath[XMLPath(["p1"]), XMLPath(["p2"])],
    Function[lp -> lp[1], lp -> lp[1] + lp[2]],
    ["lp1", "lp2"],
    Symbol[:config, :config];
    target_names=["p1", "p2"],
    inverse_maps=Function[tv -> tv[1], tv -> tv[2] - tv[1]]
)

Direct construction with discrete latent parameters

# Discrete index maps to named configurations
lv = LatentVariation(
    [[1.0, 2.0, 3.0]],
    XMLPath[XMLPath(["scenario"])],
    Function[lp -> lp[1]],
    ["scenario_index"],
    Symbol[:config]
)

RBDVariation <: AddVariationMethod

Random Balance Design sampling.

Fields

• n::Int
• rng::AbstractRNG=Random.GLOBAL_RNG
• use_sobol::Bool=true
• pow2_diff::Union{Missing,Int}=missing
• num_cycles::Union{Missing,Int,Rational}=missing

SobolVariation <: AddVariationMethod

Sobol quasi-random sequence sampling.

Fields

• n::Int: Number of samples.
• n_matrices::Int=1: Number of design matrices.
• randomization::RandomizationMethod=NoRand()
• skip_start::Union{Missing,Bool,Int}=missing
• include_one::Union{Missing,Bool}=missing

XMLPath

Hold an XML path as a vector of strings, where each element is a node in the path.

A : in a path element denotes an attribute filter, e.g. "cell_definition:name:default" selects the <cell_definition> whose name attribute equals "default". A double-colon :: separates a parent tag from a child tag used as a filter.

NormalDistributedVariation(location, target, mu, sigma; lb=-Inf, ub=Inf, flip=false)

Create a (possibly truncated) DistributedVariation with a Normal distribution.

location must be provided explicitly. Simulator packages (e.g. PhysiCellModelManager) may provide convenience constructors that infer location from the target.

UniformDistributedVariation(location, xml_path, lb, ub; flip=false)

Create a DistributedVariation with a Uniform(lb, ub) distribution.

location must be provided explicitly. Simulator packages (e.g. PhysiCellModelManager) may provide convenience constructors that infer location from the target.

addVariations(method::AddVariationMethod, inputs::InputFolders, avs::Vector{<:AbstractVariation},
              reference_variation_id::VariationID=VariationID(inputs))

Add variations to inputs using method and return an AddVariationsResult.

columnName(xml_path::Vector{<:AbstractString})

Join an XML path vector into a slash-separated column name string.

defaultLatentParameterNames(latent_parameters::Vector, targets::Vector{XMLPath})

Generate default names for latent parameters based on target column names.

For each latent parameter, the name is constructed as: "<target_1> | <target_2> | ... | lp#<i>" where <target_n> is the column name of the n-th target parameter and <i> is the index of the latent parameter.

Returns

• Vector{String}: A vector of default names for the latent parameters.

getAllParameterValues(simulation_id::Int)
getAllParameterValues(S::AbstractSampling)

Get all parameter values for the given simulation, monad, or sampling as a DataFrame. Simulation ID can also be passed directly as an integer.

Identifying attributes

If sibling elements have identical tags, attributes are programmatically searched to find one that can be used to identify them. Priority is given to "name", "ID", and "id" attributes. If sibling elements cannot be uniquely identified by an attribute, artificial IDs will be added to the XML paths to ensure uniqueness for the column names. These will show up as <tag>:temp_id:<index> in the column names. Search for them with contains(col_name, ":temp_id:"). Note: these are not added to the XML files themselves. Users must manually insert such artificial IDs into their XML files to use PCMM to vary those parameters.

Converting column names into XML paths

To convert the column names in the returned DataFrame back into XML paths, split the column names by '/':

df = getAllParameterValues(simulation_id)
col1 = names(df)[1]
xml_path = split(col1, '/')

Alternatively, columnNameToXMLPath can be used.

xml_path = columnNameToXMLPath(col1)

getParameterValue(M::AbstractMonad, location::Symbol, xp::XMLPath)

Get the parameter value for xp at location from the monad's variations database if the column exists, otherwise fall back to the base XML file.

• Boolean strings ("true" / "false") are returned as Bool.
• Numeric strings are returned as Float64.
• Everything else is returned as-is.

parseValueFromString(v::String)

Parse a string value: return Bool for "true"/"false", Float64 if numeric, or the original string otherwise.

sqliteDataType(ev::ElementaryVariation)
sqliteDataType(data_type::DataType)

Map a Julia data type to its SQLite column type string.

validateParsBytes(db::SQLite.DB, table_name::String)

Assert that the par_key blob in every row of table_name matches the float64 reinterpretation of the other columns.

variationName(av::AbstractVariation)

Get the user-facing name of a variation used in reports and sensitivity scheme headers. If no explicit name was provided to the constructor, this is a convention-based default derived from shortVariationName(location, columnName(target)).