ADRIA API

absolute_juveniles(X::AbstractArray{T}, coral_spec::DataFrame, area::AbstractVector{T})::AbstractArray{T} where {T<:Real}
absolute_juveniles(rs::ResultSet)::AbstractArray

Juvenile coral cover in m².

absolute_shelter_volume(X::NamedDimsArray, site_area::Vector{<:Real}, inputs::Union{DataFrame,DataFrameRow})
absolute_shelter_volume(rs::ResultSet)

Provide indication of shelter volume in volume of cubic meters.

The metric applies log-log linear models developed by Urbina-Barreto et al., [1] which uses colony diameter and planar area (2D metrics) to estimate shelter volume (a 3D metric).

Arguments

• X : raw results
• site_area : area in m^2 for each site
• max_cover : maximum possible coral cover for each site (in percentage of site_area)
• inputs : DataFrame of scenario inputs

References

1. Urbina-Barreto, I., Chiroleu, F., Pinel, R., Fréchon, L., Mahamadaly, V., Elise, S., Kulbicki, M., Quod, J.-P., Dutrieux, E., Garnier, R., Henrich Bruggemann, J., Penin, L., & Adjeroud, M. (2021). Quantifying the shelter capacity of coral reefs using photogrammetric 3D modeling: From colonies to reefscapes. Ecological Indicators, 121, 107151. https://doi.org/10.1016/j.ecolind.2020.107151

coral_evenness(r_taxa_cover::AbstractArray{T})::Array{T} where {T<:Real}
coral_evenness(rs::ResultSet)::AbstractArray{T} where {T}

Calculates evenness across functional coral groups in ADRIA as a diversity metric. Inverse Simpsons diversity indicator.

References

1. Hill, M. O. (1973). Diversity and Evenness: A Unifying Notation and Its Consequences. Ecology, 54(2), 427-432. https://doi.org/10.2307/1934352

juvenile_indicator(X::AbstractArray{T}, coral_params::DataFrame, area::Vector{Float64}, k_area::Vector{Float64}) where {T<:Real}
juvenile_indicator(rs::ResultSet)

Indicator for juvenile density (0 - 1), where 1 indicates the maximum theoretical density for juveniles have been achieved.

Notes

Maximum density is 51.8 juveniles / m², where juveniles are defined as < 5cm diameter. See email correspondence from: Dr. A Thompson; to: Dr. K. Anthony Subject: RE: Max density of juvenile corals on the GBR Sent: Friday, 14 October 2022 2:58 PM

reef_condition_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray)::AbstractArray
reef_condition_index(rs)

Estimates a Reef Condition Index (RCI) providing a single value that indicates the condition of a reef across four metrics:

• coral cover
• evenness (coral diversity)
• shelter volume, and
• abundance of juveniles

Notes

Juveniles are made relative to maximum observed juvenile density (51.8/m²) See notes for juvenile_indicator()

Arguments

• rc : Relative coral cover across all groups
• evenness : Evenness across all coral groups
• sv : Shelter volume based on coral sizes and abundances
• juves : Abundance of coral juveniles < 5 cm diameter

Returns

NamedArray[timesteps ⋅ locations ⋅ scenarios]

reef_fish_index(rc::AbstractArray)
reef_fish_index(rs::ResultSet)

The Reef Fish Index (RFI) estimates fish biomass from relative coral cover.

A linear regression (developed by Dr. R. Heneghan, Queensland University of Technology) is used to indicate the relationship between coral cover and fish biomass. The regression was developed with digitized data from Figures 4a and 6b in Graham & Nash (2013; see [1]).

Values are provided ∈ [0, 1], where 1 indicates maximum fish biomass.

Note: Coral cover here is relative to coral habitable area ($k$ area).

Arguments

• rc : Relative cover

Returns

NamedArray[timesteps ⋅ locations ⋅ scenarios], values in kg/km²

References

1. Graham, N.A.J., Nash, K.L., 2013.

The importance of structural complexity in coral reef ecosystems. Coral Reefs 32, 315–326. https://doi.org/10.1007/s00338-012-0984-y

reef_tourism_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray)::AbstractArray
reef_tourism_index(rs::ResultSet)::AbstractArray

Estimate tourism index.

Note: This metric assumes all inputs (relative cover, evenness, shelter volume, coral juveniles) are scaled between 0 and 1. For evenness, shelter volume and coral juveniles, a value of 1 may represent a theoretical maximum.

Arguments

• rc : Relative coral cover across all groups
• evenness : Evenness across all coral groups
• sv : Shelter volume based on coral sizes and abundances
• juves : Abundance of coral juveniles < 5 cm diameter

relative_cover(X::AbstractArray{<:Real})::AbstractArray{<:Real}
relative_cover(rs::ResultSet)::AbstractArray{<:Real}

Indicate coral cover relative to available hard substrate ($k$ area).

Arguments

• X : Matrix of raw model results

Returns

Coral cover [0 - 1], relative to available $k$ area for a given location.

relative_juveniles(X::AbstractArray{T})::AbstractArray{T} where {T}
relative_juveniles(rs::ResultSet)::AbstractArray

Juvenile coral cover relative to total site area.

_relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}
_relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}
_relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::NamedDimsArray)::NamedDimsArray where {T<:Real}
_relative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrame)::NamedDimsArray where {T<:Real}
_relative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrameRow)::NamedDimsArray where {T<:Real}
_relative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::NamedDimsArray)::NamedDimsArray where {T<:Real}
relative_shelter_volume(rs::ResultSet)

Provide indication of shelter volume relative to theoretical maximum volume for the area covered by coral.

The metric applies log-log linear models developed by Urbina-Barreto et al., [1] which uses colony diameter and planar area (2D metrics) to estimate shelter volume (a 3D metric).

\[RSV = \begin{cases} TASV / MSV & TASV > 0, \\ 0 & \text{otherwise} \end{cases}\]

where $TASV$ represents Total Absolute Shelter Volume and $MSV$ represents the maximum shelter volume possible.

Arguments

• X : raw results
• k_area : area in m^2 for each site
• inputs : DataFrame of scenario inputs

Returns

Shelter volume relative to a theoretical maximum volume for the available $k$ area.

References

1. Urbina-Barreto, I., Chiroleu, F., Pinel, R., Fréchon, L., Mahamadaly, V., Elise, S., Kulbicki, M., Quod, J.-P., Dutrieux, E., Garnier, R., Henrich Bruggemann, J., Penin, L., & Adjeroud, M. (2021). Quantifying the shelter capacity of coral reefs using photogrammetric 3D modeling: From colonies to reefscapes. Ecological Indicators, 121, 107151. https://doi.org/10.1016/j.ecolind.2020.107151

relative_taxa_cover(X::AbstractArray{T}, k_area::Vector{T}) where {T<:Real}
relative_taxa_cover(rs::ResultSet)

Results grouped by taxa/species.

TODO: Number of size classes is hard coded.

Arguments

• X : Raw model results for a single scenario
• k_area : the coral habitable area
• area : total location area

Returns

Coral cover, grouped by taxa for the given scenario, relative to location k area.

