create_metabolism(; n_resources::Int64=10, n_levels::Int64=5, energy_yields::String="Uniform_1", seed::Int64=1234)

Generates a universal metabolism

Optional arguments

• n_resources::Int64: Number of possible resources in the system. Default is 10.
• n_levels::Int64: Number of levels of decomposition in the system. Default is 5.
• energy_yields::String: The energy difference between two consecutive levels of decomposition. Default is 1 between all levels. Use "Random" to sample from a uniform distribution between 0 and 2 instead.
• rng::Int64: Random number generator seed. Default is 1234.

Output

Stoichiometric matrix, Energy yield matrix

create_species_pool(D::Matrix; n_families::Int64=5, family_size::Int64=100, dirichlet_hyper::Real=100, between_family_var::Real=0.1, inside_family_var::Real=0.05, h::Real=1, maintenance::Real=0.1, specialist::Real=1, generalist::Real=1, a_dist::Union{Distributions.Sampleable, Nothing}=nothing, k_dist::Union{Distributions.Sampleable, Nothing}=nothing, seed::Int64=1234)

Create a pool of species by sampling reactions from a matrix denoting all possible reactions.

Mandatory arguments

• D::Matrix: Matrix denoting all possible reactions. A square matrix whose size should be equal to the number of possible resources in the system. All reactions will be deemed possible whose values are non-zero.

Optional arguments

• n_families::Int64: Number of families (groups of functionally similar species) in the species pool. Default is 5.
• family_size::Int64: Number of species in each family. Default is 100.
• dirichlet_hyper::Real: Hyperparameter for the Dirichlet distribution that is used for creating the species inside the same family. The higher its value, the more similar they will be. Default is 100.
• maintenance::Real: The expected cost of maintenance accross all species. Default is 0.1.
• between_family_var::Real: Variance of the normal distribution used to sample the maintenance values between families. Default is 0.1.
• inside_family_var::Real: Variance of the normal distribution used to sample the maintenance values inside families. Default is 0.05.
• h::Real: Controls the allocation of reaction rates inside species. Default is 1.
• specialist::Real: The specialist part of the odds ratio specialists:generalists in the pool. Default is 1.
• generalist::Real: The generalist part of the odds ratio specialists:generalists in the pool. Default is 1.
• a_dist::Union{Distributions.Sampleable, Nothing}: Distribution to sample the strength of host control. Default is Uniform(0.5, 1.5).
• k_dist::Union{Distributions.Sampleable, Nothing}: Distribution to sample the critical abundance that triggers host control. Default is Uniform(99.999, 100.001).
• spec_constraint::Union{Array{Bool}, Nothing}: Boolean array of resources that specialists can consume. If nothing, first element is false, rest is true. Default is nothing.
• rng::Int64: Random number generator seed. Default is 1234.

Output

PoolStruct with the following fields:

• pool::Array{Float64, 3}: The matrices describing the metabolisms of the species inside the species pool.
• family_ids::Array{Int64}: The family IDs of species
• m::Array{Float64}: The maintenance costs of the species
• n_reactions::Array{Int64}: The number of reactions of the species
• n_splits::Array{Float64}: Reaction repertoire complexity metric of the species
• a::Array{Float64}: The strength of host control on the species
• k::Array{Float64}: The critical abundance that triggers host control on the species

sample_pool(p::PoolStruct, n_species::Int64, n_invaders::Int64; seed::Int64=1234)

Samples species from a species pool

Mandatory arguments

• p::PoolStruct: A pool struct containing the pool of species.
• n_species::Int64: Number of species initially present in the habitat.
• n_invaders::Int64: Number of invading species.

Optional arguments

• seed::Int64: Random number generator seed. Default is 1234.
• n_comms::Int64: Number of communities. Default is 1.
• ph::Bool: Whether to sample pH values. If true, optimal pH value is sampled from the (0, 14) range for each species.

Default is false, where optimal pH is set to 7.0 for all species.

Output

SampleStruct with the following fields:

