GitHub

Sensitivity

Run sensitivity analyses on a model.

Public API

PhysiCellModelManager.MOAT — Type
MOAT

Store the information necessary to run a Morris One-At-A-Time (MOAT) global sensitivity analysis.

Fields

  • lhs_variation::LHSVariation: the Latin Hypercube Sampling (LHS) variation to use for the MOAT. See LHSVariation.

Examples

Note: any keyword arguments in the MOAT constructor are passed to LHSVariation.

MOAT() # default to 15 base points
MOAT(10) # 10 base points
MOAT(10; add_noise=true) # do not restrict the base points to the center of their cells
source
PhysiCellModelManager.RBD — Type
RBD

Store the information necessary to run a Random Balance Design (RBD) global sensitivity analysis.

By default, RBD will use the Sobol' sequence to sample the parameter space. See below for how to turn this off. Currently, users cannot control the Sobolʼ sequence used in RBD to the same degree it can be controlled in Sobolʼ. Open an Issue if you would like this feature.

Fields

  • rbd_variation::RBDVariation: the RBD variation to use for the RBD analysis. See RBDVariation.
  • num_harmonics::Int: the number of harmonics to use from the Fourier transform for the RBD analysis.

Examples

Note: any keyword arguments in the RBD constructor are passed to RBDVariation, except for the num_harmonics keyword argument. If num_harmonics is not specified, it defaults to 6.

RBD(15) # 15 points from the Sobol' sequence
RBD(15; num_harmonics=10) # use 10 harmonics
RBD(15; use_sobol=false) # opt out of using the Sobol' sequence, instead using a random sequence in each dimension
source
PhysiCellModelManager.Sobolʼ — Type
Sobolʼ

Store the information necessary to run a Sobol' global sensitivity analysis as well as how to extract the first and total order indices.

The rasp symbol is used to avoid conflict with the Sobol module. To type it in VS Code, use \rasp and then press tab. Alternatively, the constructor SobolPCMM is provided as an alias for convenience.

The methods available for the first order indices are :Sobol1993, :Jansen1999, and :Saltelli2010. Default is :Jansen1999. The methods available for the total order indices are :Homma1996, :Jansen1999, and :Sobol2007. Default is :Jansen1999.

Fields

  • sobol_variation::SobolVariation: the Sobol' variation to use for the Sobol' analysis. See SobolVariation.
  • sobol_index_methods::NamedTuple{(:first_order, :total_order), Tuple{Symbol, Symbol}}: the methods to use for calculating the first and total order indices.

Examples

Note: any keyword arguments in the Sobolʼ constructor are passed to SobolVariation, except for the sobol_index_methods keyword argument. Do not use the n_matrices keyword argument in the SobolVariation constructor as it is set to 2 as required for Sobol' analysis.