scenario_absolute_juveniles(data::NamedDimsArray, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}
scenario_absolute_juveniles(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Calculate the mean absolute juvenile population for each scenario for the entire domain.

scenario_asv(sv::NamedDimsArray; kwargs...)::AbstractArray{<:Real}
scenario_asv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Calculate the mean absolute shelter volumes for each scenario for the entire domain.

scenario_evenness(ev::NamedDimsArray; kwargs...)::AbstractArray{<:Real}
scenario_evenness(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Calculate the mean coral evenness for each scenario for the entire domain.

scenario_juvenile_indicator(data::NamedDimsArray, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}
scenario_juvenile_indicator(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Determine juvenile indicator ∈ [0, 1], where 1 indicates maximum mean juvenile density (51.8) has been achieved.

scenario_rci(rci::NamedDimsArray, tac::NamedDimsArray; kwargs...)
scenario_rci(rs::ResultSet; kwargs...)

Extract the total populated area of locations with Reef Condition Index of "Good" or higher for each scenario for the entire domain.

scenario_relative_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Calculate the mean relative coral cover for each scenario for the entire domain.

scenario_relative_juveniles(data::NamedDimsArray, coral_spec::DataFrame, area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}

Calculate the mean relative juvenile population for each scenario for the entire domain.

scenario_rfi(rfi::NamedDimsArray; kwargs...)
scenario_rfi(rs::ResultSet; kwargs...)

Calculate the mean Reef Fish Index (RFI) for each scenario for the entire domain.

scenario_rsv(sv::NamedDimsArray; kwargs...)::AbstractArray{<:Real}
scenario_rsv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Calculate the mean relative shelter volumes for each scenario for the entire domain.

scenario_rti(rti::NamedDimsArray; kwargs...)
scenario_rti(rs::ResultSet; kwargs...)

Calculate the mean Reef Tourism Index (RTI) for each scenario for the entire domain.

scenario_total_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

Calculate the mean absolute coral for each scenario for the entire domain.

total_absolute_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real})::AbstractArray{<:Real}
total_absolute_cover(rs::ResultSet)::AbstractArray{<:Real}

The Total Absolute Coral Cover. Sum of proportional area taken up by all corals, multiplied by total site area.

Arguments

• X : Matrix of raw model results
• k_area : Site areas, with sites following the same order as given indicated in X.

Returns

Absolute coral cover for a given location in m².

_collate_ranks(rs, selected)

Collates ranks into seed/shade ranking results into a common structure.

_colony_Lcm2_to_m3_m2(inputs::DataFrame)::Tuple

Helper function to convert coral colony values from Litres/cm² to m³/m²

Arguments

• inputs : Scenario values for the simulation

Returns

Tuple : Assumed colony volume (m³/m²) for each species/size class, theoretical maximum for each species/size class

References

1. Aston Eoghan A., Duce Stephanie, Hoey Andrew S., Ferrari Renata (2022). A Protocol for Extracting Structural Metrics From 3D Reconstructions of Corals. Frontiers in Marine Science, 9. https://doi.org/10.3389/fmars.2022.854395

_get_ranks(rs::ResultSet, intervention::Int64; kwargs...)

Extracts results for a specific intervention (seeding [1] or shading [2])

_max_juvenile_area(coral_params::DataFrame, max_juv_density::Float64=51.8)

Calculate the maximum possible area that can be covered by juveniles for a given m².

_shelter_species_loop!(X::T1, ASV::T1, nspecies::Int64, colony_vol_m3_per_m2::V, k_area::V) where {T1<:NamedDims.NamedDimsArray{(:timesteps, :species, :sites),Float64,3,Array{Float64,3}},V<:AbstractVector{<:Float64}}

Helper method to calculate absolute shelter volume metric across each species/size class for a given scenario.

Arguments

• X : raw results (proportional coral cover relative to full site area)
• ASV : matrix to hold shelter volume results
• nspecies : number of species (taxa and size classes) considered
• scen : scenario number to calculate metric for
• colony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class (36)
• k_area : habitable area of site in m²

_shelter_species_loop(X, nspecies::Int64, scen::Int64, colony_vol_m3_per_m2, max_colony_vol_m3_per_m2, site_area)

Helper method to calculate relative shelter volume metric across each species/size class for a given scenario.

Note: Species dimension is an amalgamation of taxa and size class. e.g., X[species=1:6] is Taxa 1, size classes 1-6; X[species=7:12] is Taxa 2, size class 1-6, etc.

Arguments

• X : raw results (proportional coral cover relative to full site area)
• n_species : number of species (taxa and size classes) considered
• scen : scenario number to calculate metric for
• colony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class (36)
• max_colony_vol_m3_per_m2 : theoretical maximum volume per m² of coverage for each taxa (6)
• site_area : total area of site in m²
• k_area : habitable area of site in m² (i.e., k area)

call_metric(metric, data, args...; timesteps=(:), species=(:), sites=(:), scens=(:))

Convenience method that slices the data in the specified manner.

Arguments

• metric : Function, the metric function to apply to "raw" data.
• data : NamedDimsArray, data to pass into metric
• args : Additional positional arguments to pass into metric
• dims : dummy keyword argument, not used but defined to allow use with other methods

dims(m::Metric)::Tuple

Get dimension names for a given outcome/metric.

dominates(x::Vector{<:Real}, y::Vector{<:Real})::Vector

Adapted from: https://discourse.julialang.org/t/fast-optimized-non-dominated-sorting-algorithms/86793/7

Original function name is dominates2()

loc_trajectory(metric, data::NamedDimsArray{D,T,N,A})::NamedDimsArray where {D,T,N,A}

Alias for summarize(data, [:scenarios], metric). Collate trajectory for each location.

Examples

using Statistics

rs = ADRIA.load_results("some results")
tac = ADRIA.metrics.total_absolute_cover(rs)

# Get median trajectory for each site
ADRIA.metrics.loc_trajectory(median, tac)
# 2-dimensional NamedDimsArray(KeyedArray(...)) with keys:
# ↓   timesteps ∈ 75-element Vector{Any}
# →   sites ∈ 216-element Vector{Any}
# And data, 75×216 Matrix{Float32}:

# Get upper 95% CI for each site
ADRIA.metrics.loc_trajectory(x -> quantile(x, 0.975), tac)
# 2-dimensional NamedDimsArray(KeyedArray(...)) with keys:
# ↓   timesteps ∈ 75-element Vector{Any}
# →   sites ∈ 216-element Vector{Any}
# And data, 75×216 Matrix{Float32}:

Arguments

• metric : Any function (nominally from the Statistics package) to be applied to data
• data : Data set to apply metric to

Returns

2D array of $T ⋅ S$, where $T$ is total number of time steps and $S$ is number of sites

metric_label(m::Metric)::String
metric_label(f::Function, unit::String)

Return name of metric in the format: "Title Case [Unit]", suitable for use as a label.

Example

m_label = metric_label(scenario_total_cover)
# "Scenario Total Cover [m²]"

nds(X::AbstractArray{<:Real}, dist::Int64=0)::Vector{Vector{<:Int}}

Naive n-dimensional non-dominated sorting.

Adapted from: https://discourse.julialang.org/t/fast-optimized-non-dominated-sorting-algorithms/86793/7

Original function name is nds4()

Arguments

X : outcomes, where rows are scenarios and columns are metric results. dist : distance from front, where 0 is on the frontier.

Returns

Vector of Vectors with row indices for each dist from frontier, where 0 is on the frontier.

per_loc(metric, data::NamedDimsArray{D,T,N,A})::NamedDimsArray where {D,T,N,A}

Alias for summarize(data, [:scenarios, :timesteps], metric). Get metric results applied to the location-level at indicated time (or across timesteps).

Arguments

• metric : Any function (nominally from the Statistics package) to be applied to data
• data : Data set to apply metric to
• timesteps : timesteps to apply metric across

Returns

Named Vector of $N$ elements, where $N$ is the number of sites.

scenario_outcomes(rs::ResultSet, metrics::Vector{Metric})::NamedDimsArray

Get outcomes for a given list of metrics and a result set.

Arguments

• rs : ResultSet
• metrics : Vector of scenario Metrics (the ones that start with scenario_)

Returns

NamedDimsArray with (:timesteps, :scenarios, :outcomes)

Examples

metrics::Vector{ADRIA.metrics.Metric} = [
    ADRIA.metrics.scenario_total_cover,
    ADRIA.metrics.scenario_asv,
    ADRIA.metrics.scenario_absolute_juveniles,
]

# 3-dimensional Array of outcomes
outcomes = ADRIA.metrics.scenario_outcomes(rs, metrics)

scenario_trajectory(data::AbstractArray; metric=mean)

Produce scenario trajectories using the provided metric/aggregation function.

Arguments

• data : Results to aggregate
• metric : Function or Callable used to summarize data

Returns

Matrix[timesteps ⋅ scenarios]

seed_ranks(rs::ResultSet; kwargs...)

Arguments

• rs : ResultSet
• kwargs : named dimensions to slice across

Returns

NamedDimsArray[timesteps, sites, scenarios]

Example

ADRIA.metrics.seed_ranks(rs; timesteps=1:10, scenarios=3:5)

shade_ranks(rs::ResultSet; kwargs...)

Arguments

• rs : ResultSet
• kwargs : named dimensions to slice across

Returns

NamedDimsArray[timesteps, sites, scenarios]

Example

ADRIA.metrics.shade_ranks(rs; timesteps=1:10, scenarios=3:5)

slice_results(data::NamedDimsArray; timesteps=(:), species=(:), sites=(:), scenarios=(:))

Slice data as indicated. Dimensions not found in target data are ignored.

summarize(data::NamedDimsArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function)::NamedDimsArray{<:Real}
summarize(data::NamedDimsArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function, timesteps::Union{UnitRange,Vector{Int64},BitVector})::NamedDimsArray{<:Real}

Apply summary metric along some axis of a data set across some or all timesteps.

Arguments

• data : Data set to apply metric to.
• alongs_axis : which axis will be replaced with (:) when slicing.
• metric : Any function (nominally from the Statistics package) to be applied to data.
• timesteps : timesteps to apply metric across.

Returns

NamedDimsArray with summary metric for the remaining axis.

summarize_absolute_shelter_volume(sv::AbstractArray{<:Real}, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
summarize_absolute_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

summarize_coral_evenness(raw::AbstractArray{<:Real}, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
summarize_coral_evenness(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

summarize_raw(data::NamedDimsArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Summarize raw data, aggregating the specified dimensions (e.g., timesteps, scenarios, etc.) and collapsing given dims.

summarize_relative_cover(rc::AbstractArray{<:Real}, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
summarize_relative_cover(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized relative cover.

summarize_relative_shelter_volume(sv::AbstractArray{<:Real}, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
summarize_relative_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

summarize_total_cover(raw::AbstractArray{<:Real}, areas::AbstractArray{<:Real}; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
summarize_total_cover(rs::ResultSet; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized total absolute cover.

to_string(m::Metric)::String

Get name of metric as a string.

to_symbol(m::Metric)::String

Get name of metric as a symbol.

top_N_sites(rs::ResultSet; N::Int64; metric::relative_cover)
top_N_sites(data::AbstractArray{Real}, N::Int64; stat=mean)

Return the top N sites according to the provided metric (defaulting to mean of relative_cover).

Arguments

• rs : ResultSet
• N : No. of best performing sites to be selected
• metric : metric to use to order sites from best to worst, must take ResultSet as input
• stat : summary statistic to use for comparison (default: mean)

Returns

NamedDimsArray[:scenarios,:siteids], where `siteids` indicates order of site ranking as well.

Example

ADRIA.metrics.top_N_sites(rs, 5)
ADRIA.metrics.top_N_sites(rs, 5; metric=ADRIA.metric.relative_cover)
ADRIA.metrics.top_N_sites(rs, 5; metric=ADRIA.metric.relative_cover, stat=median)

top_n_seeded_sites(rs::ResultSet, n::Int64; kwargs...)

Get the top n seeded sites over time by their unique site id. Lower rank values are better (e.g., 1 = first choice)

Arguments

• rs : ResultSet
• n : n sites to retrieve
• kwargs : dimensions to slice across

Returns

NamedDimsArray[sites, [Site Index, Unique ID, Rank], scenarios]

trajectory_heatmap(data::Matrix{Float64})::Tuple{Vector{Float64}, Vector{Float64}, Matrix{Int64}}

Estimate heatmap of trajectories from a 2D dataset.

Arguments

• data : An N*D matrix where N is time steps and D is the scenario outcome for the given timestep in N

Returns

OnlineStats.HeatMap

trajectory_heatmap_data(data::Matrix{Float64})::Tuple{Vector{Float64}, Vector{Float64}, Matrix{Int64}}

Estimate heatmap of trajectories from a 2D dataset.

Arguments

• data : An N*D matrix where N is time steps and D is the scenario outcome for the given timestep in N

Returns

Tuple of xedges, yedges, and bi-dimensional histogram matrix

ndims(m::Metric)::Int64

Infer the number of dimensions for a given outcome/metric.

(f::Metric)(raw, args...; kwargs...)
(f::Metric)(rs::ResultSet, args...; kwargs...)

Makes Metric types callable with arbitary arguments that are passed to associated function.

Root Mean Square Error

environmental_diversity(ms, inputs_i)

Obtain an indication of environmental factor diversity for a scenario set. Higher values indicate a greater of mix of environmental conditions were experienced between scenarios.

This is referred to as $E$.

Arguments

• ms : model spec
• inputs_i : inputs used for scenarios of interest

gmd(vals::AbstractVector{<:Real})::Float64
gmd(vals::AbstractMatrix{<:Real})

Gini's Mean Difference.

The absolute mean of all pairwise distances between elements in a given set.

References

1. La Haye, R., & Zizler, P. (2019). The Gini mean difference and variance. METRON, 77(1), 43-52. https://doi.org/10.1007/s40300-019-00149-2

2. Yitzhaki, S. (2003). Gini's Mean difference: A superior measure of variability for non-normal distributions. Metron - International Journal of Statistics, LXI(2), 285-316. https://ideas.repec.org/a/mtn/ancoec/030208.html

3. Kashif, M., Aslam, M., Al-Marshadi, A. H., & Jun, C.-H. (2016). Capability Indices for Non-Normal Distribution Using Gini's Mean Difference as Measure of Variability. IEEE Access, 4, 7322-7330. https://doi.org/10.1109/ACCESS.2016.2620241

intervention_diversity(ms, inputs_i)

Obtain an indication of intervention diversity for a scenario. Higher values indicate a greater of mix of interventions options were applied.

This is referred to as $D$.

Arguments

• ms : model spec
• inputs_i : inputs used for scenarios of interest

intervention_effort(ms, inputs_i)

Obtain an indication of intervention effort for each scenario and intervention type. This is referred to as $F$.

Arguments

• ms : model spec
• inputs_i : inputs used for scenarios of interest

Returns

Matrix of s * 8, where s is the number of scenarios and columns are: N_seed_TA, N_seed_CA, N_seed_SM, fogging, SRM, seed_years, shade_years, fog_years

normalize(vals::AbstractArray{<:Real})

Normalize values using feature scaling such that values are bound between 0 and 1, where 1 is equivalent to the maximum value found.

probability(vals::AbstractArray{<:Real})

Calculate probability of individual trajectories, given a scenario ensemble $S$.

temporal_variability(x::AbstractVector{<:Real})
temporal_variability(x::AbstractArray{<:Real, 2})
temporal_variability(x::AbstractArray{<:Real}, func_or_data...)

The V meta-metric.

As a meta-metric, it can be applied to any combination of metrics (including itself), assuming $x$ is bound between 0 and 1. If this is not the case, consider normalizing values first.

Examples

# Apply V to a time series
julia> temporal_variability(rand(50))

# Apply V to an ensemble of time series
julia> x = rand(50, 200)
julia> temporal_variability(x)

# Create and apply a modified V metric to an ensemble of time series.
# Where the argument is an array and not a function, the data is used directly
# and so it is assumed all matrices are of the same size and shape.
julia> temporal_variability(x, temporal_variabilty, temporal_variability(P(x)))
julia> temporal_variability(x, temporal_variabilty, P(x), D(x), E(x))

_category_bins(S::Int64, foi_spec::DataFrame)

Get number of bins for categorical variables.

Arguments

• S : Number of bins
• foi_spec : Model specification for factors of interest

_get_cat_quantile(foi_spec::DataFrame, factor_name::Symbol, steps::Vector{Float64})

Get quantile value for a given categorical variable.

Arguments

• foi_spec : Model specification for factors of interest
• factor_name : Contains true where the factor is categorical and false otherwise
• steps : Number of steps for defining bins

_get_factor_spec(model_spec::DataFrame, factors::Vector{Symbol})

Get model spec for specified factors.

Arguments

• model_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet
• factors : Factors considered for sensitivity analysis

convergence(X::DataFrame, y::NamedDimsArray, target_factors::Vector{Symbol}; n_steps::Int64=10)::NamedDimsArray
convergence(rs::ResultSet, X::DataFrame, y::NamedDimsArray, components::Vector{String}; n_steps::Int64=10)::NamedDimsArray

Calculates the PAWN sensitivity index for an increasing number of scenarios where the maximum is the total number of scenarios in scens. Number of scenario subsets determined by N_steps. Can be calculated for individual factors or aggregated over factors for specified model components.

Arguments

• rs : Result set (only needed if aggregating over model components).
• X : Model inputs
• y : Model outputs
• target_factors : Names of target factors represented by columns in X.
• components : Names of model components to aggregate over (e.g. [:Intervention, :Criteria]).
• n_steps : Number of steps to cut the total number of scenarios into.

Returns

NamedDimsArray, of min, lower bound, mean, median, upper bound, max, std, and cv summary statistics for an increasing number of scenarios.

ks_statistic(ks)

Calculate the Kolmogorov-Smirnov test statistic.

outcome_map(X::DataFrame, y::AbstractVecOrMat, rule, target_factors::Vector; S::Int=20, n_boot::Int=100, conf::Float64=0.95)::NamedDimsArray

Map normalized outcomes (defined by rule) to factor values discretized into S bins.

Produces a matrix indicating the range of (normalized) outcomes across factor space for each dimension (the model inputs). This is similar to a Regional Sensitivity Analysis, except that the model outputs are examined directly as opposed to a measure of sensitivity.

Note:

• y is normalized on a per-column basis prior to the analysis
• Empty areas of factor space (those that do not have any desired outcomes) will be assigned NaN

Arguments

• X : scenario specification
• y : Vector or Matrix of outcomes corresponding to scenarios in X
• rule : a callable defining a "desirable" scenario outcome
• target_factors : list of factors of interest to perform analyses on
• S : number of slices of factor space. Higher values equate to finer granularity
• n_boot : number of bootstraps (default: 100)
• conf : confidence interval (default: 0.95)

Returns

3-dimensional NamedDimsArray, of shape $S$ ⋅ $D$ ⋅ 3, where:

• \[S\]

  is the slices,

• \[D\]

  is the number of dimensions, with
• boostrapped mean (dim 1) and the lower/upper 95% confidence interval (dims 2 and 3).

Examples

# Get metric of interest
mu_tac = vec(mean(ADRIA.metrics.scenario_total_cover(rs), dims=:timesteps))

# Factors of interest
foi = [:SRM, :fogging, :a_adapt]

# Find scenarios where all metrics are above their median
rule = y -> all(y .> 0.5)

# Map input values where to their outcomes
ADRIA.sensitivity.outcome_map(X, y, rule, foi; S=20, n_boot=100, conf=0.95)

pawn(rs::ResultSet, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray
pawn(X::AbstractMatrix{<:Real}, y::AbstractVector{<:Real}, factor_names::Vector{String}; S::Int64=10)::NamedDimsArray
pawn(X::DataFrame, y::AbstractVector{<:Real}; S::Int64=10)::NamedDimsArray
pawn(X::NamedDimsArray, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray
pawn(X::Union{DataFrame,AbstractMatrix{<:Real}}, y::AbstractMatrix{<:Real}; S::Int64=10)::NamedDimsArray

Calculates the PAWN sensitivity index.

The PAWN method (by Pianosi and Wagener) is a moment-independent approach to Global Sensitivity Analysis. Outputs are characterized by their Cumulative Distribution Function (CDF), quantifying the variation in the output distribution after conditioning an input over "slices" ($S$) - the conditioning intervals. If both distributions coincide at all slices (i.e., the distributions are similar or identical), then the factor is deemed non-influential.

This implementation applies the Kolmogorov-Smirnov test as the distance measure and returns summary statistics (min, lower bound, mean, median, upper bound, max, std, and cv) over the slices.

Arguments

• rs : ResultSet
• X : Model inputs
• y : Model outputs
• factor_names : Names of each factor represented by columns in X
• S : Number of slides (default: 10)

Returns

NamedDimsArray, of min, mean, lower bound, median, upper bound, max, std, and cv summary statistics.

Examples

dom = ADRIA.load_domain("example_domain")
scens = ADRIA.sample(dom, 128)
rs = ADRIA.run_scenarios(dom, scens, "45")

# Get mean coral cover over time and locations
μ_tac = mean(ADRIA.metrics.scenario_total_cover(rs), dims=:timesteps)

ADRIA.sensitivity.pawn(rs, μ_tac)

References

1. Pianosi, F., Wagener, T., 2018. Distribution-based sensitivity analysis from a generic input-output sample. Environmental Modelling & Software 108, 197-207. https://doi.org/10.1016/j.envsoft.2018.07.019

2. Baroni, G., Francke, T., 2020. GSA-cvd Combining variance- and distribution-based global sensitivity analysis https://github.com/baronig/GSA-cvd

3. Puy, A., Lo Piano, S., & Saltelli, A. 2020. A sensitivity analysis of the PAWN sensitivity index. Environmental Modelling & Software, 127, 104679. https://doi.org/10.1016/j.envsoft.2020.104679

4. https://github.com/SAFEtoolbox/Miscellaneous/blob/main/ReviewofPuy_2020.pdf

Extended help

Pianosi and Wagener have made public their review responding to a critique of their method by Puy et al., (2020). A key criticism by Puy et al. was that the PAWN method is sensitive to its tuning parameters and thus may produce biased results. The tuning parameters referred to are the number of samples ($N$) and the number of conditioning points - $n$ in Puy et al., but denoted as $S$ here.

Puy et al., found that the ratio of $N$ (number of samples) to $S$ has to be sufficiently high ($N/S > 80$) to avoid biased results. Pianosi and Wagener point out this requirement is not particularly difficult to meet. Using the recommended value ($S := 10$), a sample of 1024 runs (small for purposes of Global Sensitivity Analysis) meets this requirement ($1024/10 = 102.4$). Additionally, lower values of $N/S$ is more an indication of faulty experimental design moreso than any deficiency of the PAWN method.

rsa(X::DataFrame, y::Vector{<:Real}, model_spec::DataFrame; S::Int64=10)::NamedDimsArray
rsa(rs::ResultSet, y::AbstractVector{<:Real}, factors::Vector{Symbol}; S::Int64=10)::NamedDimsArray
rsa(rs::ResultSet, y::AbstractArray{<:Real}; S::Int64=10)::NamedDimsArray

Perform Regional Sensitivity Analysis.

Regional Sensitivity Analysis is a Monte Carlo Filtering approach which aims to identify which (group of) factors drive model outputs within or outside of a specified bound. Outputs which fall inside the bounds are regarded as "behavioral", whereas those outside are "non-behavioral". The distribution of behavioral/non-behavioral subsets are compared for each factor. If the subsets are not similar, then the factor is influential. The sensitivity index is simply the maximum distance between the two distributions, with larger values indicating greater sensitivity.

The implemented approach slices factor space into $S$ bins and iteratively assesses behavioral (samples within the bin) and non-behavioral (out of bin samples) subsets with the non-parametric $k$-sample Anderson-Darling test. Larger values indicate greater dissimilarity (thus, sensitivity). The Anderson-Darling test places more weight on the tails compared to the Kolmogorov-Smirnov test.

RSA can indicate where in factor space model sensitivities may be, and contributes to a Value-of-Information (VoI) analysis.

Increasing the value of $S$ increases the granularity of the analysis, but necessitates larger sample sizes.

Note: Values of type missing indicate a lack of samples in the region.

Arguments

• rs : ResultSet
• X : scenario specification
• y : scenario outcomes
• model_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet
• factors : Specific model factors to examine
• S : number of bins to slice factor space into (default: 10)

Returns

NamedDimsArray, [bin values, factors]

Examples

ADRIA.sensitivity.rsa(X, y; S=10)

References

1. Pianosi, F., K. Beven, J. Freer, J. W. Hall, J. Rougier, D. B. Stephenson, and T. Wagener. 2016. Sensitivity analysis of environmental models: A systematic review with practical workflow. Environmental Modelling & Software 79:214-232. https://dx.doi.org/10.1016/j.envsoft.2016.02.008

2. Saltelli, A., M. Ratto, T. Andres, F. Campolongo, J. Cariboni, D. Gatelli, M. Saisana, and S. Tarantola. 2008. Global Sensitivity Analysis: The Primer. Wiley, West Sussex, U.K. https://dx.doi.org/10.1002/9780470725184 Accessible at: http://www.andreasaltelli.eu/file/repository/PrimerCorrected2022.pdf

tsa(X::DataFrame, y::AbstractMatrix)::NamedDimsArray

Perform Temporal (or time-varying) Sensitivity Analysis using the PAWN sensitivity index.

The sensitivity index value for time $t$ is inclusive of all time steps prior to $t$. Alternate approaches use a moving window, or only data for time $t$.

Examples

rs = ADRIA.load_results("a ResultSet of interest")

# Get scenario outcomes over time (shape: `time ⋅ scenarios`)
y_tac = ADRIA.metrics.scenario_total_cover(rs)

# Calculate sensitivity of outcome to factors for each time step
ADRIA.sensitivity.tsa(rs.inputs, y_tac)

Arguments

• X : Scenario specification
• y : scenario outcomes over time

Returns

NamedDimsArray, of shape $D$ ⋅ 6 ⋅ $T$, where

• \[D\]

  is the number of dimensions/factors
• 6 corresponds to the min, mean, median, max, std, and cv of the PAWN indices

• \[T\]

  is the number of time steps

coral_spec()

Template for coral parameter values for ADRIA. Includes "vital" bio/ecological parameters, to be filled with sampled or user-specified values.

Any parameter added to the params DataFrame defined here will automatically be made available to the ADRIA model.

Notes: Values for the historical, temporal patterns of degree heating weeks between bleaching years come from [1].

Returns

• params : NamedTuple[taxanames, paramnames, params], taxa names, parameter names, and parameter values for each coral taxa, group and size class

References

1. Lough, J. M., Anderson, K. D., & Hughes, T. P. (2018). Increasing thermal stress for tropical coral reefs: 1871-2017. Scientific Reports, 8(1), 6079. https://doi.org/10.1038/s41598-018-24530-9

2. Hall, V.R. & Hughes, T.P. 1996. Reproductive strategies of modular organisms: comparative studies of reef-building corals. Ecology, 77: 950 - 963. https://dx.doi.org/10.2307/2265514

3. Bozec, Y.-M., Rowell, D., Harrison, L., Gaskell, J., Hock, K., Callaghan, D., Gorton, R., Kovacs, E. M., Lyons, M., Mumby, P., & Roelfsema, C. (2021). Baseline mapping to support reef restoration and resilience-based management in the Whitsundays. https://doi.org/10.13140/RG.2.2.26976.20482

4. Bozec, Y.-M., Hock, K., Mason, R. A. B., Baird, M. E., Castro-Sanguino, C., Condie, S. A., Puotinen, M., Thompson, A., & Mumby, P. J. (2022). Cumulative impacts across Australia's Great Barrier Reef: A mechanistic evaluation. Ecological Monographs, 92(1), e01494. https://doi.org/10.1002/ecm.1494

5. Bairos-Novak, K.R., Hoogenboom, M.O., van Oppen, M.J.H., Connolly, S.R., 2021. Coral adaptation to climate change: Meta-analysis reveals high heritability across multiple traits. Global Change Biology 27, 5694-5710. https://doi.org/10.1111/gcb.15829

create_coral_struct(bounds=(0.9, 1.1))

Generates Coral struct using the default parameter spec.

Example

# Define coral struct with auto-generated parameter ranges
# (default in ADRIA is ± 10%, triangular distribution with peak at 0.5)
create_coral_struct()
coral = Coral()

# Recreate coral spec ± 50% from nominal values
create_coral_struct((0.5, 1.5))
coral = Coral()

env_stats(rs::ResultSet, s_name::String, rcp::String)
env_stats(rs::ResultSet, s_name::String, rcp::String, scenario::Int)
env_stats(rs::ResultSet, s_name::String, stat::String, rcp::String, scenario::Int)

Extract statistics for a given environmental layer ("DHW" or "wave")

growthODE(du, X, p, _)

Base coral growth function.

Proportion of corals within a size class are modeled to transition to the next size class up. Assumes colony sizes are evenly distributed within each size bin. Transitions are a ratio of the change in colony size to the width of the bin. See coral_spec() for further detail.

Note that recruitment pertains to coral groups ($n = 6$) and represents the contribution to the cover of the smallest size class within each group. While growth and mortality metrics pertain to groups (6) as well as size classes (6) across all sites (total of 36 by $n_sites$), recruitment is a 6 by $n_sites$ array.

run_scenario(domain::Domain, idx::Int64, scenario::Union{AbstractVector, DataFrameRow}, data_store::NamedTuple, cache::NamedTuple)::Nothing
run_scenario(domain::Domain, idx::Int64, scenario::Union{AbstractVector, DataFrameRow}, domain::Domain, data_store::NamedTuple)::Nothing
run_scenario(domain::Domain, scenario::Union{AbstractVector, DataFrameRow}, cache::NamedTuple)::NamedTuple
run_scenario(domain::Domain, scenario::NamedTuple)::NamedTuple

Run individual scenarios for a given domain, saving results to a Zarr data store. Results are stored in Zarr format at a pre-configured location. Sets up a new cache if not provided.

Notes

Logs of site ranks only store the mean site rankings over all environmental scenarios. This is to reduce the volume of data stored.

Returns

Nothing

run_scenario(idx::Int64, param_set::Union{AbstractVector, DataFrameRow}, domain::Domain, data_store::NamedTuple, cache::NamedTuple)::Nothing
run_scenario(idx::Int64, param_set::Union{AbstractVector, DataFrameRow}, domain::Domain, data_store::NamedTuple)::Nothing
run_scenario(param_set::Union{AbstractVector, DataFrameRow}, domain::Domain, cache::NamedTuple)::NamedTuple
run_scenario(param_set::NamedTuple, domain::Domain)::NamedTuple

WARNING: Deprecated set of functions to be removed in v1.0

Instead, use: run_scenario(dom, scenarios, ...)

select(r::ResultSet, op::String)

Hacky scenario filtering - to be replaced with more robust approach.

Only supports filtering by single attribute. Should be expanded to support filtering metric results too.

Examples

select(result, "guided .> 0.0")

# Above expands to:
# result.inputs.guided .> 0.0

site_area(rs::ResultSet)::Vector{Float64}

Extract vector of a location's total area in its areal unit (m², km², etc).

site_area(domain::Domain)::Vector{Float64}

Get site area for the given domain.

site_k_area(rs::ResultSet)::Vector{Float64}

Extract vector of a location's coral carrying capacity in terms of absolute area.

site_k_area(domain::Domain)::Vector{Float64}

Get maximum coral cover area for the given domain in absolute area.

timesteps(rs::ResultSet)

Retrieve the time steps represented in the result set.

Arguments

• rs : ResultSet

Extract the time steps represented in the data package.

ADRIADomain{Σ,M,I,D,X,Y,Z}

Core ADRIA domain. Represents study area.

Domain(name::String, rcp::String, timeframe::Vector, site_data_fn::String, site_id_col::String, unique_site_id_col::String, init_coral_fn::String, conn_path::String, dhw_fn::String, wave_fn::String, cyclone_mortality_fn::String)::Domain

Convenience constructor for Domain.

Arguments

• name : Name of domain
• dpkg_path : location of data package
• rcp : RCP scenario represented
• timeframe : Time steps represented
• site_data_fn : File name of spatial data used
• site_id_col : Column holding name of reef the site is associated with (non-unique)
• unique_site_id_col : Column holding unique site names/ids
• init_coral_fn : Name of file holding initial coral cover values
• conn_path : Path to directory holding connectivity data
• dhw_fn : Filename of DHW data cube in use
• wave_fn : Filename of wave data cube
• cyclone_mortality_fn : Filename of cyclone mortality data cube

Barrier function to create Domain struct without specifying Intervention/Criteria/Coral/SimConstant parameters.

SimConstants

Struct of simulation constants for ADRIA

References

1. Lough, J. M., Anderson, K. D., & Hughes, T. P. (2018). Increasing thermal stress for tropical coral reefs: 1871-2017. Scientific Reports, 8(1), 6079. https://doi.org/10.1038/s41598-018-24530-9

2. Hughes, T. P., Kerry, J. T., Baird, A. H., Connolly, S. R., Dietzel, A., Eakin, C. M., Heron, S. F., Hoey, A. S., Hoogenboom, M. O., Liu, G., McWilliam, M. J., Pears, R. J., Pratchett, M. S., Skirving, W. J., Stella, J. S., & Torda, G. (2018). Global warming transforms coral reef assemblages. Nature, 556(7702), 492-496. https://doi.org/10.1038/s41586-018-0041-2

3. Bozec, Y.-M., Rowell, D., Harrison, L., Gaskell, J., Hock, K., Callaghan, D., Gorton, R., Kovacs, E. M., Lyons, M., Mumby, P., & Roelfsema, C. (2021). Baseline mapping to support reef restoration and resilience-based management in the Whitsundays. https://doi.org/10.13140/RG.2.2.26976.20482

4. Bozec, Y.-M., Hock, K., Mason, R. A. B., Baird, M. E., Castro-Sanguino, C., Condie, S. A., Puotinen, M., Thompson, A., & Mumby, P. J. (2022). Cumulative impacts across Australia's Great Barrier Reef: A mechanistic evaluation. Ecological Monographs, 92(1), e01494. https://doi.org/10.1002/ecm.1494