• n_species::Int64: Number of species initially present in the habitat.
• n_invaders::Int64: Number of invading species.
• C::Array{Float64, 3}: The matrices describing the metabolism of the sampled species.
• family_ids::Array{Int64}: The family IDs of the sampled species.
• m::Array{Float64}: The maintenance costs of the sampled species.
• n_reactions::Array{Int64}: The number of reactions of the sampled species.
• n_splits::Array{Float64}: Reaction repertoire complexity metric of the sampled species.
• species_abundance::Array{Float64}: The initial abundances of the sampled species.
• resource_abundance::Array{Float64}: The initial abundances of resources.
• a::Array{Float64}: The strength of host control on the sampled species.
• k::Array{Float64}: The critical abundance that triggers host control on the sampled species.

generic_run(sample::SampleStruct;
   D=nothing,
   W_ba=nothing,
   path=homedir(),
   t_span=(0, 1000),
   t_inv=25.0,
   t_inv_0=100.0,
   cutoff=0.0001,
   phi=0.1,
   eta=0.1,
   tau=nothing,
   alpha=nothing,
   plot=true,
   host_regulation=true)

Run the model with the given parameters and sample by solving a set of ODEs using the KenCarp4 solver.

Mandatory arguments

• sample::SampleStruct: A sample struct containing the initial conditions and parameters for the model.

Recommended but optional arguments

• D::Union{Nothing, Matrix{Int64}}: The stoichiometric matrix for the model. If not supplied, a default matrix will be created.
• W_ba::Union{Nothing, Matrix{Float64}}: The energy yield matrix for the model. If not supplied, a default matrix will be created.
• path::String: The path to save the output plots. Default is homedir().
• t_span::Tuple{Int64, Int64}: The time span for the simulation. Default is (0, 1000).

Optional arguments

• t_inv::Float64: The time between the introduction of two subsequent invading species. Default is 25.0.
• t_inv_0::Float64: The time at which the first invading species is introduced. Default is 100.0.
• cutoff::Float64: The abundance threshold under which a species is considered extinct and its abundance is set to 0. Default is 0.0001.
• phi::Float64: The strength of the additional maintenance costs based on the complexity of a the reaction repertoires of species. Default is 0.1.
• eta::Float64: The strength of the additional maintenance costs based on the number of reactions of species. Default is 0.1.
• tau::Union{Vector{Float64}, Nothing}: Controls the replenisment/depletion rates of resources from/into the outter environment. Default is 1.0 for all reasources.
• alpha::Union{Vector{Float64}, Nothing}: The availability of resources in the outer environment. Default is 100.0 for the first resource and 0.0 for the rest.
• plot::Bool: Whether to generate plots of the simulation. Default is true.
• host_regulation::Bool: Whether to include host regulation in the model. Default is true.

Output

Returns time series data in a SummarizedExperiment (SE) data container, which can be used for a variety of analyses. For details, see MicrobiomeAnalysis.jl

spatial_run(n_comms::Int64, sample::SampleStruct;
    ph_list::Union{Nothing, Vector{Float64}}=nothing,
    ph_strength=1.0,
    D_species=0.1,
    D_resources=0.1,
    A_species=0.1,
    A_resources=0.1,
    D=nothing,
    W_ba=nothing,
    path=homedir(),
    t_span=(0, 1000),
    t_inv=25.0,
    t_inv_0=100.0,
    cutoff=0.0001,
    phi=0.1,
    eta=0.1,
    tau=nothing,
    alpha=nothing,
    plot=true,
    host_regulation=true)

Run the spatially extended version of the model, where a set of communities are simulated. The communities resemble different sections of the gut, where resources and invaders appear in the first community and can spread to the other communities through diffusion and advection.

Mandatory arguments

• n_comms::Int64: The number of communities to simulate.
• sample::SampleStruct: A sample struct containing the initial conditions and parameters for the model.

Additional arguments

• D_species::Float64: The diffusion coefficient for species. Default is 0.1.
• D_resources::Float64: The diffusion coefficient for resources. Default is 0.1.
• A_species::Float64: The advection coefficient for species. Default is 0.1.
• A_resources::Float64: The advection coefficient for resources. Default is 0.1.
• ph_strength::Float64: The strength of the pH effect on growth. Default is 1.0.
• ph_list::Union{Nothing, Vector{Float64}}: A list of pH values for each community. If not supplied, the default pH value is 7.0.

Output

Returns a dictionary of SummarizedExperiment (SE) data containers