Sobolʼ(15) # 15 points from the Sobol' sequence
Sobolʼ(15; sobol_index_methods=(first_order=:Jansen1999, total_order=:Jansen1999)) # use Jansen, 1999 for both first and total order indices
Sobolʼ(15; randomization=NoRand())` # use the default Sobol' sequence with no randomization. See GlobalSensitivity.jl for more options.
Sobolʼ(15; skip_start=true) # force the Sobol' sequence to skip to the lowest denominator in the sequence that can hold 15 points, i.e., choose from [1/32, 3/32, 5/32, ..., 31/32]
Sobolʼ(15; skip_start=false) # force the Sobol' sequence to start at the beginning, i.e. [0, 0.5, 0.25, 0.75, ...]
Sobolʼ(15; include_one=true) # force the Sobol' sequence to include 1 in the sequence
source
Base.run — Method
run(method::GSAMethod, args...; functions::AbstractVector{<:Function}=Function[], kwargs...)

Run a global sensitivity analysis method on the given arguments.

Arguments

  • method::GSAMethod: the method to run. Options are MOAT, Sobolʼ, and RBD.
  • inputs::InputFolders: the input folders shared across all simuations to run.
  • avs::AbstractVector{<:AbstractVariation}: the elementary variations to sample. These can be either DiscreteVariation's or DistributedVariation's.

Alternatively, the third argument, inputs, can be replaced with a reference::AbstractMonad, i.e., a simulation or monad to be the reference. This should be preferred to setting reference variation IDs manually, i.e., if not using the base files in the input folders.

Keyword Arguments

The reference_variation_id keyword argument is only compatible when the third argument is of type InputFolders. Otherwise, the reference simulation/monad will set the reference variation values.

  • reference_variation_id::VariationID: the reference variation IDs as a VariationID
  • ignore_indices::AbstractVector{<:Integer}=[]: indices into avs to ignore when perturbing the parameters. Only used for Sobolʼ. See Sobolʼ for a use case.
  • force_recompile::Bool=false: whether to force recompilation of the simulation code
  • prune_options::PruneOptions=PruneOptions(): the options for pruning the simulation results
  • n_replicates::Integer=1: the number of replicates to run for each monad, i.e., at each sampled parameter vector.
  • use_previous::Bool=true: whether to use previous simulation results if they exist
  • functions::AbstractVector{<:Function}=Function[]: the functions to calculate the sensitivity indices for. Each function must take a simulation ID as the singular input and return a real number.
source

Private API

PhysiCellModelManager.MOATSampling — Type
MOATSampling

Store the information that comes out of a Morris One-At-A-Time (MOAT) global sensitivity analysis.

Fields

  • sampling::Sampling: the sampling used in the sensitivity analysis.
  • monad_ids_df::DataFrame: the DataFrame of monad IDs that define the scheme of the sensitivity analysis.
  • results::Dict{Function, GlobalSensitivity.MorrisResult}: the results of the sensitivity analysis for each function.
source
PhysiCellModelManager.RBDSampling — Type
RBDSampling

Store the information that comes out of a Random Balance Design (RBD) global sensitivity analysis.

Fields

  • sampling::Sampling: the sampling used in the sensitivity analysis.
  • monad_ids_df::DataFrame: the DataFrame of monad IDs that define the scheme of the sensitivity analysis.
  • results::Dict{Function, GlobalSensitivity.SobolResult}: the results of the sensitivity analysis for each function.
  • num_harmonics::Int: the number of harmonics used in the Fourier transform.
  • num_cycles::Union{Int, Rational}: the number of cycles used for each parameter.
source
PhysiCellModelManager.SobolSampling — Type
SobolSampling

Store the information that comes out of a Sobol' global sensitivity analysis.

Fields

  • sampling::Sampling: the sampling used in the sensitivity analysis.
  • monad_ids_df::DataFrame: the DataFrame of monad IDs that define the scheme of the sensitivity analysis.
  • results::Dict{Function, GlobalSensitivity.SobolResult}: the results of the sensitivity analysis for each function.
  • sobol_index_methods::NamedTuple{(:first_order, :total_order), Tuple{Symbol, Symbol}}: the methods used for calculating the first and total order indices.
source
PhysiCellModelManager.calculateGSA! — Method
calculateGSA!(gsa_sampling::GSASampling, functions::AbstractVector{<:Function})

Calculate the sensitivity indices for the given functions.

This function is also used to compute the sensitivity indices for a single function:

calculateGSA!(gsa_sampling, f)

Arguments

  • gsa_sampling::GSASampling: the sensitivity analysis to calculate the indices for.
  • functions::AbstractVector{<:Function}: the functions to calculate the sensitivity indices for. Each function must take a simulation ID as the singular input and return a real number.
source
PhysiCellModelManager.perturbVariation — Method
perturbVariation(pv::ParsedVariations, inputs::InputFolders, reference_variation_id::VariationID, cdf_col::AbstractVector{<:Real})

Perturb the variation at the given location and dimension for MOAT global sensitivity analysis.

source
PhysiCellModelManager.runSensitivitySampling — Function
runSensitivitySampling(method::GSAMethod, args...; kwargs...)

Run a global sensitivity analysis method on the given arguments.

Arguments

  • method::GSAMethod: the method to run. Options are MOAT, Sobolʼ, and RBD.
  • inputs::InputFolders: the input folders shared across all simuations to run.
  • pv::ParsedVariations: the ParsedVariations object that contains the variations to sample.

Keyword Arguments

  • reference_variation_id::VariationID: the reference variation IDs as a VariationID
  • ignore_indices::AbstractVector{<:Integer}=[]: indices into dimensions of pv.latent_variations to ignore when perturbing the parameters. Only used for Sobolʼ. These count the latent parameters, i.e. possibly >1 per latent variation!
  • force_recompile::Bool=false: whether to force recompilation of the simulation code
  • prune_options::PruneOptions=PruneOptions(): the options for pruning the simulation results
  • n_replicates::Int=1: the number of replicates to run for each monad, i.e., at each sampled parameter vector.
  • use_previous::Bool=true: whether to use previous simulation results if they exist
source
PhysiCellModelManager.sensitivityResults! — Method
sensitivityResults!(gsa_sampling::GSASampling, functions::AbstractVector{<:Function})

Calculate the global sensitivity analysis for the given functions and record the sampling scheme.

source
PhysiCellModelManager.variationsToMonads — Method
variationsToMonads(inputs::InputFolders, variation_ids::AbstractArray{VariationID})

Return a matrix of Monads based on the given variation IDs.

For each varied location, a matrix of variation IDs is provided. This information, together with the inputs, identifies the monads to be used.

Returns

  • monad_ids::Array{Monad}: an array of the monads to be used. Matches the shape of the variations array.
source