Variations

CoVariation{T<:ElementaryVariation} <: AbstractVariation

A co-variation of one or more variations. Each must be of the same type, either DiscreteVariation or DistributedVariation.

Fields

• variations::Vector{T}: The variations that make up the co-variation.

Constructors

• CoVariation(inputs::Vararg{Tuple{Vector{<:AbstractString},Distribution},N}) where {N}: Create a co-variation from a vector of XML paths and distributions.

CoVariation((xml_path_1, d_1), (xml_path_2, d_2), ...) # d_i are distributions, e.g. `d_1 = Uniform(1, 2)`

• CoVariation(inputs::Vararg{Tuple{Vector{<:AbstractString},Vector},N}) where {N}: Create a co-variation from a vector of XML paths and values.

CoVariation((xml_path_1, val_1), (xml_path_2, val_2), ...) # val_i are vectors of values, e.g. `val_1 = [0.1, 0.2]`, or singletons, e.g. `val_2 = 0.3`

• CoVariation(evs::Vector{ElementaryVariation}): Create a co-variation from a vector of variations all the same type.

CoVariation([discrete_1, discrete_2, ...]) # all discrete variations and with the same number of values
CoVariation([distributed_1, distributed_2, ...]) # all distributed variations

• CoVariation(inputs::Vararg{T}) where {T<:ElementaryVariation}: Create a co-variation from a variable number of variations all the same type.

CoVariation(discrete_1, discrete_2, ...) # all discrete variations and with the same number of values
CoVariation(distributed_1, distributed_2, ...) # all distributed variations

DiscreteVariation

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

Fields

• location::Symbol: The location of the variation. Can be :config, :rulesets_collection, :intracellular, :ic_cell, :ic_ecm. The location is inferred from the target.
• target::XMLPath: The target of the variation. The target is a vector of strings that represent the XML path to the element being varied. See XMLPath for more information.
• values::Vector{T}: The values of the variation. The values are the possible values that the target can take on.

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

Examples

julia> dv = DiscreteVariation(["overall", "max_time"], [1440.0, 2880.0])
DiscreteVariation (Float64):
  location: config
  target: overall/max_time
  values: [1440.0, 2880.0]

xml_path = rulePath("default", "cycle entry", "decreasing_signals", "max_response")
DiscreteVariation(xml_path, 0)
# output
DiscreteVariation (Int64):
  location: rulesets_collection
  target: behavior_ruleset:name:default/behavior:name:cycle entry/decreasing_signals/max_response
  values: [0]

xml_path = icCellsPath("default", "disc", 1, "x0")
DiscreteVariation(xml_path, [0.0, 100.0])
# output
DiscreteVariation (Float64):
  location: ic_cell
  target: cell_patches:name:default/patch_collection:type:disc/patch:ID:1/x0
  values: [0.0, 100.0]

```jldoctest xmlpath = icECMPath(2, "ellipse", 1, "density") DiscreteVariation(xmlpath, [0.1, 0.2])

output

DistributedVariation: location: icecm target: layer:ID:2/patchcollection:type:ellipse/patch:ID:1/density values: [0.1, 0.2]

DistributedVariation

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

Analagousy to DiscreteVariation, instances of DistributedVariation can be initialized with a target (XML path) and a distribution (a distribution from the Distributions package). Alternatively, users can use the UniformDistributedVariation and NormalDistributedVariation functions to create instances of DistributedVariation.

Fields

• location::Symbol: The location of the variation. Can be :config, :rulesets_collection, :intracellular, :ic_cell, or :ic_ecm. The location is inferred from the target.
• target::XMLPath: The target of the variation. The target is a vector of strings that represent the XML path to the element being varied. See XMLPath for more information.
• distribution::Distribution: The distribution of the variation.
• flip::Bool=false: Whether to flip the distribution, i.e., when asked for the iCDF of x, return the iCDF of 1-x. Useful for CoVariation's.

Examples

using Distributions
d = Uniform(1, 2)
DistributedVariation(pcvct.apoptosisPath("default", "death_rate"), d)
# output
DistributedVariation:
  location: config
  target: cell_definitions/cell_definition:name:default/phenotype/death/model:code:100/death_rate
  distribution: Distributions.Uniform{Float64}(a=1.0, b=2.0)

```jldoctest using Distributions d = Uniform(1, 2) flip = true # the cdf on this variation will decrease from 1 to 0 as the value increases from 1 to 2 DistributedVariation(pcvct.necrosisPath("default", "death_rate"), d, flip)

output

DistributedVariation (flipped): location: config target: celldefinitions/celldefinition:name:default/phenotype/death/model:code:101/death_rate distribution: Distributions.Uniform{Float64}(a=1.0, b=2.0)

ElementaryVariation <: AbstractVariation

The base type for variations of a single parameter.

GridVariation <: AddVariationMethod

A variation method that creates a grid of all possible combinations of the values of the variations.

Examples

julia> GridVariation() # the only method for GridVariation
GridVariation()

LHSVariation <: AddVariationMethod

A variation method that creates a Latin Hypercube Sample of the values of the variations.

Fields

Default values from constructors are shown.

• n::Int: The number of samples to take.
• add_noise::Bool=false: Whether to add noise to the samples or have them be in the center of the bins.
• rng::AbstractRNG=Random.GLOBAL_RNG: The random number generator to use.
• orthogonalize::Bool=true: Whether to orthogonalize the samples. See https://en.wikipedia.org/wiki/Latinhypercubesampling#:~:text=In%20orthogonal%20sampling

Examples

julia> LHSVariation(4) # set `n` and use default values for the rest
LHSVariation(4, false, Random.TaskLocalRNG(), true)

using Random
LHSVariation(; n=16, add_noise=true, rng=MersenneTwister(1234), orthogonalize=false)
# output
LHSVariation(16, true, MersenneTwister(1234), false)

RBDVariation <: AddVariationMethod

A variation method that creates a Random Balance Design of the values of the variations.

This creates n sample points where the values in each dimension are uniformly distributed. By default, this will use Sobol sequences (see SobolVariation) to create the sample points. If use_sobol is false, it will use random permutations of uniformly spaced points for each dimension.

Fields

Default values from constructors are shown.

• n::Int: The number of samples to take.
• rng::AbstractRNG=Random.GLOBAL_RNG: The random number generator to use.
• use_sobol::Bool=true: Whether to use Sobol sequences to create the sample points.

Do not set these next two fields unless you know what you are doing. Let pcvct compute them.

• pow2_diff::Union{Missing, Int}=missing: The difference between n and the nearest power of 2. Missing means pcvct will compute it if using Sobol sequences.
• num_cycles::Union{Missing, Int, Rational}=missing: The number of cycles to use in the Sobol sequence. Missing means pcvct will set it.

Examples

julia> pcvct.RBDVariation(4) # set `n` and use default values for the rest
RBDVariation(4, Random.TaskLocalRNG(), true, 0, 1//2)

julia> pcvct.RBDVariation(4; use_sobol=false) # use random permutations of uniformly spaced points
RBDVariation(4, Random.TaskLocalRNG(), false, missing, 1//1)

SobolVariation <: AddVariationMethod

A variation method that creates a Sobol sequence of the values of the variations.

See generateSobolCDFs for more information on how the Sobol sequence is generated based on n and the other fields.

See the GlobalSensitivity.jl package for more information on RandomizationMethod's to use.

Fields

Default values from constructors are shown.

• n::Int: The number of samples to take.
• n_matrices::Int=1: The number of matrices to use in the Sobol sequence.
• randomization::RandomizationMethod=NoRand(): The randomization method to use on the deterministic Sobol sequence.
• skip_start::Union{Missing, Bool, Int}=missing: Whether to skip the start of the sequence. Missing means pcvct will choose the best option.
• include_one::Union{Missing, Bool}=missing: Whether to include 1 in the sequence. Missing means pcvct will choose the best option.

Examples

julia> SobolVariation(9) # set `n` and use default values for the rest; will use [0, 0.5, 0.25, 0.75, 0.125, 0.375, 0.625, 0.875, 1]
SobolVariation(9, 1, QuasiMonteCarlo.NoRand(), missing, missing)

julia> SobolVariation(15; skip_start=true) # use [0.5, 0.25, 0.75, ..., 1/16, 3/16, ..., 15/16]
SobolVariation(15, 1, QuasiMonteCarlo.NoRand(), true, missing)

julia> SobolVariation(4; include_one=true) # use [0, 0.5, 1] and one of [0.25, 0.75]
SobolVariation(4, 1, QuasiMonteCarlo.NoRand(), missing, true)

NormalDistributedVariation(xml_path::Vector{<:AbstractString}, mu::T, sigma::T; lb::Real=-Inf, ub::Real=Inf) where {T<:Real}

Create a (possibly truncated) distributed variation with a normal distribution.

UniformDistributedVariation(xml_path::Vector{<:AbstractString}, lb::T, ub::T) where {T<:Real}

Create a distributed variation with a uniform distribution.

addAttackRateVariationDimension!(evs::Vector{<:ElementaryVariation}, cell_definition::String, target_name::String, values::Vector{T} where T)

Pushes a variation onto evs for the attack rate of a cell type against a target cell type.

Examples:

addAttackRateVariationDimension!(evs, "immune", "cancer", [0.1, 0.2, 0.3])

addCustomDataVariationDimension!(evs::Vector{<:ElementaryVariation}, cell_definition::String, field_name::String, values::Vector{T} where T)

Pushes a variation onto evs for a custom data field of a cell type.

Examples:

addCustomDataVariationDimension!(evs, "immune", "perforin", [0.1, 0.2, 0.3])

addDomainVariationDimension!(evs::Vector{<:ElementaryVariation}, domain::NamedTuple)

Pushes variations onto evs for each domain boundary named in domain.

The names in domain can be flexibly named as long as they contain either min or max and one of x, y, or z (other than the the x in max). It is not required to include all three dimensions and their boundaries. The values for each boundary can be a single value or a vector of values.

Examples:

``` evs = ElementaryVariation[] addDomainVariationDimension!(evs, (xmin=-78, xmax=78, miny=-30, maxy=[30, 60], z_max=10))

AbstractVariation

Abstract type for variations.

Subtypes

ElementaryVariation, DiscreteVariation, DistributedVariation, CoVariation

Methods

addVariations, createTrial, run, _createTrial

AddGridVariationsResult <: AddVariationsResult

A struct that holds the result of adding grid variations to a set of inputs.

Fields

• all_variation_ids::AbstractArray{VariationID}: The variation IDs for all the variations added.

AddLHSVariationsResult <: AddVariationsResult

A struct that holds the result of adding LHS variations to a set of inputs.

Fields

• all_variation_ids::AbstractArray{VariationID}: The variation IDs for all the variations added.

AddRBDVariationsResult <: AddVariationsResult

A struct that holds the result of adding Sobol variations to a set of inputs.

Fields

• all_variation_ids::AbstractArray{VariationID}: The variation IDs for all the variations added.
• location_variation_ids_dict::Dict{Symbol, Matrix{Int}}: A dictionary of the variation IDs for each location. The keys are the locations and the values are the variation IDs for that location.

AddSobolVariationsResult <: AddVariationsResult

A struct that holds the result of adding Sobol variations to a set of inputs.

Fields

• all_variation_ids::AbstractArray{VariationID}: The variation IDs for all the variations added.
• cdfs::Array{Float64, 3}: The CDFs for the samples. The first dimension is the varied parameters, the second dimension is the design matrices, and the third dimension is the samples.

AddVariationMethod

Abstract type for variation methods.

Subtypes

GridVariation, LHSVariation, SobolVariation, RBDVariation

Methods

addVariations, createTrial, run, _createTrial

AddVariationsResult

Abstract type for the result of adding variations to a set of inputs.

Subtypes

AddGridVariationsResult, AddLHSVariationsResult, AddSobolVariationsResult, AddRBDVariationsResult

LocationParsedVariations

A struct that holds the variations and their indices into a vector of AbstractVariations for a specific location.

Fields

• variations::Vector{<:ElementaryVariation}: The variations for the location.
• indices::Vector{Int}: The indices of the variations in the vector of AbstractVariations.

ParsedVariations

A struct that holds the parsed variations and their sizes for all locations.

Fields

• sz::Vector{Int}: The sizes of the variations for each location.
• variations::Vector{<:AbstractVariation}: The variations used to create the parsed variations.
• location_parsed_variations::NamedTuple: A named tuple of LocationParsedVariationss for each location.

XMLPath

Hold the XML path as a vector of strings.

PhysiCell uses a : in names for signals/behaviors from cell custom data. For example, custom:sample is the default way to represent the sample custom data in a PhysiCell rule. pcvct uses : to indicate an attribute in an XML path and thus splits on : when looking for attribute values. To avoid this conflict, pcvct will internally replace custom:<name> and custom: <name> with custom <name>. Users should never have to think about this. Any pcvct function that uses XML paths will automatically handle this replacement.

cdf(ev::ElementaryVariation, x::Real)

Get the cumulative distribution function (CDF) of the variation at x.

If ev is a DiscreteVariation, x must be in the values of the variation. The value returned is from 0:Δ:1 where Δ=1/(n-1) and n is the number of values in the variation.

If ev is a DistributedVariation, the CDF is computed from the distribution of the variation.

addColumns(location::Symbol, folder_id::Int, evs::Vector{<:ElementaryVariation})

Add columns to the variations database for the given location and folder_id.

addLocationCDFVariations(location::Symbol, inputs::InputFolders, pv::ParsedVariations, reference_variation_id::VariationID, cdfs::AbstractMatrix{Float64})

Add variations for a specific location to the inputs. Used in addVariations with the LHSVariation, SobolVariation, and RBDVariation methods.

addLocationGridVariations(location::Symbol, inputs::InputFolders, pv::ParsedVariations, reference_variation_id::VariationID)

Add grid variations for a specific location to the inputs. Used in addVariations with a GridVariation method.

addVariationRow(location::Symbol, folder_id::Int, table_features::String, static_values::String, varied_values::String)

Add a new row to the variations database for the given location and folder_id if it doesn't already exist.

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

Add variations to the inputs using the specified AddVariationMethod and the variations in avs.

cdfsToVariations(location::Symbol, pv::ParsedVariations, folder_id::Int, reference_variation_id::Int, cdfs::AbstractMatrix{Float64})

Convert the CDFs to variation IDs in the database.

createSortedRBDMatrix(variation_ids::Vector{Int}, rbd_sorting_inds::AbstractMatrix{Int})

Create a sorted matrix of variation IDs based on the RBD sorting indices. This ensures that the orderings for each parameter stored for the RBD calculations.

generateLHSCDFs(n::Int, d::Int[; add_noise::Bool=false, rng::AbstractRNG=Random.GLOBAL_RNG, orthogonalize::Bool=true])

Generate a Latin Hypercube Sample of the Cumulative Distribution Functions (CDFs) for n samples in d dimensions.

Arguments

• n::Int: The number of samples to take.
• d::Int: The number of dimensions to sample.
• add_noise::Bool=false: Whether to add noise to the samples or have them be in the center of the bins.
• rng::AbstractRNG=Random.GLOBAL_RNG: The random number generator to use.
• orthogonalize::Bool=true: Whether to orthogonalize the samples, if possible. See https://en.wikipedia.org/wiki/Latinhypercubesampling#:~:text=In%20orthogonal%20sampling

Returns

• cdfs::Matrix{Float64}: The CDFs for the samples. Each row is a sample and each column is a dimension (corresponding to a feature).

Examples

cdfs = pcvct.generateLHSCDFs(4, 2)
size(cdfs)
# output
(4, 2)

generateRBDCDFs(rbd_variation::RBDVariation, d::Int)

Generate CDFs for a Random Balance Design (RBD) in d dimensions.

Arguments

• rbd_variation::RBDVariation: The RBD variation method to use.
• d::Int: The number of dimensions to sample.

Returns

• cdfs::Matrix{Float64}: The CDFs for the samples. Each row is a sample and each column is a dimension (corresponding to a parameter / parameter group from a CoVariation).
• rbd_sorting_inds::Matrix{Int}: A n_samples x d matrix that gives the ordering of the dimensions to use for the RBD. The order along each column is necessary for computing the RBD, sorting the simulations along the periodic curve.

generateSobolCDFs(n::Int, d::Int[; n_matrices::Int=1, randomization::RandomizationMethod=NoRand(), skip_start::Union{Missing, Bool, Int}=missing, include_one::Union{Missing, Bool}=missing)

Generate n_matrices Sobol sequences of the Cumulative Distribution Functions (CDFs) for n samples in d dimensions.

The subsequence of the Sobol sequence is chosen based on the value of n and the value of include_one. If it is one less than a power of 2, e.g. n=7, skip 0 and start from 0.5. Otherwise, it will always start from 0. If it is one more than a power of 2, e.g. n=9, include 1 (unless include_one is false).

The skip_start field can be used to control this by skipping the start of the sequence. If skip_start is true, skip to the smallest consecutive subsequence with the same denominator that has at least n elements. If skip_start is false, start from 0. If skip_start is an integer, skip that many elements in the sequence, .e.g., skip_start=1 skips 0 and starts at 0.5.

If you want to include 1 in the sequence, set include_one to true. If you want to exlude 1 (in the case of n=9, e.g.), set include_one to false.

Arguments

• n::Int: The number of samples to take.
• d::Int: The number of dimensions to sample.
• n_matrices::Int=1: The number of matrices to use in the Sobol sequence (effectively, the dimension of the sample is d x n_matrices).
• randomization::RandomizationMethod=NoRand(): The randomization method to use on the deterministic Sobol sequence. See GlobalSensitivity.jl.
• skip_start::Union{Missing, Bool, Int}=missing: Whether to skip the start of the sequence. Missing means pcvct will choose the best option.
• include_one::Union{Missing, Bool}=missing: Whether to include 1 in the sequence. Missing means pcvct will choose the best option.

Returns

• cdfs::Array{Float64, 3}: The CDFs for the samples. The first dimension is the features, the second dimension is the matrix, and the third dimension is the sample points.

Examples

cdfs = pcvct.generateSobolCDFs(11, 3)
size(cdfs)
# output
(3, 1, 11)

cdfs = pcvct.generateSobolCDFs(7, 5; n_matrices=2)
size(cdfs)
# output
(5, 2, 7)

gridToDB(evs::Vector{<:DiscreteVariation}, folder_id::Int, reference_variation_id::Int)

Adds a grid of variations to the database from the vector of DiscreteVariations.

orthogonalLHS(k::Int, d::Int)

Generate an orthogonal Latin Hypercube Sample in d dimensions with k subdivisions in each dimension, requiring n=k^d samples.

setUpColumns(location::Symbol, evs::Vector{<:ElementaryVariation}, folder_id::Int, reference_variation_id::Int)

Set up the columns for the variations database for the given location and folder_id.

sqliteDataType(ev::ElementaryVariation)

Get the SQLite data type to hold the data in the variation.

variationDataType(ev::ElementaryVariation)

Get the data type of the variation.

variationLocation(av::AbstractVariation)

Get the location of a variation as a Symbol, e.g., :config, :rulesets_collection, etc. Can also pass in an XMLPath object.

variationTarget(av::AbstractVariation)

Get the type XMLPath target(s) of a variation

variationValues(ev::ElementaryVariation[, cdf])

Get the values of an ElementaryVariation.

If ev is a DiscreteVariation, all values are returned unless cdf is provided. In that case, the CDF(s) is linearly converted into an index into the values vector and the corresponding value is returned.

If ev is a DistributedVariation, the cdf is required and the iCDF is returned. The cdf can be a single value or a vector of values.

Arguments

• ev::ElementaryVariation: The variation to get the values of.
• cdf: The cumulative distribution function (CDF) values to use for the variation.