diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 3b7f7e3b6..974801f8b 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.6","generation_timestamp":"2024-11-26T09:49:43","documenter_version":"1.6.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.7","generation_timestamp":"2024-12-03T00:09:28","documenter_version":"1.6.0"}} \ No newline at end of file diff --git a/dev/API/index.html b/dev/API/index.html index 92dbcbaf2..d07cebb6d 100644 --- a/dev/API/index.html +++ b/dev/API/index.html @@ -1,18 +1,18 @@ ADRIA API · ADRIA.jl
GitHub

ADRIA API

Metrics

ADRIA.metrics._absolute_juveniles — Method
absolute_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::AbstractVector{T})::AbstractArray{T,2} where {T<:Real}
-absolute_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}

Juvenile coral cover in m².

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations)

  • coral_spec : Coral spec DataFrame
  • k_area : The coral habitable area.
source
ADRIA.metrics._absolute_shelter_volume — Method
absolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}
+absolute_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}

Juvenile coral cover in m².

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations)

  • coral_spec : Coral spec DataFrame
  • k_area : The coral habitable area.
source
ADRIA.metrics._absolute_shelter_volume — Method
absolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}
 absolute_shelter_volume(X::YAXArray{T,4}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}
 absolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}
 absolute_shelter_volume(X::YAXArray{T,4}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}
-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
  • k_area : area in m^2 for each site
  • max_cover : maximum possible coral cover for each site (in percentage of loc_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
source
ADRIA.metrics._colony_Lcm2_to_m3m2 — Method
_colony_Lcm2_to_m3m2(inputs::DataFrame)::Tuple
-_colony_Lcm2_to_m3m2(inputs::YAXArray)::Tuple{Vector{Float64},Vector{Float64}}

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
source
ADRIA.metrics._coral_evenness — Method
coral_evenness(r_taxa_cover::AbstractArray{T})::AbstractArray{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

source
ADRIA.metrics._get_ranks — Method
_get_ranks(rs::ResultSet, intervention::Int64; kwargs...)

Extracts results for a specific intervention (:seed or :fog)

source
ADRIA.metrics._juvenile_indicator — Method
juvenile_indicator(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::Vector{Float64})::AbstractArray{T,2} where {T<:Real}
-juvenile_indicator(rs::ResultSet)::AbstractArray{<:Real,2}

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

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations).

  • coral_spec : Coral spec DataFrame.
  • k_area : The coral habitable area.

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

source
ADRIA.metrics._max_juvenile_area — Function
_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².

source
ADRIA.metrics._reef_condition_index — Method
reef_condition_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray; threshold=2)::AbstractArray
-reef_condition_index(rs::ResultSet)::AbstractArray{<:Real}

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

YAXArray[timesteps ⋅ locations ⋅ scenarios]

source
ADRIA.metrics._reef_fish_index — Method
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

YAXArray[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

source
ADRIA.metrics._reef_tourism_index — Method
reef_tourism_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray, intcp_u::Vector)::AbstractArray
-reef_tourism_index(rs::ResultSet; intcp_u::Bool=false)::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
  • intcp_u : ?
source
ADRIA.metrics._relative_cover — Method
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 with dimensions (ntimesteps, nfunctionalgroups * nsize_classes,

n_locations) of raw model results (coral cover relative to available space)

Returns

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

source
ADRIA.metrics._relative_juveniles — Method
relative_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame)::AbstractArray{T,2} where {T<:Real}
-relative_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}

Juvenile coral cover relative to total site area.

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations)

  • coral_spec : Coral spec DataFrame
source
ADRIA.metrics._relative_loc_taxa_cover — Method
relative_loc_taxa_cover(X::AbstractArray{T}, k_area::Vector{T}, n_groups::Int64)::AbstractArray{T,3} where {T<:Real}

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations)

  • k_area : The coral habitable area.
  • n_groups : Number of function coral groups.

Returns

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

source
ADRIA.metrics._relative_shelter_volume — Method
relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}
+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
  • k_area : area in m^2 for each site
  • max_cover : maximum possible coral cover for each site (in percentage of loc_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
source
ADRIA.metrics._colony_Lcm2_to_m3m2 — Method
_colony_Lcm2_to_m3m2(inputs::DataFrame)::Tuple
+_colony_Lcm2_to_m3m2(inputs::YAXArray)::Tuple{Vector{Float64},Vector{Float64}}

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
source
ADRIA.metrics._coral_evenness — Method
coral_evenness(r_taxa_cover::AbstractArray{T})::AbstractArray{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

source
ADRIA.metrics._get_ranks — Method
_get_ranks(rs::ResultSet, intervention::Int64; kwargs...)

Extracts results for a specific intervention (:seed or :fog)

source
ADRIA.metrics._juvenile_indicator — Method
juvenile_indicator(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::Vector{Float64})::AbstractArray{T,2} where {T<:Real}
+juvenile_indicator(rs::ResultSet)::AbstractArray{<:Real,2}

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

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations).

  • coral_spec : Coral spec DataFrame.
  • k_area : The coral habitable area.

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

source
ADRIA.metrics._max_juvenile_area — Function
_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².

source
ADRIA.metrics._reef_condition_index — Method
reef_condition_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray; threshold=2)::AbstractArray
+reef_condition_index(rs::ResultSet)::AbstractArray{<:Real}

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

YAXArray[timesteps ⋅ locations ⋅ scenarios]

source
ADRIA.metrics._reef_fish_index — Method
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

YAXArray[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

source
ADRIA.metrics._reef_tourism_index — Method
reef_tourism_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray, intcp_u::Vector)::AbstractArray
+reef_tourism_index(rs::ResultSet; intcp_u::Bool=false)::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
  • intcp_u : ?
source
ADRIA.metrics._relative_cover — Method
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 with dimensions (ntimesteps, nfunctionalgroups * nsize_classes,

n_locations) of raw model results (coral cover relative to available space)

Returns

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

source
ADRIA.metrics._relative_juveniles — Method
relative_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame)::AbstractArray{T,2} where {T<:Real}
+relative_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}

Juvenile coral cover relative to total site area.

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations)

  • coral_spec : Coral spec DataFrame
source
ADRIA.metrics._relative_loc_taxa_cover — Method
relative_loc_taxa_cover(X::AbstractArray{T}, k_area::Vector{T}, n_groups::Int64)::AbstractArray{T,3} where {T<:Real}

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations)

  • k_area : The coral habitable area.
  • n_groups : Number of function coral groups.

Returns

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

source
ADRIA.metrics._relative_shelter_volume — Method
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::DataFrame)::AbstractArray{T} where {T<:Real}
 relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}
 relative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}
@@ -21,13 +21,13 @@
 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 & MSV > 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
  • scens : 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

source
ADRIA.metrics._relative_taxa_cover — Method
relative_taxa_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real}, n_groups::Int64)::AbstractArray{<:Real,2}
-relative_taxa_cover(rs::ResultSet)::AbstractArray{<:Real,2}

Relative coral cover grouped by taxa/species sumed up across all locations.

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations).

  • k_area : The coral habitable area.
  • n_groups : Number of function coral groups.

Returns

Coral cover, grouped by taxa for the given scenario, summed up across all locations, relative to total k area.

source
ADRIA.metrics._scenario_absolute_juveniles — Method
scenario_absolute_juveniles(data::YAXArray, 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.

Arguments

  • X : Raw data for a single scenario.
  • coral_spec : Coral spec DataFrame.
  • k_area : K_area.
  • rs : Resultset.
source
ADRIA.metrics._scenario_asv — Method
scenario_asv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}
-scenario_asv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

Arguments

  • asv : Absolute shelter volume.
  • rs : Resultset.
source
ADRIA.metrics._scenario_evenness — Method
scenario_evenness(ev::YAXArray; kwargs...)::AbstractArray{<:Real}
-scenario_evenness(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

source
ADRIA.metrics._scenario_juvenile_indicator — Method
scenario_juvenile_indicator(data::YAXArray, 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.

Arguments

  • X : Raw data for a single scenario.
  • coral_spec : Coral spec DataFrame.
  • k_area : K_area.
  • rs : Resultset.
source
ADRIA.metrics._scenario_rci — Method
scenario_rci(rci::YAXArray, tac::YAXArray; 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.

source
ADRIA.metrics._scenario_relative_juveniles — Method
scenario_relative_juveniles(X::YAXArray{<:Real,3}, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}
+\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
  • scens : 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
source
ADRIA.metrics._relative_taxa_cover — Method
relative_taxa_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real}, n_groups::Int64)::AbstractArray{<:Real,2}
+relative_taxa_cover(rs::ResultSet)::AbstractArray{<:Real,2}

Relative coral cover grouped by taxa/species sumed up across all locations.

Arguments

  • X : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,

n_locations).

  • k_area : The coral habitable area.
  • n_groups : Number of function coral groups.

Returns

Coral cover, grouped by taxa for the given scenario, summed up across all locations, relative to total k area.

source
ADRIA.metrics._scenario_absolute_juveniles — Method
scenario_absolute_juveniles(data::YAXArray, 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.

Arguments

  • X : Raw data for a single scenario.
  • coral_spec : Coral spec DataFrame.
  • k_area : K_area.
  • rs : Resultset.
source
ADRIA.metrics._scenario_asv — Method
scenario_asv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}
+scenario_asv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

Arguments

  • asv : Absolute shelter volume.
  • rs : Resultset.
source
ADRIA.metrics._scenario_evenness — Method
scenario_evenness(ev::YAXArray; kwargs...)::AbstractArray{<:Real}
+scenario_evenness(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

source
ADRIA.metrics._scenario_juvenile_indicator — Method
scenario_juvenile_indicator(data::YAXArray, 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.

Arguments

  • X : Raw data for a single scenario.
  • coral_spec : Coral spec DataFrame.
  • k_area : K_area.
  • rs : Resultset.
source
ADRIA.metrics._scenario_rci — Method
scenario_rci(rci::YAXArray, tac::YAXArray; 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.

source
ADRIA.metrics._scenario_relative_juveniles — Method
scenario_relative_juveniles(X::YAXArray{<:Real,3}, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}
 scenario_relative_juveniles(rs::ResultSet; kwargs...)::YAXArray

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

Arguments

  • X : Raw data for a single scenario.
  • rs : Resultset.
  • coral_spec : Coral spec DataFrame.
  • k_area : K_area.

Examples

num_scens = 2^5
 scens = ADRIA.sample(dom, num_scens)
 
@@ -35,10 +35,10 @@
 _k_area = site_k_area(dom)
 
 # X contains raw coral cover results for a single scenario
-ADRIA.metrics.scenario_relative_juveniles(X, _coral_spec, _k_area)
source
ADRIA.metrics._scenario_rfi — Method

scenariorfi(rfi::YAXArray; kwargs...) scenariorfi(rs::ResultSet; kwargs...)

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

source
ADRIA.metrics._scenario_rsv — Method
scenario_rsv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}
-scenario_rsv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

source
ADRIA.metrics._scenario_rti — Method
scenario_rti(rti::YAXArray; kwargs...)
-scenario_rti(rs::ResultSet; kwargs...)

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

source
ADRIA.metrics._scenario_total_cover — Method
scenario_total_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

Arguments

  • tac : Total absolute cover
  • rs : ResultSet
source
ADRIA.metrics._shelter_species_loop! — Method

shelterspeciesloop!(X::YAXArray, ASV::YAXArray, nspecies::Int64, colonyvolm3perm2::V, karea::V) where {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
  • k_area : habitable area of site in m²
source
ADRIA.metrics._shelter_species_loop — Method
_shelter_species_loop(X::AbstractArray{T1,3}, n_species::Int64, colony_vol_m3_per_m2::Array{F}, max_colony_vol_m3_per_m2::Array{F}, k_area::Array{F})::YAXArray where {T1<:Real,F<:Float64}

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_group_and_size : number of species (taxa and size classes) considered
  • colony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class
  • max_colony_vol_m3_per_m2 : theoretical maximum volume per m² of coverage for each taxa
  • k_area : habitable area of site in m² (i.e., k area)
source
ADRIA.metrics._total_absolute_cover — Method
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

  • relative_cover : Array with relative_cover
  • 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².

source
ADRIA.metrics.call_metric — Method
call_metric(metric::Union{Function,Metric}, data::YAXArray, args...; kwargs...)

Convenience method that slices the data in the specified manner.

Arguments

  • metric : Function, the metric function to apply to "raw" data.
  • data : YAXArray, data to pass into metric
  • args : Additional positional arguments to pass into metric
  • kwargs : Additional keyword arguments to pass into slice_results
    • dims : dummy keyword argument, not used but defined to allow use with other methods
source
ADRIA.metrics.dominates — Method
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()

source
ADRIA.metrics.ensemble_loc_difference — Method
ensemble_loc_difference(outcome::YAXArray{T,3}, scens::DataFrame; agg_metric::Union{Function,AbstractFloat}=median, diff_target=:guided, conf::Float64=0.95, rng::AbstractRNG=Random.GLOBAL_RNG)::YAXArray where {T}

Mean bootstrapped difference (counterfactual - target) between some outcome aggregated for each location.

Arguments

  • outcome : Metric outcome with dimensions (:timesteps, :locations, :scenarios).
  • scens : Scenarios DataFrame.
  • agg_metric : Metric used to aggregate scenarios when comparing between counterfactual and

target. If it is an AbstractFloat between 0 and 1, it uses the bs_metric-th quantile. Defaults to median.

  • diff_target : Target group of scenarios to compare with. Valid options are :guided and

:unguided. Defaults to :guided

  • conf : Percentile used for the confidence interval. Defaults to 0.95.
  • rng : Pseudorandom number generator.

Example

# Load domain
+ADRIA.metrics.scenario_relative_juveniles(X, _coral_spec, _k_area)
source
ADRIA.metrics._scenario_rfi — Method

scenariorfi(rfi::YAXArray; kwargs...) scenariorfi(rs::ResultSet; kwargs...)

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

source
ADRIA.metrics._scenario_rsv — Method
scenario_rsv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}
+scenario_rsv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

source
ADRIA.metrics._scenario_rti — Method
scenario_rti(rti::YAXArray; kwargs...)
+scenario_rti(rs::ResultSet; kwargs...)

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

source
ADRIA.metrics._scenario_total_cover — Method
scenario_total_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}

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

Arguments

  • tac : Total absolute cover
  • rs : ResultSet
source
ADRIA.metrics._shelter_species_loop! — Method

shelterspeciesloop!(X::YAXArray, ASV::YAXArray, nspecies::Int64, colonyvolm3perm2::V, karea::V) where {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
  • k_area : habitable area of site in m²
source
ADRIA.metrics._shelter_species_loop — Method
_shelter_species_loop(X::AbstractArray{T1,3}, n_species::Int64, colony_vol_m3_per_m2::Array{F}, max_colony_vol_m3_per_m2::Array{F}, k_area::Array{F})::YAXArray where {T1<:Real,F<:Float64}

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_group_and_size : number of species (taxa and size classes) considered
  • colony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class
  • max_colony_vol_m3_per_m2 : theoretical maximum volume per m² of coverage for each taxa
  • k_area : habitable area of site in m² (i.e., k area)
source
ADRIA.metrics._total_absolute_cover — Method
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

  • relative_cover : Array with relative_cover
  • 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².

source
ADRIA.metrics.call_metric — Method
call_metric(metric::Union{Function,Metric}, data::YAXArray, args...; kwargs...)

Convenience method that slices the data in the specified manner.

Arguments

  • metric : Function, the metric function to apply to "raw" data.
  • data : YAXArray, data to pass into metric
  • args : Additional positional arguments to pass into metric
  • kwargs : Additional keyword arguments to pass into slice_results
    • dims : dummy keyword argument, not used but defined to allow use with other methods
source
ADRIA.metrics.dominates — Method
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()

source
ADRIA.metrics.ensemble_loc_difference — Method
ensemble_loc_difference(outcome::YAXArray{T,3}, scens::DataFrame; agg_metric::Union{Function,AbstractFloat}=median, diff_target=:guided, conf::Float64=0.95, rng::AbstractRNG=Random.GLOBAL_RNG)::YAXArray where {T}

Mean bootstrapped difference (counterfactual - target) between some outcome aggregated for each location.

Arguments

  • outcome : Metric outcome with dimensions (:timesteps, :locations, :scenarios).
  • scens : Scenarios DataFrame.
  • agg_metric : Metric used to aggregate scenarios when comparing between counterfactual and

target. If it is an AbstractFloat between 0 and 1, it uses the bs_metric-th quantile. Defaults to median.

  • diff_target : Target group of scenarios to compare with. Valid options are :guided and

:unguided. Defaults to :guided

  • conf : Percentile used for the confidence interval. Defaults to 0.95.
  • rng : Pseudorandom number generator.

Example

# Load domain
 dom = ADRIA.load_domain(path_to_domain)
 
 # Create scenarios
@@ -59,8 +59,8 @@
 
 # Plot maps of difference to the counterfactual
 ADRIA.viz.map(rs, gd_res[summary=At(:agg_value)]; diverging=true)
-ADRIA.viz.map(rs, ug_res[summary=At(:agg_value)]; diverging=true)

Returns

Vector with bootstrapped difference (counterfactual - guided) for each location.

source
ADRIA.metrics.fill_metadata! — Method
fill_metadata!(outcomes::YAXArray{T,N,A}, metric::Metric)::YAXArray{T,N,A} where {T,N,A}
-fill_metadata!(outcomes::YAXArray{T,N,A}, metadata::Dict{Symbol,Any})::YAXArray{T,N,A} where {T,N,A}

Fill outcomes YAXArray metadata (properties attribute).

Arguments

  • outcomes : YAXArray datacube of metric outcomes.
  • metric : ADRIA.metrics.Metric object.
  • metadata : Dict to be used to fill outcomes metrics metadata.
source
ADRIA.metrics.fog_ranks — Method
fog_ranks(rs::ResultSet; kwargs...)

Arguments

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

Returns

YAXArray[timesteps, sites, scenarios]

Example

ADRIA.metrics.fog_ranks(rs; timesteps=1:10, scenarios=3:5)
source
ADRIA.metrics.loc_trajectory — Method
loc_trajectory(metric, data::YAXArray{D,T,N,A})::YAXArray where {D,T,N,A}

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

Examples

using Statistics
+ADRIA.viz.map(rs, ug_res[summary=At(:agg_value)]; diverging=true)

Returns

Vector with bootstrapped difference (counterfactual - guided) for each location.

source
ADRIA.metrics.fill_metadata! — Method
fill_metadata!(outcomes::YAXArray{T,N,A}, metric::Metric)::YAXArray{T,N,A} where {T,N,A}
+fill_metadata!(outcomes::YAXArray{T,N,A}, metadata::Dict{Symbol,Any})::YAXArray{T,N,A} where {T,N,A}

Fill outcomes YAXArray metadata (properties attribute).

Arguments

  • outcomes : YAXArray datacube of metric outcomes.
  • metric : ADRIA.metrics.Metric object.
  • metadata : Dict to be used to fill outcomes metrics metadata.
source
ADRIA.metrics.fog_ranks — Method
fog_ranks(rs::ResultSet; kwargs...)

Arguments

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

Returns

YAXArray[timesteps, sites, scenarios]

Example

ADRIA.metrics.fog_ranks(rs; timesteps=1:10, scenarios=3:5)
source
ADRIA.metrics.loc_trajectory — Method
loc_trajectory(metric, data::YAXArray{D,T,N,A})::YAXArray 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)
@@ -77,27 +77,27 @@
 #75×216 YAXArray{Float64,2} with dimensions:
 #  Dim{:timesteps} Categorical{Any} Any[1, 2, …, 74, 75] Unordered,
 #  Dim{:locations} Categorical{Any} Any[1, 2, …, 215, 216] Unordered
-#Total size: 126.56 KB

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 locations

source
ADRIA.metrics.metric_label — Method
metric_label(m::Metric)::String
+#Total size: 126.56 KB

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 locations

source
ADRIA.metrics.metric_label — Method
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²]"
source
ADRIA.metrics.n_fog_locations — Method
n_fog_locations(rs::ResultSet; kwargs...)::Matrix{Int64}

Determine the number of locations fogged at each time step, for each scenario.

Returns

YAXArray[timesteps ⋅ scenarios] indicating the number of locations fogged at each time step.

source
ADRIA.metrics.n_seed_locations — Method
n_seed_locations(rs::ResultSet; kwargs...)::Matrix{Int64}

Determine the number of locations seeded at each time step, for each scenario.

Returns

YAXArray[timesteps ⋅ scenarios] indicating the number of locations seeded at each time step.

source
ADRIA.metrics.nds — Function
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.

source
ADRIA.metrics.per_loc — Method
per_loc(metric, data::YAXArray{D,T,N,A})::YAXArray 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 locations.

source
ADRIA.metrics.scenario_outcomes — Method
scenario_outcomes(rs::ResultSet, metrics::Vector{Metric})::YAXArray

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

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

Examples

metrics::Vector{ADRIA.metrics.Metric} = [
+# "Scenario Total Cover [m²]"
source
ADRIA.metrics.n_fog_locations — Method
n_fog_locations(rs::ResultSet; kwargs...)::Matrix{Int64}

Determine the number of locations fogged at each time step, for each scenario.

Returns

YAXArray[timesteps ⋅ scenarios] indicating the number of locations fogged at each time step.

source
ADRIA.metrics.n_seed_locations — Method
n_seed_locations(rs::ResultSet; kwargs...)::Matrix{Int64}

Determine the number of locations seeded at each time step, for each scenario.

Returns

YAXArray[timesteps ⋅ scenarios] indicating the number of locations seeded at each time step.

source
ADRIA.metrics.nds — Function
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.

source
ADRIA.metrics.per_loc — Method
per_loc(metric, data::YAXArray{D,T,N,A})::YAXArray 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 locations.

source
ADRIA.metrics.scenario_outcomes — Method
scenario_outcomes(rs::ResultSet, metrics::Vector{Metric})::YAXArray

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

YAXArray 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)
source
ADRIA.metrics.scenario_trajectory — Method
scenario_trajectory(data::AbstractArray; metric=mean)::YAXArray{<:Real}

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]

source
ADRIA.metrics.seed_ranks — Method
seed_ranks(rs::ResultSet; kwargs...)

Arguments

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

Returns

YAXArray[timesteps, sites, scenarios]

Example

ADRIA.metrics.seed_ranks(rs; timesteps=1:10, scenarios=3:5)
source
ADRIA.metrics.slice_results — Method
slice_results(data::YAXArray; timesteps=(:), species=(:), locations=(:), scenarios=(:))

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

source
ADRIA.metrics.summarize — Method
summarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function)::YAXArray{<:Real}
-summarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function, timesteps::Union{UnitRange,Vector{Int64},BitVector})::YAXArray{<: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

YAXArray with summary metric for the remaining axis.

source
ADRIA.metrics.summarize_absolute_shelter_volume — Method
summarize_absolute_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
-summarize_absolute_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

source
ADRIA.metrics.summarize_coral_evenness — Method
summarize_coral_evenness(raw::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
-summarize_coral_evenness(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

source
ADRIA.metrics.summarize_raw — Method
summarize_raw(data::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

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

source
ADRIA.metrics.summarize_relative_cover — Method
summarize_relative_cover(rc::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
-summarize_relative_cover(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized relative cover.

source
ADRIA.metrics.summarize_relative_shelter_volume — Method
summarize_relative_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
-summarize_relative_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

source
ADRIA.metrics.summarize_total_cover — Method
summarize_total_cover(raw::YAXArray, areas::AbstractArray{<:Real}; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
-summarize_total_cover(rs::ResultSet; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized total absolute cover.

source
ADRIA.metrics.top_N_sites — Method
top_N_sites(rs::ResultSet; N::Int64; metric::relative_cover)
+outcomes = ADRIA.metrics.scenario_outcomes(rs, metrics)
source
ADRIA.metrics.scenario_trajectory — Method
scenario_trajectory(data::AbstractArray; metric=mean)::YAXArray{<:Real}

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]

source
ADRIA.metrics.seed_ranks — Method
seed_ranks(rs::ResultSet; kwargs...)

Arguments

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

Returns

YAXArray[timesteps, sites, scenarios]

Example

ADRIA.metrics.seed_ranks(rs; timesteps=1:10, scenarios=3:5)
source
ADRIA.metrics.slice_results — Method
slice_results(data::YAXArray; timesteps=(:), species=(:), locations=(:), scenarios=(:))

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

source
ADRIA.metrics.summarize — Method
summarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function)::YAXArray{<:Real}
+summarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function, timesteps::Union{UnitRange,Vector{Int64},BitVector})::YAXArray{<: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

YAXArray with summary metric for the remaining axis.

source
ADRIA.metrics.summarize_absolute_shelter_volume — Method
summarize_absolute_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
+summarize_absolute_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

source
ADRIA.metrics.summarize_coral_evenness — Method
summarize_coral_evenness(raw::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
+summarize_coral_evenness(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

source
ADRIA.metrics.summarize_raw — Method
summarize_raw(data::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

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

source
ADRIA.metrics.summarize_relative_cover — Method
summarize_relative_cover(rc::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
+summarize_relative_cover(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized relative cover.

source
ADRIA.metrics.summarize_relative_shelter_volume — Method
summarize_relative_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
+summarize_relative_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized coral evenness.

source
ADRIA.metrics.summarize_total_cover — Method
summarize_total_cover(raw::YAXArray, areas::AbstractArray{<:Real}; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}
+summarize_total_cover(rs::ResultSet; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}

Calculate summarized total absolute cover.

source
ADRIA.metrics.top_N_sites — Method
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 : Number 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

YAXArray[:scenarios, :locations], where locations indicates order of location ranking.

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)
source
ADRIA.metrics.top_n_seeded_sites — Method
top_n_seeded_sites(rs::ResultSet, n::Int64; kwargs...)

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

Arguments

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

Returns

YAXArray[locations, [locid, locname, rank], scenarios]

source
ADRIA.metrics.trajectory_heatmap — Method
trajectory_heatmap(data::YAXArray)::HeatMap

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

source
ADRIA.metrics.trajectory_heatmap_data — Method
trajectory_heatmap_data(data::YAXArray)::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

source
Base.ndims — Method
ndims(m::Metric)::Int64

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

source
ADRIA.metrics.Metric — Method
(f::Metric)(raw, args...; kwargs...)
-(f::Metric)(rs::ResultSet, args...; kwargs...)

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

source

Performance indicators

ADRIA.performance.environmental_diversity — Method
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
source
ADRIA.performance.gmd — Method
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

source
ADRIA.performance.intervention_diversity — Method
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
source
ADRIA.performance.intervention_effort — Method
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

source
ADRIA.performance.normalize — Method
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.

source
ADRIA.metrics.top_n_seeded_sites — Method
top_n_seeded_sites(rs::ResultSet, n::Int64; kwargs...)

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

Arguments

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

Returns

YAXArray[locations, [locid, locname, rank], scenarios]

source
ADRIA.metrics.trajectory_heatmap — Method
trajectory_heatmap(data::YAXArray)::HeatMap

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

source
ADRIA.metrics.trajectory_heatmap_data — Method
trajectory_heatmap_data(data::YAXArray)::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

source
Base.ndims — Method
ndims(m::Metric)::Int64

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

source
ADRIA.metrics.Metric — Method
(f::Metric)(raw, args...; kwargs...)
+(f::Metric)(rs::ResultSet, args...; kwargs...)

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

source

Performance indicators

ADRIA.performance.environmental_diversity — Method
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
source
ADRIA.performance.gmd — Method
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

source
ADRIA.performance.intervention_diversity — Method
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
source
ADRIA.performance.intervention_effort — Method
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

source
ADRIA.performance.normalize — Method
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.

source
ADRIA.performance.temporal_variability — Method
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))
@@ -110,14 +110,14 @@
 # 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))
source

Sensitivity

ADRIA.sensitivity._category_bins — Method
_category_bins(foi_spec::DataFrame)::Int64

Get number of bins for categorical variables.

Arguments

  • foi_spec : Model specification for factors of interest

Returns

Number of bins relevant to the factor of interest

source
ADRIA.sensitivity._create_seq_store — Method
_create_seq_store(model_spec::DataFrame, unordered_cat::Vector{Symbol}, S::Int64)::Dict{Symbol,Vector{Float64}}

Get stored bin sequences for each factor type.

Arguments

  • model_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet
  • unordered_cat : Factors considered for sensitivity analysis of unordered categorical type.
  • S : Number of bins.

Returns

A dictionary containing bin sequences for each factor

source

Sensitivity

ADRIA.sensitivity._category_bins — Method
_category_bins(foi_spec::DataFrame)::Int64

Get number of bins for categorical variables.

Arguments

  • foi_spec : Model specification for factors of interest

Returns

Number of bins relevant to the factor of interest

source
ADRIA.sensitivity._create_seq_store — Method
_create_seq_store(model_spec::DataFrame, unordered_cat::Vector{Symbol}, S::Int64)::Dict{Symbol,Vector{Float64}}

Get stored bin sequences for each factor type.

Arguments

  • model_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet
  • unordered_cat : Factors considered for sensitivity analysis of unordered categorical type.
  • S : Number of bins.

Returns

A dictionary containing bin sequences for each factor

source
ADRIA.sensitivity._foi_data_stores — Method
_foi_data_stores(
     seq_store::Dict{Symbol,Vector{Float64}},
     m_spec::DataFrame,
     unordered_cat::Vector{Symbol};
     second_dim::NamedTuple
-)::Dataset

Generate data stores of correct size for each factor of interest.

Arguments

  • seq_store : Dictionary for storing bin sequences (created by _create_seq_store)
  • m_spec : Model specification
  • unordered_cat : List of unordered categorical variables.
  • second_dim : second storage dimension (e.g. (CI=["mean","lower","upper"], ))

Returns

Dataset containing storage for sensitivity ranges for each factor.

source
ADRIA.sensitivity._get_cat_quantile — Method
_get_cat_quantile(foi_spec::DataFrame, factor_name::Symbol, steps::Vector{Float64})::Vector{Float64}

Get quantiles 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

Returns

Quantile for a categorical factor.

source
ADRIA.sensitivity._get_factor_quantile — Method
_get_factor_quantile(seq_store::Dict{Symbol,Vector{Float64}}, foi_spec::DataFrame, fact_t::Symbol)

Checks the type of the factor to calculate its quantile.

Arguments

  • seq_store : storage containing bin sequences for factors considered
  • foi_spec : Model specification for factors of interest
  • X_f : Scenario dataframe for factor of interest
  • factor_name : Contains true where the factor is categorical and false otherwise

Returns

Quantile for factor fact_t, given bin sequences in seq_store

source
ADRIA.sensitivity._get_factor_spec — Method
_get_factor_spec(model_spec::DataFrame, factors::Vector{Symbol})::DataFrame

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
source
ADRIA.sensitivity._map_outcomes — Method
_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Union{BitVector,Vector{Int64}})::Union{BitVector,Vector{Int64}}
-_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Function)::Vector{Int64}

Apply rule to create mapping between $X$ (model inputs/parameters/factors) and $y$ (model outcomes).

Note

Where the rule is a vector indicating true/false, the y argument is ignored. The function accepts the y argument simply to maintain compatibility so the same method name can be applied.

Arguments

  • y : Model outputs/outcomes
  • rule : BitVector, or Function that returns a BitVector, indicating outcomes that meet some desired threshold/behavior.
source
ADRIA.sensitivity.convergence — Method
convergence(X::DataFrame, y::YAXArray, target_factors::Vector{Symbol}; n_steps::Int64=10)::YAXArray
-convergence(rs::ResultSet, X::DataFrame, y::YAXArray, components::Vector{String}; n_steps::Int64=10)::YAXArray

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

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

source
ADRIA.sensitivity.outcome_map — Method
outcome_map(p::YAXArray, X_q::AbstractArray, X_f::AbstractArray, y::AbstractVecOrMat{<:Real}, behave::BitVector; n_boot::Int64=100, conf::Float64=0.95)::YAXArray
+)::Dataset

Generate data stores of correct size for each factor of interest.

Arguments

  • seq_store : Dictionary for storing bin sequences (created by _create_seq_store)
  • m_spec : Model specification
  • unordered_cat : List of unordered categorical variables.
  • second_dim : second storage dimension (e.g. (CI=["mean","lower","upper"], ))

Returns

Dataset containing storage for sensitivity ranges for each factor.

source
ADRIA.sensitivity._get_cat_quantile — Method
_get_cat_quantile(foi_spec::DataFrame, factor_name::Symbol, steps::Vector{Float64})::Vector{Float64}

Get quantiles 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

Returns

Quantile for a categorical factor.

source
ADRIA.sensitivity._get_factor_quantile — Method
_get_factor_quantile(seq_store::Dict{Symbol,Vector{Float64}}, foi_spec::DataFrame, fact_t::Symbol)

Checks the type of the factor to calculate its quantile.

Arguments

  • seq_store : storage containing bin sequences for factors considered
  • foi_spec : Model specification for factors of interest
  • X_f : Scenario dataframe for factor of interest
  • factor_name : Contains true where the factor is categorical and false otherwise

Returns

Quantile for factor fact_t, given bin sequences in seq_store

source
ADRIA.sensitivity._get_factor_spec — Method
_get_factor_spec(model_spec::DataFrame, factors::Vector{Symbol})::DataFrame

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
source
ADRIA.sensitivity._map_outcomes — Method
_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Union{BitVector,Vector{Int64}})::Union{BitVector,Vector{Int64}}
+_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Function)::Vector{Int64}

Apply rule to create mapping between $X$ (model inputs/parameters/factors) and $y$ (model outcomes).

Note

Where the rule is a vector indicating true/false, the y argument is ignored. The function accepts the y argument simply to maintain compatibility so the same method name can be applied.

Arguments

  • y : Model outputs/outcomes
  • rule : BitVector, or Function that returns a BitVector, indicating outcomes that meet some desired threshold/behavior.
source
ADRIA.sensitivity.convergence — Method
convergence(X::DataFrame, y::YAXArray, target_factors::Vector{Symbol}; n_steps::Int64=10)::YAXArray
+convergence(rs::ResultSet, X::DataFrame, y::YAXArray, components::Vector{String}; n_steps::Int64=10)::YAXArray

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

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

source
ADRIA.sensitivity.outcome_map — Method
outcome_map(p::YAXArray, X_q::AbstractArray, X_f::AbstractArray, y::AbstractVecOrMat{<:Real}, behave::BitVector; n_boot::Int64=100, conf::Float64=0.95)::YAXArray
 outcome_map(X::DataFrame, y::AbstractVecOrMat{<:Real}, rule::Union{Function,BitVector,Vector{Int64}}, target_factors::Vector{Symbol}, model_spec::DataFrame; S::Int64=10, n_boot::Int64=100, conf::Float64=0.95)::Dataset
 outcome_map(X::DataFrame, y::AbstractVecOrMat{<:Real}, rule::Union{Function,BitVector,Vector{Int64}}, target_factor::Symbol, model_spec::DataFrame; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::YAXArray
 outcome_map(X::DataFrame, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}
@@ -133,7 +133,7 @@
 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)
source
ADRIA.sensitivity.pawn — Method
pawn(rs::ResultSet, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray
+ADRIA.sensitivity.outcome_map(X, y, rule, foi; S=20, n_boot=100, conf=0.95)
source
ADRIA.sensitivity.pawn — Method
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
@@ -144,29 +144,29 @@
 # 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.

source
ADRIA.sensitivity.rsa — Method
rsa(X::DataFrame, y::AbstractVector{<:Real}, model_spec::DataFrame; S::Int64=10)::Dataset
+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.

source
ADRIA.sensitivity.rsa — Method
rsa(X::DataFrame, y::AbstractVector{<:Real}, model_spec::DataFrame; S::Int64=10)::Dataset
 rsa(r_s::YAXArray, X_q::AbstractArray, X_i::AbstractArray, y::AbstractVecOrMat{<:Real}, sel::BitVector)::YAXArray
 rsa(X::Vector{Float64}, y::AbstractVector{<:Real}, foi_spec::DataFrame; S::Int64=10)::YAXArray
 rsa(rs::ResultSet, y::AbstractVector{T}; S::Int64=10)::Dataset where {T<:Real}
 rsa(rs::ResultSet, y::AbstractVector{T}, factors::Vector{Symbol}; S::Int64=10)::Dataset where {T<:Real}
-rsa(rs::ResultSet, y::AbstractVector{T}, factor::Symbol; S::Int64=10)::YAXArray where {T<:Real}

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

Dataset

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

source
ADRIA.sensitivity.tsa — Method
tsa(X::DataFrame, y::AbstractMatrix)::YAXArray

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")
+rsa(rs::ResultSet, y::AbstractVector{T}, factor::Symbol; S::Int64=10)::YAXArray where {T<:Real}

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

Dataset

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

source
ADRIA.sensitivity.tsa — Method
tsa(X::DataFrame, y::AbstractMatrix)::YAXArray

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

YAXArray, 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
source

General API

ADRIA.coral_spec — Method
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

source
ADRIA.create_coral_struct — Function
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
+ADRIA.sensitivity.tsa(rs.inputs, y_tac)

Arguments

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

Returns

YAXArray, 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
source

General API

ADRIA.coral_spec — Method
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

source
ADRIA.create_coral_struct — Function
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()
source
ADRIA.env_stats — Method
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")

source
ADRIA.growthODE — Method
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_locs$), recruitment is a 6 by $n_locs$ array.

source
ADRIA.loc_area — Method
loc_area(rs::ResultSet)::Vector{Float64}

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

source
ADRIA.loc_area — Method
loc_area(domain::Domain)::Vector{Float64}

Get site area for the given domain.

source
ADRIA.run_scenario — Method
run_scenario(domain::Domain, idx::Int64, scenario::Union{AbstractVector,DataFrameRow}, functional_groups::Vector{Vector{FunctionalGroup}}, data_store::NamedTuple)::Nothing
+env_stats(rs::ResultSet, s_name::String, stat::String, rcp::String, scenario::Int)

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

source
ADRIA.growthODE — Method
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_locs$), recruitment is a 6 by $n_locs$ array.

source
ADRIA.loc_area — Method
loc_area(rs::ResultSet)::Vector{Float64}

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

source
ADRIA.loc_area — Method
loc_area(domain::Domain)::Vector{Float64}

Get site area for the given domain.

source
ADRIA.run_scenario — Method
run_scenario(domain::Domain, idx::Int64, scenario::Union{AbstractVector,DataFrameRow}, functional_groups::Vector{Vector{FunctionalGroup}}, data_store::NamedTuple)::Nothing
 run_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow})::NamedTuple
-run_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow}, RCP::String)::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.

Arguments

  • domain : Domain
  • idx : Scenario index

Returns

Nothing

source
ADRIA.select — Method
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")
+run_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow}, RCP::String)::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.

Arguments

  • domain : Domain
  • idx : Scenario index

Returns

Nothing

source
ADRIA.select — Method
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
source
ADRIA.site_k_area — Method
site_k_area(rs::ResultSet)::Vector{Float64}

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

source
ADRIA.site_k_area — Method
site_k_area(domain::Domain)::Vector{Float64}

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

source
ADRIA.timesteps — Method
timesteps(rs::ResultSet)

Retrieve the time steps represented in the result set.

Arguments

  • rs : ResultSet
source
ADRIA.Domain — Method
Domain(name::String, rcp::String, timeframe::Vector, location_data_fn::String, location_id_col::String, cluster_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
  • location_data_fn : File name of spatial data used
  • location_id_col : Column holding name of reef the location is associated with (non-unique)
  • cluster_id_col : Column holding unique cluster 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
source
ADRIA.Domain — Method

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

source
ADRIA.SimConstants — Type
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

source
+# result.inputs.guided .> 0.0source
ADRIA.site_k_area — Method
site_k_area(rs::ResultSet)::Vector{Float64}

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

source
ADRIA.site_k_area — Method
site_k_area(domain::Domain)::Vector{Float64}

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

source
ADRIA.timesteps — Method
timesteps(rs::ResultSet)

Retrieve the time steps represented in the result set.

Arguments

  • rs : ResultSet
source
ADRIA.timesteps — Method

Extract the time steps represented in the data package.

source
ADRIA.ADRIADomain — Type
ADRIADomain{Σ,M,I,D,X,Y,Z}

Core ADRIA domain. Represents study area.

source
ADRIA.Domain — Method
Domain(name::String, rcp::String, timeframe::Vector, location_data_fn::String, location_id_col::String, cluster_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
  • location_data_fn : File name of spatial data used
  • location_id_col : Column holding name of reef the location is associated with (non-unique)
  • cluster_id_col : Column holding unique cluster 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
source
ADRIA.Domain — Method

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

source
ADRIA.SimConstants — Type
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

source
diff --git a/dev/architecture/architecture/index.html b/dev/architecture/architecture/index.html index 536cc7fb6..22ac3cb70 100644 --- a/dev/architecture/architecture/index.html +++ b/dev/architecture/architecture/index.html @@ -1,3 +1,3 @@ Architectural overview · ADRIA.jl
GitHub

Architectural overview

ADRIA consists of three overarching components:

  1. a set of Multi-Criteria Decision Analysis methods used to emulate decision-makers
  2. a coral ecosystem model (referred to as ADRIAmod)
  3. a suite of analysis and assessment methods

Each component may be applied separately, or altogether to perform an end-to-end analysis. This page documents the underlying architectural implementation of ADRIA, detailing how the above components interact.

General Structure

The primary purpose of ADRIA is to support reef restoration and adaptation through the development of robust intervention strategies under deep uncertainty. Here, "robustness" refers to the ability of an intervention strategy to meet desired outcomes under uncertain future conditions, which themselves are unknown and may be unexpected. To do so, ADRIA adopts an Exploratory Scenario Modelling framework to explore the range of possible futures and their outcomes.

Exploratory Scenario Modelling (ESM) itself leverages uncertainty and sensitivity analysis (UA/SA). Uncertainty analysis quantifies the variability of uncertainties in a given system and its expected range of outcomes. Sensitivity analysis examines the effect of a change in a model's inputs to its outputs. Common workflows to such analyses involve a three-step process (as discussed in Pianosi et al., 2016):

  1. Input sampling
  2. Model evaluation
  3. Post-processing

When ADRIA is applied in its entirety, "input sampling" is analogous to scenario generation: all model factors (the inputs) are collated and are sampled through a quasi-monte carlo process. The Sobol' sampling method is adopted as the default, although any method provided by the QuasiMonteCarlo.jl package can be used. Sample adjustment is required to map sampled values (which are continuous) to categorical or whole number values (e.g., Baroni and Tarantola, 2014) as may be expected by some factors. Values are also adjusted to avoid implausible factor combinations, such as active intervention factors in the case of non-intervention scenarios.

Model evaluation is simply running the model with the generated scenario set.

Post-processing is the analysis and visualization step.

Model Factors

Factors in ADRIA are defined across four sub-components:

  1. Intervention
  2. CriteriaWeights
  3. EnvironmentalLayer
  4. Coral

Each sub-component is represented by a struct with fields for each parameter. The Intervention sub-component holds parameters that define a given adopted intervention strategy/option: how many (and type of) corals are to be seeded, the length of any deployment, the start/end years, and so on. The CriteriaWeights sub-component relates to the preferences for the Multi-Criteria Decision Analysis methods, further detailed in Dynamic Multi-Criteria Decision Analysis. For the ADRIA ecosystem model (ADRIAmod), EnviromentalLayer relate to the environmental scenarios available for a given simulation (a time series of DHW and Wave stress), itself determined on the loading of data (see Running scenarios).

The Coral sub-component relates to ADRIAmod, currently representing six coral species:

  1. Arborescent Acropora
  2. Tabular Acropora
  3. Corymbose Acropora
  4. Corymbose non-Acropora
  5. Small massives and encrusting
  6. Large massives

ADRIAmod represents these across six size classes, with six parameter sets for each coral species and size class. These six parameter sets are further detailed in Model Factors, however, it results in a large number of unique factors (6 groups x 6 size classes x 6 parameters: 216 factors). Instead of specifying all coral factors by hand, ADRIA instead auto-generates the sub-component using a common template (see coral_spec() and create_coral_struct() in General API). Through discussion with expert stakeholders, factor bounds were set to +/- 10% of their default values following a triangular distribution, the peak of which is the default value.

The ModelParameters.jl package is used to provide a simple table-like interface to model factors. ADRIA provides a wrapper to the Param type provided by ModelParameters.jl called a Factor. These Factors requires ADRIA-specific metadata to be provided alongside the default value for a given model factor. These include the assumed distribution of the factor, distribution factors (principally the lower and upper bounds), and a human-readable name and description. An example from the Intervention sub-component is shown below.

guided::N = Factor(0.0, ptype="ordered categorical", dist=(-1.0, 3.0), dist_params=DiscreteUniform,
-        name="Guided", description="Choice of MCDA approach.")

Note that factor values are provided as floats - even where discrete values are expected - to maintain type stability. Mixing floats with integers will lead to an error. Similarly, values used to update the model should always be floats.

Combinations of the realized factor values then represent a "scenario".

Parameter Collation and Scenario Generation

See Cookbook examples for an example how-to on collating model factors and generating samples.

References

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.

+ name="Guided", description="Choice of MCDA approach.")

Note that factor values are provided as floats - even where discrete values are expected - to maintain type stability. Mixing floats with integers will lead to an error. Similarly, values used to update the model should always be floats.

Combinations of the realized factor values then represent a "scenario".

Parameter Collation and Scenario Generation

See Cookbook examples for an example how-to on collating model factors and generating samples.

References

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.

diff --git a/dev/architecture/domain_and_resultsets/index.html b/dev/architecture/domain_and_resultsets/index.html index fb12fb838..7edfd916e 100644 --- a/dev/architecture/domain_and_resultsets/index.html +++ b/dev/architecture/domain_and_resultsets/index.html @@ -76,4 +76,4 @@ │ ├───relative_shelter_volume │ ├───relative_taxa_cover │ └───total_absolute_cover -└───site_data +└───site_data diff --git a/dev/dMCDA/index.html b/dev/dMCDA/index.html index 9b1ba808c..aaaf549d1 100644 --- a/dev/dMCDA/index.html +++ b/dev/dMCDA/index.html @@ -1,2 +1,2 @@ -Dynamic Multi-Criteria Decision Analysis · ADRIA.jl
GitHub

Dynamic Multi-Criteria Decision Analysis

Multi-Criteria Decision Making

Multi-criteria decision analysis (MCDA) encompasses a series of methods for conducting decision making in a way that is formalised, structured and transparent. It evaluates the decision objective according to numerical measures of decision criteria assembled by the decision maker. Constructing explicit criteria over which to evaluate alternatives allows a transparent evaluation of benefits, negatives and trade-offs in coming to a decision solution.

Typical approaches to MCDA require the construction of a "decision matrix", which takes the form of a $X^{n \cdot m}$, where $n$ is the number of alternate options available, and $m$ is the number of criteria.

In the context of ADRIA, the alternate options relate to the locations being assessed. The criteria then relate to the common set of attributes on which the locations are being judged, such as the projected heat stress (in terms of DHW), depth, and level of incoming or outgoing connectivity.

MCDA methods provide a ranking according to the set of assessed criteria, in the form of:

\[r = g(X, w, d)\]

where:

  • \[g()\]

    refers to a given MCDA algorithm (see JMcDM.jl).

  • \[X\]

    is the decision matrix

  • \[w\]

    is the weights afforded to each criteria, indicating their relative importance

  • \[d\]

    is the desired directionality for each criterion (to minimize the criteria value, or to maximize)

  • \[r\]

    is the ranking determined by $g()$

When applied in conjunction with scenario analyses, locations are assessed at each decision point.

When conducting location selection, the analyses are applied to the initial conditions represented in the Domain.

+Dynamic Multi-Criteria Decision Analysis · ADRIA.jl
GitHub

Dynamic Multi-Criteria Decision Analysis

Multi-Criteria Decision Making

Multi-criteria decision analysis (MCDA) encompasses a series of methods for conducting decision making in a way that is formalised, structured and transparent. It evaluates the decision objective according to numerical measures of decision criteria assembled by the decision maker. Constructing explicit criteria over which to evaluate alternatives allows a transparent evaluation of benefits, negatives and trade-offs in coming to a decision solution.

Typical approaches to MCDA require the construction of a "decision matrix", which takes the form of a $X^{n \cdot m}$, where $n$ is the number of alternate options available, and $m$ is the number of criteria.

In the context of ADRIA, the alternate options relate to the locations being assessed. The criteria then relate to the common set of attributes on which the locations are being judged, such as the projected heat stress (in terms of DHW), depth, and level of incoming or outgoing connectivity.

MCDA methods provide a ranking according to the set of assessed criteria, in the form of:

\[r = g(X, w, d)\]

where:

  • \[g()\]

    refers to a given MCDA algorithm (see JMcDM.jl).

  • \[X\]

    is the decision matrix

  • \[w\]

    is the weights afforded to each criteria, indicating their relative importance

  • \[d\]

    is the desired directionality for each criterion (to minimize the criteria value, or to maximize)

  • \[r\]

    is the ranking determined by $g()$

When applied in conjunction with scenario analyses, locations are assessed at each decision point.

When conducting location selection, the analyses are applied to the initial conditions represented in the Domain.

diff --git a/dev/development/building_docs/index.html b/dev/development/building_docs/index.html index 0a305272d..d0db8aa39 100644 --- a/dev/development/building_docs/index.html +++ b/dev/development/building_docs/index.html @@ -2,4 +2,4 @@ Building Documentation · ADRIA.jl
GitHub

Building Documentation

ADRIA documentation is built using Documenter.jl.

Building documentation locally

As the documentation is build from a separate environment, it must be maintained/updated to incorporate any changes to ADRIA.

$ julia --project=docs
 (docs) pkg> resolve
 (docs) pkg> up

If no changes to the environment are necessary, simply run make.jl from the docs folder:

$ cd docs
-$ julia --project=. make.jl

Locally generated documentation can be found under docs/build. Open the index.html file with any web browser.

Documentation deployment

Documentation is hosted on GitHub Pages via GitHub Actions.

Configuration is found here.

Documentation is automatically built and deployed:

  • When a PR targeting main is submitted In this case, a preview URL is created: e.g., a URL with previews/PR### at the end, where PR### refers to the PR ID.
  • On commit/merge to main In this case the main documentation website is updated
+$ julia --project=. make.jl

Locally generated documentation can be found under docs/build. Open the index.html file with any web browser.

Documentation deployment

Documentation is hosted on GitHub Pages via GitHub Actions.

Configuration is found here.

Documentation is automatically built and deployed:

diff --git a/dev/development/development_setup/index.html b/dev/development/development_setup/index.html index 78817fdac..866d609ff 100644 --- a/dev/development/development_setup/index.html +++ b/dev/development/development_setup/index.html @@ -11,4 +11,4 @@ include("test/runtests.jl")

If a specific test case is being run, write the test file to be a standalone script (importing all necessary packages, including Test) and run it directly.

Doing so allows use of debugging packages if necessary.

include("test/some_test_file.jl")

Once the test is complete, put the tests in a testset as and if required. If a new file is added to the test suite, include() it in test/runtests.jl

See the Test documentation for further details.

Code Style

We are currently moving to follow Blue Style Guide. All PRs should follow this style guide. The julia-format GitHub workflow will check that your PR's code is formatted. Note that this check requires all code in the repo to be formatted, not only the files modified by your PR.

Use the VSCode Format Document or Format Selection actions to format your code.

To reformat the entire project:

using JuliaFormatter
 format(".")

If this returns false, call format() again.

Formatter configuration is defined in .JuliaFormatter.toml, see JuliaFormatter docs.

VSCode Settings

Open Settings (Ctrl+,). Search for trim and ensure the following options are all ticked/enabled:

An optional, but recommended, step would be to add a ruler guide to indicate where the character limit/width is.

Search for rulers and click on "Edit in settings.json" under "Editor: Rulers"

Add "92" to the list of ruler lengths, such that the editor.rulers entry looks like this:

"editor.rulers": [
         92
-    ]

Adding multiple values adds more guide lines at the indicated widths.

Important: if you installed the oh7z Julia Formatter VSCode extension, uninstall or disable it for this workspace. That extension always uses its formatter settings and does not support .JuliaFormatter.toml whereas the main Julia extension does. The only reason to use the oh7z extension is for Julia projects that do not have a .JuliaFormatter.toml file.

Git blame ignore revs

If you have GitLens (or similar extension), it will show the author of a line of code using git blame. To ignore commits like "re-format entire project", run this once:

git config --local blame.ignoreRevsFile .git-blame-ignore-revs

If you reformat code and want to ignore that commit, simply add the commit SHA to the .git-blame-ignore-revs file.

Notes

The very first import of the ADRIA package will be very slow as it attempts to precompile common functions to reduce later start up time. The same applies when running ADRIA for the first time. This slow initial precompilation has to be repeated if the package is modified, but will remain "fast" if no changes are made.

Use the Revise package to avoid having to repeatedly restart the REPL to incorporate code changes. By default, the VS Code REPL will auto-load this package.

A custom sysimage can also be created to reduce start up times.

VS Code now has (experimental) support for generating a custom sysimage for its REPL. Prior to Julia v1.9, a custom sysimage for the development/sandbox environment was highly recommended. Julia v1.9 introduced an improved precompilation process and the concept of extension packages. As many packages are still in the process of taking advantage of these changes, the sysimage may not successfully build. Given precompilation is now much faster than previously, the sysimage can be considered to be a "nice to have".

The same caveats as above apply: the sysimage has to be recreated if the project specification (e.g., expected package dependencies) changes.

See: This guide

Otherwise, if the VS Code build task cannot be used, see the documentation here for a quick how to. Note: compilation time to create a sysimage can be upwards of 15mins and, again, has to be repeated if the project packages are updated.

+ ]

Adding multiple values adds more guide lines at the indicated widths.

Important: if you installed the oh7z Julia Formatter VSCode extension, uninstall or disable it for this workspace. That extension always uses its formatter settings and does not support .JuliaFormatter.toml whereas the main Julia extension does. The only reason to use the oh7z extension is for Julia projects that do not have a .JuliaFormatter.toml file.

Git blame ignore revs

If you have GitLens (or similar extension), it will show the author of a line of code using git blame. To ignore commits like "re-format entire project", run this once:

git config --local blame.ignoreRevsFile .git-blame-ignore-revs

If you reformat code and want to ignore that commit, simply add the commit SHA to the .git-blame-ignore-revs file.

Notes

The very first import of the ADRIA package will be very slow as it attempts to precompile common functions to reduce later start up time. The same applies when running ADRIA for the first time. This slow initial precompilation has to be repeated if the package is modified, but will remain "fast" if no changes are made.

Use the Revise package to avoid having to repeatedly restart the REPL to incorporate code changes. By default, the VS Code REPL will auto-load this package.

A custom sysimage can also be created to reduce start up times.

VS Code now has (experimental) support for generating a custom sysimage for its REPL. Prior to Julia v1.9, a custom sysimage for the development/sandbox environment was highly recommended. Julia v1.9 introduced an improved precompilation process and the concept of extension packages. As many packages are still in the process of taking advantage of these changes, the sysimage may not successfully build. Given precompilation is now much faster than previously, the sysimage can be considered to be a "nice to have".

The same caveats as above apply: the sysimage has to be recreated if the project specification (e.g., expected package dependencies) changes.

See: This guide

Otherwise, if the VS Code build task cannot be used, see the documentation here for a quick how to. Note: compilation time to create a sysimage can be upwards of 15mins and, again, has to be repeated if the project packages are updated.

diff --git a/dev/development/docker/index.html b/dev/development/docker/index.html index 29a5c6b61..4203e211f 100644 --- a/dev/development/docker/index.html +++ b/dev/development/docker/index.html @@ -50,4 +50,4 @@ --mount type=bind,source="$(pwd)"/output,target=/data/output \ --mount type=bind,source="$(pwd)"/sandbox,target=/opt/adria-sandbox/src \ --mount type=bind,source="$(pwd)"/ADRIA.jl,target=/usr/local/src/adria \ - ADRIA.jl/adria-sandbox:latest

In both cases, the initial working directory will be the installation-location for the sandbox application's source code, and you can invoke any command you like from that shell prompt, e.g:

julia --project=@. dev.jl

Warning: For julia commands, you will probably need to use the --project=@. argument. This tells Julia that it's working environment is based in a parent directory of the one the sandbox source code is installed to, which is where the build configured all the precompiled dependencies. If you omit this, the pre-installed packages may not all be available.

+ ADRIA.jl/adria-sandbox:latest

In both cases, the initial working directory will be the installation-location for the sandbox application's source code, and you can invoke any command you like from that shell prompt, e.g:

julia --project=@. dev.jl

Warning: For julia commands, you will probably need to use the --project=@. argument. This tells Julia that it's working environment is based in a parent directory of the one the sandbox source code is installed to, which is where the build configured all the precompiled dependencies. If you omit this, the pre-installed packages may not all be available.

diff --git a/dev/development/metrics/index.html b/dev/development/metrics/index.html index ab7ba10cc..34574d2ab 100644 --- a/dev/development/metrics/index.html +++ b/dev/development/metrics/index.html @@ -8,4 +8,4 @@ total_absolute_cover = Metric(_total_absolute_cover, (:timesteps, :sites, :scenarios), "m²") # Unit of measure is optional, in cases where the values are non-dimensional -# some_example_metric = Metric(_some_example_metric, (:timesteps, :scenarios)) +# some_example_metric = Metric(_some_example_metric, (:timesteps, :scenarios)) diff --git a/dev/development/release_guide/index.html b/dev/development/release_guide/index.html index f11287a67..99169833e 100644 --- a/dev/development/release_guide/index.html +++ b/dev/development/release_guide/index.html @@ -3,4 +3,4 @@ Release notes: -Paste the generated release notes here.

See Julia Registrator usage notes here for more details.

Issues can block release

The JuliaRegistrator bot submits a corresponding Pull Request with the Julia package registry. Registration may be blocked for a number of reasons. Keep an eye on the auto-submitted Pull Request and resolve any issues reported there. Otherwise the package version will never be released.

Development Release

Development releases provide users with the most recent "working" version of ADRIA and may still have some known bugs. It provides users a chance to try new features and/or provide feedback before a public release.

Deploying a Development Release follows the same steps as "Public" releases, except:

Release Candidates

Release candidates are releases that are not yet "final" but are close to it. Release candidates provide a "last chance" opportunity for users to report bugs prior to a "final" release.

Deploying a Release Candidate follows the same steps as "Public" releases, except:

+Paste the generated release notes here.

See Julia Registrator usage notes here for more details.

Issues can block release

The JuliaRegistrator bot submits a corresponding Pull Request with the Julia package registry. Registration may be blocked for a number of reasons. Keep an eye on the auto-submitted Pull Request and resolve any issues reported there. Otherwise the package version will never be released.

Development Release

Development releases provide users with the most recent "working" version of ADRIA and may still have some known bugs. It provides users a chance to try new features and/or provide feedback before a public release.

Deploying a Development Release follows the same steps as "Public" releases, except:

Release Candidates

Release candidates are releases that are not yet "final" but are close to it. Release candidates provide a "last chance" opportunity for users to report bugs prior to a "final" release.

Deploying a Release Candidate follows the same steps as "Public" releases, except:

diff --git a/dev/index.html b/dev/index.html index d97709e20..33cbf298d 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Introduction · ADRIA.jl
GitHub

Introduction

What is ADRIA.jl?

ADRIA is a decision support platform for informing reef restoration and adaptation interventions through scenario exploration and analysis, decision heuristics (MCDA), alongside a small coral ecosystem model.

Among the most common usecases are:

  • Running a number of scenarios under different environmental and intervention conditions (see Loading a Domain, Generating scenarios and Running scenarios);
  • Extracting metrics for each scenario and timestep such as coral cover, shelter volume or number of juveniles (see Metrics);
  • Using these metrics to perform a range of analyses like time series clustering (grouping together scenarios with similar temporal behaviour; see Analysis);
  • Using the visualization tools to plot some of the mentioned metrics or analysis (see Analysis);

More details about each of these can be found in the next sections.

Docker documentation

ADRIA.jl features a set of Docker build targets which allow usage, development and experimentation of the ADRIA Julia package. See ADRIA Docker Setup for more information.

Troubleshooting F.A.Q

ADRIA.jl is under active development and from time to time issues may arise. Here are some answers to some issues encountered.

Q. I get this warning when trying to load pre-existing results: Results were produced with a different version of ADRIA (v0.x.x). The installed version of ADRIA is: v0.y.y. Errors may occur when analyzing data. (where x and y are different numbers).

A. The result set being loaded were generated by a different version of ADRIA, and in a possibly incompatible format. Sometimes, results may still be produced/analyzed as normal. In other times, ADRIA.jl or the expected metadata in the result set may have changed leading to errors when conducting analyses.

Either go back to the version indicated, or re-run the scenarios to obtain results in the updated format.

Q. I get an error or warning about an ENV variable not being found or set.

A. Double check the configuration settings in config.toml (see above).

Q. How do I run my own scenarios?

A. Scenarios are defined in a CSV file (with parameter values in columns, so that each row defines a scenario).

  • See the example_scenarios.csv file in the ADRIA data specification repository for an idea of what this looks like.
  • See Extracting model details example in Cookbook examples on how to extract the model specification and parameter table for a given domain.
  • See also the Generating and running scenarios example in Cookbook examples which showcases how to run such a file for a given study area.
+Introduction · ADRIA.jl
GitHub

Introduction

What is ADRIA.jl?

ADRIA is a decision support platform for informing reef restoration and adaptation interventions through scenario exploration and analysis, decision heuristics (MCDA), alongside a small coral ecosystem model.

Among the most common usecases are:

  • Running a number of scenarios under different environmental and intervention conditions (see Loading a Domain, Generating scenarios and Running scenarios);
  • Extracting metrics for each scenario and timestep such as coral cover, shelter volume or number of juveniles (see Metrics);
  • Using these metrics to perform a range of analyses like time series clustering (grouping together scenarios with similar temporal behaviour; see Analysis);
  • Using the visualization tools to plot some of the mentioned metrics or analysis (see Analysis);

More details about each of these can be found in the next sections.

Docker documentation

ADRIA.jl features a set of Docker build targets which allow usage, development and experimentation of the ADRIA Julia package. See ADRIA Docker Setup for more information.

Troubleshooting F.A.Q

ADRIA.jl is under active development and from time to time issues may arise. Here are some answers to some issues encountered.

Q. I get this warning when trying to load pre-existing results: Results were produced with a different version of ADRIA (v0.x.x). The installed version of ADRIA is: v0.y.y. Errors may occur when analyzing data. (where x and y are different numbers).

A. The result set being loaded were generated by a different version of ADRIA, and in a possibly incompatible format. Sometimes, results may still be produced/analyzed as normal. In other times, ADRIA.jl or the expected metadata in the result set may have changed leading to errors when conducting analyses.

Either go back to the version indicated, or re-run the scenarios to obtain results in the updated format.

Q. I get an error or warning about an ENV variable not being found or set.

A. Double check the configuration settings in config.toml (see above).

Q. How do I run my own scenarios?

A. Scenarios are defined in a CSV file (with parameter values in columns, so that each row defines a scenario).

  • See the example_scenarios.csv file in the ADRIA data specification repository for an idea of what this looks like.
  • See Extracting model details example in Cookbook examples on how to extract the model specification and parameter table for a given domain.
  • See also the Generating and running scenarios example in Cookbook examples which showcases how to run such a file for a given study area.
diff --git a/dev/search_index.js b/dev/search_index.js index aa2366e68..ba0cbf204 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"development/docker/#ADRIA-Docker-Setup","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This repo contains a multistage Dockerfile for generating containerised applications based on the ADRIA source code in this repository.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"docker configuration\nadria-base\nA note about platform build targets\nPublished base images\nBuilding adria-base\nRunning adria-base with a non-interactive Julia command\nRunning adria-base as an interactive Julia shell\nRunning adria-base with a non-Julia entrypoint\nDeriving an image from adria-base\nadria-dev\nBuilding adria-dev\nRunning adria-dev as an interactive Julia shell\nRunning ADRIA tests with adria-dev\nadria-sandbox\nBuilding adria-sandbox\nRunning adria-sandbox\nInteracting with adria-sandbox","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#Docker-configuration","page":"ADRIA Docker Setup","title":"Docker configuration","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The following build args and defaults are available to configure the build behaviour.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"ARG SANDBOX_FROM=\"adria-dev\": What base image should be used for the sandbox\nARG ADRIA_VERSION=\"0.11.0\": What version of ADRIA from package registry to install in adria-base\nARG JULIA_VERSION=\"1.10.4\": See https://hub.docker.com/*/julia for valid versions.","category":"page"},{"location":"development/docker/#adria-base","page":"ADRIA Docker Setup","title":"adria-base","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-base image variant is a Julia image with ADRIA.jl installed to a shared environment that is included in the Julia LOAD_PATH directly from it's github origin.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The Docker entrypoint for the adria-base image is the julia binary, so you can run just this base container if you want to invoke julia commands, including commands that depend on the ADRIA package being installed.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"It can also be used as a base-image for any Julia application that needs to use ADRIA.","category":"page"},{"location":"development/docker/#A-note-about-platform-build-targets","page":"ADRIA Docker Setup","title":"A note about platform build targets","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This line in the Dockerfile prompts Julia to precompile the ADRIA package and it's predependencies for a larger range of target platforms. Given that the building of the image could occur on any host, we need to specify a range of platforms so that precompilation (which is CPU architecture dependent) does not need to reoccur when the Docker image is run on the user's system.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The below list came from here and is confirmed to work for a x86_64 based architecture.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# Try to coerce Julia to build across multiple targets\nENV JULIA_CPU_TARGET=x86_64;haswell;skylake;skylake-avx512;tigerlake","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"If more platforms are needing to be targeted, please lodge a pull request with the output of uname -m and other details, and we can expand this list of target platforms.","category":"page"},{"location":"development/docker/#Published-base-images","page":"ADRIA Docker Setup","title":"Published base images","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This repository uses GitHub actions to publish, upon version release, the adria-base image - see .github/workflows/PublishDockerImage.yml. The below commands such as running and using the ADRIA base image apply to these published images, replacing your locally tagged image with the GitHub Container Registry label e.g. the following will run in an interactive Julia shell, a precompiled terminal with ADRIA installed, ready to be used.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"docker run --tty --interactive ghcr.io/open-aims/adria.jl/adria-base:latest","category":"page"},{"location":"development/docker/#Building-adria-base","page":"ADRIA Docker Setup","title":"Building adria-base","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose build adria-base\n\n# OR using just `docker build`:\ndocker build --target \"adria-base\" --tag ADRIA.jl/adria-base:latest .","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"You can also opt to specify some custom build arguments to change the versions of Julia or ADRIA.jl that get installed. Supported arguments are:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"ADRIA_REPO: URL for the repository that ADRIA.jl should be cloned from. Defaults to https://github.com/open-AIMS/ADRIA.jl.git\nADRIA_REFSPEC: the branch-name or tag of the ADRIA_REPO that you want to install. Defaults to main.\nJULIA_VERSION: The version of the Julia platform you want to install ADRIA.jl into. This must be one of the versions available for the official Julia base image. Defaults to 1.10.1.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"See the docker-compose.yaml file for an example of how to specify build arguments in docker compose.","category":"page"},{"location":"development/docker/#Running-adria-base-with-a-non-interactive-Julia-command","page":"ADRIA Docker Setup","title":"Running adria-base with a non-interactive Julia command","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"e.g. to list the packages installed in the @adria shared environment:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-base --project=@adria -e 'using Pkg; Pkg.status()'\n\n# OR using just docker run:\ndocker run --rm ADRIA.jl/adria-base:latest --project=@adria -e 'using Pkg; Pkg.status()'","category":"page"},{"location":"development/docker/#Running-adria-base-as-an-interactive-Julia-shell","page":"ADRIA Docker Setup","title":"Running adria-base as an interactive Julia shell","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"To launch an interactive Julia shell:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-base\n\n# OR using just docker run:\ndocker run --rm --interactive --tty ADRIA.jl/adria-base:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In both cases, type CTRL-d to exit the shell and stop the container.","category":"page"},{"location":"development/docker/#Running-adria-base-with-a-non-Julia-entrypoint","page":"ADRIA Docker Setup","title":"Running adria-base with a non-Julia entrypoint","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"If you want to use this image to run something other than a Julia command, you can specify an alternate entrypoint at runtime as well as an alternate command. e.g. to launch an interactive bash shell in the container for checking filesystem permissions or similar:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm --entrypoint /bin/bash adria-base\n\n# OR using just docker run:\ndocker run --rm --interactive --tty --entrypoint /bin/bash ADRIA.jl/adria-base:latest","category":"page"},{"location":"development/docker/#Deriving-an-image-from-adria-base","page":"ADRIA Docker Setup","title":"Deriving an image from adria-base","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"To make a derived ADRIA application:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"Use FROM ADRIA.jl/adria-base:latest (or a related tag)\nInclude a CMD line in your Dockerfile that provides appropriate arguments to the julia command line to invoke your application.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The section of the Dockerfile that defines the adria-sandbox target described below might be useful inspiration.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#adria-dev","page":"ADRIA Docker Setup","title":"adria-dev","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-dev image variant is an alternative to the adria-base image, not a derived application. Instead of installing ADRIA.jl as a normal package, it looks for the ADRIA.jl source code in a local subdirectory, and installs that as a Julia development package.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This allows you to use the adria-dev container as an ADRIA.jl development environment: you can run tests, bind-mount and edit the code, re-resolve dependencies and all sorts of other useful things without needing to a native installation of Julia.","category":"page"},{"location":"development/docker/#Building-adria-dev","page":"ADRIA Docker Setup","title":"Building adria-dev","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"From within the root of the ADRIA.jl project, you can build the adria-dev image like so:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose build adria-dev\n\n# OR using just `docker build`:\ndocker build --target \"adria-dev\" --tag ADRIA.jl/adria-dev:latest .","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The same JULIA_VERSION build argument that works with adria-base will also work with adria-dev.","category":"page"},{"location":"development/docker/#Running-adria-dev-as-an-interactive-Julia-shell","page":"ADRIA Docker Setup","title":"Running adria-dev as an interactive Julia shell","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"Very useful for running commands to update Package manifests and similar! The command will activate the shared @adria environment by default, but you can switch to any other environment as you need to.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-dev\n\n# OR using just docker run:\ndocker run --rm --interactive --tty \\\n --mount type=bind,source=\"$(pwd)\"/ADRIA.jl/,target=/usr/local/src/adria/\n ADRIA.jl/adria-dev:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In both cases, type CTRL-d to exit the shell and stop the container.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#Running-ADRIA-tests-with-adria-dev","page":"ADRIA Docker Setup","title":"Running ADRIA tests with adria-dev","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"ADRIA tests can be run like any other Julia command, but the GOTCHA is that they need to run in the local project environment, NOT in the shared @adria environment:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-dev --project=. -e 'using Pkg; Pkg.test();'\n\n# OR using just docker run:\ndocker run --rm ADRIA.jl/adria-dev:latest --project=. -e 'using Pkg; Pkg.test();'","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This method of running tests is suitable to use in a containerised continuous integration pipeline.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#adria-sandbox","page":"ADRIA Docker Setup","title":"adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-sandbox image variant is set up to run the sandbox Julia application which has its source code in this repository.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This application uses the pre-installed ADRIA package, and can be built on either of adria-base or adria-dev, depending on whether you want the development version of the package or not.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"It depends on input and output data files which must be provided at runtime.","category":"page"},{"location":"development/docker/#Building-adria-sandbox","page":"ADRIA Docker Setup","title":"Building adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The sandbox build supports an optional SANDBOX_FROM build argument which is used to specify a base image. Supported values are adria-dev (the default) or adria-base.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose (edit the compose file to specify which base image to use):\ndocker compose build adria-sandbox\n\n# OR using just `docker build`:\ndocker build --build-arg SANDBOX_FROM=adria-dev --target \"adria-sandbox\" --tag ADRIA.jl/adria-sandbox:latest .","category":"page"},{"location":"development/docker/#Running-adria-sandbox","page":"ADRIA Docker Setup","title":"Running adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-sandbox image is configured to automatically run the dev.jl script when a container made from that image runs.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"For that script to be useful, though, you must first mount two filesystem locations to the container:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"A directory containing your input data files should be mounted at /data/input\nA directory where the sandbox application can create output files should be mounted at /data/output","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This documentation and the docker-compose.yaml file in the repository demonstrate using bind mounts to data-directories which are local to your current working directory for this purpose, but docker volumes with any supported storage driver should also work fine.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose (which has the bind-mounts predefined):\ndocker compose up adria-sandbox\n\n# OR using docker run:\ndocker run --rm \\\n --mount type=bind,source=\"$(pwd)\"/input,target=/data/input \\\n --mount type=bind,source=\"$(pwd)\"/output,target=/data/output \\\n ADRIA.jl/adria-sandbox:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The dev.jl script should run with any files you have provided in your input volume, and will create and output files in your output volume. The container will be removed once the script completes.","category":"page"},{"location":"development/docker/#Interacting-with-adria-sandbox","page":"ADRIA Docker Setup","title":"Interacting with adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"If you prefer to work with the sandbox code from an interactive shell, then you will need to override the default entrypoint and command combination to make the container launch your preferred shell at startup.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In this case, you may also like to bind-mount your sandbox and/or ADRIA.jl source code into the container, so that you can edit it without having to re-build the container each time.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"e.g. to launch the sandbox container as a development environment with an interactive bash shell and use:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm --entrypoint /bin/bash adria-sandbox\n\n# OR using just docker run:\ndocker run --rm --interactive --tty --entrypoint /bin/bash \\\n --mount type=bind,source=\"$(pwd)\"/input,target=/data/input \\\n --mount type=bind,source=\"$(pwd)\"/output,target=/data/output \\\n --mount type=bind,source=\"$(pwd)\"/sandbox,target=/opt/adria-sandbox/src \\\n --mount type=bind,source=\"$(pwd)\"/ADRIA.jl,target=/usr/local/src/adria \\\n ADRIA.jl/adria-sandbox:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In both cases, the initial working directory will be the installation-location for the sandbox application's source code, and you can invoke any command you like from that shell prompt, e.g:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"julia --project=@. dev.jl","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"Warning: For julia commands, you will probably need to use the --project=@. argument. This tells Julia that it's working environment is based in a parent directory of the one the sandbox source code is installed to, which is where the build configured all the precompiled dependencies. If you omit this, the pre-installed packages may not all be available.","category":"page"},{"location":"synopsis/#Synopsis","page":"Synopsis","title":"Synopsis","text":"","category":"section"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"Climate change is transforming coral reefs. Continued climate change has scope to erode reef biodiversity, key ecosystem functions, and the ecosystem services they provide for people. Conventional management strategies remain essential but will not be sufficient on their own to sustain coral reefs in a warming and acidifying ocean. New interventions are increasingly being considered, including assisted gene flow, cooling and shading, and reef structures that provide reef habitats and substrates for enhanced recruitment.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"Deciding where, when, and how to intervene – if at all - using new reef restoration and adaptation measures is challenging on at least three fronts.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"are new interventions likely to create more benefits than damage? And if so, whom do they benefit, or pose risks to, and at what spatial and temporal scales?\nwhich interventions, individually and in combination, represent solutions that provide the highest return on investment for reef, people, and industries?\nwhich R&D paths and deployment strategies represent optimal solutions given multiple key objectives, trade-offs, and limited time, resources, and logistical constraints?","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"To help reef modellers, decision-support teams and reef managers address these questions, AIMS has developed the Adaptive, Dynamic Reef Intervention Algorithm (ADRIA). In short, ADRIA simulates a reef decision maker operating inside the dynamic state space of a coral reef.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"For reef managers, ADRIA help provide line of sight to conservation solutions in complex settings where multiple objectives need to be considered. For investors, ADRIA helps analysts identify which options (R&D and/or deployment solutions) might have the highest likelihood of providing ecological and social returns on investment across a range of considered environmental conditions. While ADRIA’s key function is as a decision-support tool for intervention deployment, it uses a simple proxy model for reef coral dynamics, consisting of vital rates parameterised in a set of linked differential equations for four coral groups. The growth, mortality and recruitment of those four coral groups are further parameterised by environmental drivers and by different restoration and adaptation interventions.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"The primary purpose of ADRIA is to help guide intervention deployment such that net benefits are maximised against primary objectives and minimised against costs. Solutions can be tuned (eventually optimised) via heuristics that control the selection of sites and/or reefs and the prioritisation of species, ecosystem services or benefits that favour what people (society) want. The key benefits considered in ADRIA are consistent with a triple-bottom-line approach, i.e.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"ecological (e.g. biodiversity),\neconomic (e.g. tourism and fisheries values) and\nsocial and cultural (e.g. recreation and supporting identities).","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"The guiding principles for decision support in ADRIA are currently a set of dynamic Multi-Criteria Decision Analyses (dMCDA) applied at each time step. Criteria in the model are a composite of spatial environmental variables (risk from wave damage, thermal stress, and water quality) and ecological information (coral cover, substrate availability).","category":"page"},{"location":"development/development_setup/#Development-setup","page":"Development setup","title":"Development setup","text":"","category":"section"},{"location":"development/development_setup/#Install-Julia","page":"Development setup","title":"Install Julia","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Install Julia if not already done so, preferably using juliaup.","category":"page"},{"location":"development/development_setup/#Windows","page":"Development setup","title":"Windows","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"There may be issues installing juliaup from the Windows Store (or otherwise undesirable). In such cases, use the alternate MSIX App installer (https://install.julialang.org/Julia.appinstaller)","category":"page"},{"location":"development/development_setup/#Recommendations","page":"Development setup","title":"Recommendations","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"It is recommended that the juliaup tool be used to ease managing Julia versions.\nWe recommend VS Code with its Julia extension when developing ADRIA.\nInstall the VS Code Julia Formatter extension (note: not the JuliaFormatter.jl package).\nWe also recommend the built-in Julia REPL within VS Code be used (see the notes below).","category":"page"},{"location":"development/development_setup/#Initial-Setup","page":"Development setup","title":"Initial Setup","text":"","category":"section"},{"location":"development/development_setup/#Using-the-console","page":"Development setup","title":"Using the console","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Once Julia is installed, clone the ADRIA.jl repository and navigate to the project folder:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ git clone git@github.com:open-AIMS/ADRIA.jl.git\n$ cd ./ADRIA.jl","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Start Julia specifying the current directory as the project environment:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ julia --project=.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Switch to the package manager (]) and instantiate the project. This only needs to be done once.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"julia> ]\n(ADRIA.jl) pkg> instantiate","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"This will sets up the project packages.","category":"page"},{"location":"development/development_setup/#Sandbox","page":"Development setup","title":"Sandbox","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"For development purposes, set up a sandbox environment (setup only needs to be done once). This environment will function as a project apart from ADRIA, where you can install any packages, including ADRIA.jl, and run your code. When installing ADRIA.jl at the sandbox, use the dev command instead of add. For more information, please refer to Pkg.jl documentation.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Once you are inside ADRIA.jl project folder, create a folder named sandbox and start julia inside it:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ mkdir sandbox\n$ cd sandbox\n$ julia --project=.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Switch to the package manager (]) and add ADRIA.jl as a local package under development","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"julia> ]\n(sandbox) pkg> dev ../","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"You may also install additional packages for visualizations and debugging tools","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"(sandbox) pkg> add GLMakie GeoMakie GraphMakie\n(sandbox) pkg> add Revise Infiltrator BenchmarkTools JET","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Press backspace or Ctrl+C to leave the package manager.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Development scripts/functions can now be worked on in the sandbox folder, and its sub-folders, without these polluting the ADRIA project itself.","category":"page"},{"location":"development/development_setup/#Testing","page":"Development setup","title":"Testing","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"To run the full test suite, rebuilding the environment as necessary:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ julia --project=.\njulia> ]test","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Rebuilding the environment can be unnecessary for every test run during development. It such cases, include() the runtests.jl file directly.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"# Assuming the current working directory is the project root.\n# Adjust the filepath as necessary if this is not the case.\ninclude(\"test/runtests.jl\")","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If a specific test case is being run, write the test file to be a standalone script (importing all necessary packages, including Test) and run it directly.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Doing so allows use of debugging packages if necessary.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"include(\"test/some_test_file.jl\")","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Once the test is complete, put the tests in a testset as and if required. If a new file is added to the test suite, include() it in test/runtests.jl","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"See the Test documentation for further details.","category":"page"},{"location":"development/development_setup/#Code-Style","page":"Development setup","title":"Code Style","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"We are currently moving to follow Blue Style Guide. All PRs should follow this style guide. The julia-format GitHub workflow will check that your PR's code is formatted. Note that this check requires all code in the repo to be formatted, not only the files modified by your PR.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Use the VSCode Format Document or Format Selection actions to format your code.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"To reformat the entire project:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"using JuliaFormatter\nformat(\".\")","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If this returns false, call format() again.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Formatter configuration is defined in .JuliaFormatter.toml, see JuliaFormatter docs.","category":"page"},{"location":"development/development_setup/#VSCode-Settings","page":"Development setup","title":"VSCode Settings","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Open Settings (Ctrl+,). Search for trim and ensure the following options are all ticked/enabled:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Files: Trim Final Newlines\nFiles: Trim Trailing Whitespace\nEditor: Trim Auto Whitespace","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"An optional, but recommended, step would be to add a ruler guide to indicate where the character limit/width is.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Search for rulers and click on \"Edit in settings.json\" under \"Editor: Rulers\"","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Add \"92\" to the list of ruler lengths, such that the editor.rulers entry looks like this:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"\"editor.rulers\": [\n 92\n ]","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Adding multiple values adds more guide lines at the indicated widths.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Important: if you installed the oh7z Julia Formatter VSCode extension, uninstall or disable it for this workspace. That extension always uses its formatter settings and does not support .JuliaFormatter.toml whereas the main Julia extension does. The only reason to use the oh7z extension is for Julia projects that do not have a .JuliaFormatter.toml file.","category":"page"},{"location":"development/development_setup/#Git-blame-ignore-revs","page":"Development setup","title":"Git blame ignore revs","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If you have GitLens (or similar extension), it will show the author of a line of code using git blame. To ignore commits like \"re-format entire project\", run this once:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"git config --local blame.ignoreRevsFile .git-blame-ignore-revs","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If you reformat code and want to ignore that commit, simply add the commit SHA to the .git-blame-ignore-revs file.","category":"page"},{"location":"development/development_setup/#Notes","page":"Development setup","title":"Notes","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"The very first import of the ADRIA package will be very slow as it attempts to precompile common functions to reduce later start up time. The same applies when running ADRIA for the first time. This slow initial precompilation has to be repeated if the package is modified, but will remain \"fast\" if no changes are made.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Use the Revise package to avoid having to repeatedly restart the REPL to incorporate code changes. By default, the VS Code REPL will auto-load this package.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"A custom sysimage can also be created to reduce start up times.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"VS Code now has (experimental) support for generating a custom sysimage for its REPL. Prior to Julia v1.9, a custom sysimage for the development/sandbox environment was highly recommended. Julia v1.9 introduced an improved precompilation process and the concept of extension packages. As many packages are still in the process of taking advantage of these changes, the sysimage may not successfully build. Given precompilation is now much faster than previously, the sysimage can be considered to be a \"nice to have\".","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"The same caveats as above apply: the sysimage has to be recreated if the project specification (e.g., expected package dependencies) changes.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"See: This guide","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Otherwise, if the VS Code build task cannot be used, see the documentation here for a quick how to. Note: compilation time to create a sysimage can be upwards of 15mins and, again, has to be repeated if the project packages are updated.","category":"page"},{"location":"usage/cookbook/#Cookbook-examples","page":"Cookbook examples","title":"Cookbook examples","text":"","category":"section"},{"location":"usage/cookbook/#Extracting-model-details","page":"Cookbook examples","title":"Extracting model details","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"Example showcasing how to extract model details, such as:","category":"page"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"the model parameter table\nmodel specification","category":"page"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"and more specific information/data from the above.","category":"page"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using DataFrames\nusing ADRIA\n\n\n# Loading a dataset for a study area (a \"domain\")\ndata_pkg = \"./Example_domain\"\ndom = ADRIA.load_domain(data_pkg, 45)\n\n# Get current parameter table (fieldnames and their values)\nparam_df = ADRIA.param_table(dom)\n\n# Get model specification with lower/upper bounds separated\nmodel_spec = ADRIA.model_spec(dom)\n\n# Export model specification to CSV\nADRIA.model_spec(dom, \"model_spec.csv\")\n\n\n# Get parameter details\n\n## Parameter names\np_names = dom.model[:fieldname]\n\n## Current values\np_vals = dom.model[:val]\n\n## ADRIA parameter types\np_types = dom.model[:ptype]\n\n## Parameter bounds (for e.g., to pass into a sampler or optimizer)\n## Note: ADRIA integer parameter bounds are set such that ℓ ≤ x ≤ u+1,\n## where ℓ is the lower bound and u is the upper bound.\n## This is because `floor(x)` is assigned with `update_params!()`.\n## Instances where ℓ := x := u indicate uncertain parameters that\n## are nevertheless assumed to be constant.\np_bounds = dom.model[:bounds]\n\n## Component groups\np_groups = dom.model[:component]\n\n## All of above as a DataFrame\nmodel_spec = DataFrame(dom.model)\n\n\n# Get DataFrame of parameter information for a specific sub-component (Intervention, Criteria, Coral)\nADRIA.component_params(dom.model, Intervention)","category":"page"},{"location":"usage/cookbook/#Generating-and-running-scenarios","page":"Cookbook examples","title":"Generating and running scenarios","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using ADRIA\n\n\n# Loading data package\ndom = ADRIA.load_domain(\"Example_domain\")\n\n# Creating 128 scenarios based on parameter bounds using the Sobol' method\nscens = ADRIA.sample(dom, 128)\n\n# Can also use other samplers\n# using Surrogates.QuasiMonteCarlo\n# scens = ADRIA.sample(dom, 100, LatinHypercubeSample())\n\n# Can also sample counterfactuals (scenarios with no interventions)\n# or scenarios with guided interventions only\n# s = ADRIA.sample_cf(dom, 32)\n# s = ADRIA.sample_guided(dom, 32)\n\n# Can also load previously generated scenarios\n# p_df = ADRIA.load_scenarios(dom, joinpath(here, \"example_scenarios.csv\"))\n\n# Batch run scenarios. Returns a ResultSet.\n# Setting up and running scenarios\nrs = ADRIA.run_scenarios(dom, p_df, \"45\")\n\n# Multiple RCPs can be specified, so long as RCP-specific data is available.\n# rs = ADRIA.run_scenarios(dom, p_df, [\"45\", \"60\"])\n\n# Single scenario run (returns NamedTuple of results for a single environmental/intervention scenario).\n# See documentation for more detail.\n# scenario_id = 1\n# result = ADRIA.run_scenario(domain::Domain, scenario_id, param_df::DataFrameRow)\n\n# switch_RCPs!(domain, \"45\")\n# res1 = ADRIA.run_scenario(domain, scens[1, :])\n# res2 = ADRIA.run_scenario(domain, scens[2, :])\n# res3 = ADRIA.run_scenario(domain, scens[3, :], \"60\") # run for a different RCP\n\n# The location of the outputs stored on disk\n@info ADRIA.store_name(rs)\n# \"Example_domain__RCPs45__2022-10-19_12_01_26_965\"\n\n@info ADRIA.result_location(rs)\n# \"[some location]/Example_domain__RCPs45__2022-10-19_12_01_26_965\"\n\n# Can also load results using a path to the stored result set.\n# rs = ADRIA.load_results(\"path to result set\")\n\n# Specific metrics found in the `metrics` submodule.\n# tac = ADRIA.metrics.total_absolute_cover(rs)","category":"page"},{"location":"usage/cookbook/#Intervention-location-selection","page":"Cookbook examples","title":"Intervention location selection","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using ADRIA\nusing ADRIA: rank_locations\n\n\ndom = ADRIA.load_domain(\"path to domain\", \"45\")\nscens = ADRIA.sample_site_selection(dom, 8)\n\n# Area of seeded corals in m^2\narea_to_seed = 962.11\n\n# Initial coral cover matching number of criteria samples (size = (no. criteria scens, no. of sites)).\nsum_cover = repeat(sum(dom.init_coral_cover; dims=1), size(scens, 1))\n\n# Use rank_locations to get ranks\nranks = rank_locations(dom, scens, sum_cover, area_to_seed)","category":"page"},{"location":"usage/cookbook/#Intervention-location-selection-summary-functions","page":"Cookbook examples","title":"Intervention location selection - summary functions","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using ADRIA\nusing ADRIA:\n rank_locations,\n ranks_to_frequencies,\n location_selection_frequencies,\n selection_score\nusing DataFrames\nusing Statistics, StatsBase\n\n# Load data package\ndom = ADRIA.load_domain(\"path to Domain files\", \"RCP\")\n\n# Select locations for interventions without any model runs\nscens = ADRIA.sample_site_selection(dom, 8) # Get site selection scenario dataframe.\n\n# Area of seeded corals in m^2\narea_to_seed = 962.11\n\n# Initial coral cover matching number of criteria samples\nsum_cover = repeat(sum(dom.init_coral_cover; dims=1), size(scens, 1))\n\n# Use rank_locations to get ranks\nranks = rank_locations(dom, scens, sum_cover, area_to_seed)\n\n# Get frequencies with which each site is selected for each rank for set of stand alone\n# location selections\nrank_freq = ranks_to_frequencies(ranks[intervention=1])\n\n# Calculate rank aggregations\n# Get location selection freqencies for set of standalone location selections\nlocation_selection_frequency = location_selection_frequencies(ranks[intervention=1])\n\n# Get summed inverse rank for set of standalone location selections\n# Measure of magnitude and frequency of high rank\nsel_score = selection_score(ranks[intervention=1])\n\n# Use aggregation function within rank_locations to get direct output\n# To get rank frequencies:\nrank_frequencies_seed = rank_locations(\n dom, scens, sum_cover, area_to_seed, ranks_to_frequencies, 1\n)\nrank_frequencies_seed = rank_locations(\n dom, scens, sum_cover, area_to_seed, location_selection_frequencies, 1\n)\nrank_frequencies_seed = rank_locations(\n dom, scens, sum_cover, area_to_seed, selection_score, 1\n)\n\n# Example using ADRIA runs\nscens = ADRIA.sample(dom, 8)\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# Get frequencies with which each site was selected for each rank for a set of runs\nrank_freq = ranks_to_frequencies(rs.ranks[intervention=1]) # with timesteps not aggregated\n\n# With timesteps aggregated\nrank_freq = ranks_to_frequencies(\n rs.ranks[intervention=1];\n agg_func=x -> dropdims(sum(x; dims=:timesteps); dims=:timesteps),\n)\n\n# Get selection frequencies for set of runs\nselection_freq = location_selection_frequencies(rs.ranks[intervention=1])\n\n# Get selection frequencies over time for unguided runs only\nunguided_freq = location_selection_frequencies(\n rs.seed_log[scenarios=findall(scens.guided .>= 1)]\n)\n\n# Get selection score for set of runs\n# Measure of magnitude and frequency of high rank\nsel_score = selection_score(rs.ranks[intervention=1])\n\n# Get selection score for locations over time\nsel_score = selection_score(rs.ranks[intervention=1]; dims=[:scenarios])","category":"page"},{"location":"architecture/architecture/#Architectural-overview","page":"Architectural overview","title":"Architectural overview","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"ADRIA consists of three overarching components:","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"a set of Multi-Criteria Decision Analysis methods used to emulate decision-makers\na coral ecosystem model (referred to as ADRIAmod)\na suite of analysis and assessment methods","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Each component may be applied separately, or altogether to perform an end-to-end analysis. This page documents the underlying architectural implementation of ADRIA, detailing how the above components interact.","category":"page"},{"location":"architecture/architecture/#General-Structure","page":"Architectural overview","title":"General Structure","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"The primary purpose of ADRIA is to support reef restoration and adaptation through the development of robust intervention strategies under deep uncertainty. Here, \"robustness\" refers to the ability of an intervention strategy to meet desired outcomes under uncertain future conditions, which themselves are unknown and may be unexpected. To do so, ADRIA adopts an Exploratory Scenario Modelling framework to explore the range of possible futures and their outcomes.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Exploratory Scenario Modelling (ESM) itself leverages uncertainty and sensitivity analysis (UA/SA). Uncertainty analysis quantifies the variability of uncertainties in a given system and its expected range of outcomes. Sensitivity analysis examines the effect of a change in a model's inputs to its outputs. Common workflows to such analyses involve a three-step process (as discussed in Pianosi et al., 2016):","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Input sampling\nModel evaluation\nPost-processing","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"When ADRIA is applied in its entirety, \"input sampling\" is analogous to scenario generation: all model factors (the inputs) are collated and are sampled through a quasi-monte carlo process. The Sobol' sampling method is adopted as the default, although any method provided by the QuasiMonteCarlo.jl package can be used. Sample adjustment is required to map sampled values (which are continuous) to categorical or whole number values (e.g., Baroni and Tarantola, 2014) as may be expected by some factors. Values are also adjusted to avoid implausible factor combinations, such as active intervention factors in the case of non-intervention scenarios.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Model evaluation is simply running the model with the generated scenario set.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Post-processing is the analysis and visualization step.","category":"page"},{"location":"architecture/architecture/#Model-Factors","page":"Architectural overview","title":"Model Factors","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Factors in ADRIA are defined across four sub-components:","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Intervention\nCriteriaWeights\nEnvironmentalLayer\nCoral","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Each sub-component is represented by a struct with fields for each parameter. The Intervention sub-component holds parameters that define a given adopted intervention strategy/option: how many (and type of) corals are to be seeded, the length of any deployment, the start/end years, and so on. The CriteriaWeights sub-component relates to the preferences for the Multi-Criteria Decision Analysis methods, further detailed in Dynamic Multi-Criteria Decision Analysis. For the ADRIA ecosystem model (ADRIAmod), EnviromentalLayer relate to the environmental scenarios available for a given simulation (a time series of DHW and Wave stress), itself determined on the loading of data (see Running scenarios).","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"The Coral sub-component relates to ADRIAmod, currently representing six coral species:","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Arborescent Acropora\nTabular Acropora\nCorymbose Acropora\nCorymbose non-Acropora\nSmall massives and encrusting\nLarge massives","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"ADRIAmod represents these across six size classes, with six parameter sets for each coral species and size class. These six parameter sets are further detailed in Model Factors, however, it results in a large number of unique factors (6 groups x 6 size classes x 6 parameters: 216 factors). Instead of specifying all coral factors by hand, ADRIA instead auto-generates the sub-component using a common template (see coral_spec() and create_coral_struct() in General API). Through discussion with expert stakeholders, factor bounds were set to +/- 10% of their default values following a triangular distribution, the peak of which is the default value.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"The ModelParameters.jl package is used to provide a simple table-like interface to model factors. ADRIA provides a wrapper to the Param type provided by ModelParameters.jl called a Factor. These Factors requires ADRIA-specific metadata to be provided alongside the default value for a given model factor. These include the assumed distribution of the factor, distribution factors (principally the lower and upper bounds), and a human-readable name and description. An example from the Intervention sub-component is shown below.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"guided::N = Factor(0.0, ptype=\"ordered categorical\", dist=(-1.0, 3.0), dist_params=DiscreteUniform,\n name=\"Guided\", description=\"Choice of MCDA approach.\")","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Note that factor values are provided as floats - even where discrete values are expected - to maintain type stability. Mixing floats with integers will lead to an error. Similarly, values used to update the model should always be floats.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Combinations of the realized factor values then represent a \"scenario\".","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"note: Parameter Collation and Scenario Generation\nSee Cookbook examples for an example how-to on collating model factors and generating samples.","category":"page"},{"location":"architecture/architecture/#References","page":"Architectural overview","title":"References","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"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.","category":"page"},{"location":"development/release_guide/#Release-Guide","page":"Release Guide","title":"Release Guide","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"All releases are done on main.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Note: version numbers should follow Semantic Versioning.","category":"page"},{"location":"development/release_guide/#Public-\"Final\"-Releases","page":"Release Guide","title":"Public \"Final\" Releases","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Increase the version number (manually) following SemVer in the Project.toml file\nUpdate environment and run tests locally to ensure all pass. Testing\nSubmit a PR with the updated version number. Wait for approval.\nOnce approved, go to the releases page and click the \"Draft a new release\" button at the top right\nUnder \"Choose a tag\" on the left, enter the new version number (e.g., \"v0.99.0\") and then select \"Create new tag: on publish\"\nAt the top-right of the textbox, select the last full release then click the \"Generate release notes\" button (at the top-right of the textbox).\nUnder \"What's Changed\" add a short description of the major changes. Explicitly note any major breaking changes (i.e., anything that results obtained with previous versions of ADRIA incompatible) Copy the release notes (for step 8). Click \"Publish release\".\nRegister the updated package by opening a new issue with the title \"Register [version number]\" e.g., Register v1.0\nState in the comment: @JuliaRegistrator register Paste in the generated text from step 6 (an example is shown below)\nSubmit the issue. The JuliaRegistrator bot should take care of the rest.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"@JuliaRegistrator register\n\nRelease notes:\n\nPaste the generated release notes here.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"See Julia Registrator usage notes here for more details.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"note: Issues can block release\nThe JuliaRegistrator bot submits a corresponding Pull Request with the Julia package registry. Registration may be blocked for a number of reasons. Keep an eye on the auto-submitted Pull Request and resolve any issues reported there. Otherwise the package version will never be released.","category":"page"},{"location":"development/release_guide/#Development-Release","page":"Release Guide","title":"Development Release","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Development releases provide users with the most recent \"working\" version of ADRIA and may still have some known bugs. It provides users a chance to try new features and/or provide feedback before a public release.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Deploying a Development Release follows the same steps as \"Public\" releases, except:","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Add \"-dev.x\" to the version number. e.g., v1.2.3-dev.1; v1.2.3-dev.2 for the second development release, etc.\nUntick \"Set as the latest release\" and tick the \"Set as a pre-release\" option.\nIgnore Step 8 through 10; DO NOT trigger the JuliaRegistrator bot.","category":"page"},{"location":"development/release_guide/#Release-Candidates","page":"Release Guide","title":"Release Candidates","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Release candidates are releases that are not yet \"final\" but are close to it. Release candidates provide a \"last chance\" opportunity for users to report bugs prior to a \"final\" release.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Deploying a Release Candidate follows the same steps as \"Public\" releases, except:","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Add \"-rc.x\" to the version number. e.g., v1.2.3-rc.1; v1.2.3-rc.2 for the second release candidate, etc.\nUntick \"Set as the latest release\" and tick the \"Set as a pre-release\" option.\nIgnore Step 8 through 10; DO NOT trigger the JuliaRegistrator bot.","category":"page"},{"location":"usage/scenario_generation/#Generating-scenarios","page":"Generating scenarios","title":"Generating scenarios","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Typical use of ADRIA is to generate a number of scenarios by sampling from combinations of possible factors relating to environmental, intervention, and coral conditions.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"A scenario is defined as a combination of all factors (i.e., all the model inputs).","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"# Load domain before generating scenarios\ndom = ADRIA.load_domain(\"path to domain data package\")\n\n# Generate 128 scenarios based on available environmental data layers and model parameters\nscens = ADRIA.sample(dom, 128)","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Here, the scens variable holds a DataFrame of scenarios of shape N by D, where N is the number of scenarios (rows) and D is the number of factors (columns). Because it is a DataFrame, it can be modified after the fact.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"The Sobol' method (Sobol' 1993, 2001) with Owen Scrambling is the default sampling approach. The Sobol' sampling method is a deterministic low-discrepancy quasi-monte carlo method. Samples are described as having low discrepancy if the samples are equi-distributed, and thus guarantee an even exploration of factor space. Owen Scrambling is an approach to introduce randomness to the quasi-monte carlo sequence, and belong to a class of sampling methods known as randomized Quasi-Monte Carlo (rQMC). rQMC approaches offer a balance between good space-filling properties and associated exploration of factor space with improved convergence characteristics.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"One limitation of the Sobol' method is that all factors are assumed to be independent. For most factors represented in ADRIA, this assumption holds true. Specific factors relating to intervention options may conditionally co-vary however, and this dependency is introduced by adjusting the sample values a posteriori to restrict sampled values to their plausible combinations, and to map continuous values to their expected discrete factor values (where necessary), as is in the case with categorical factors. The Sobol' scheme is therefore disrupted due to the adjustment and so a Sobol' sensitivity analysis may exhibit comparatively poor convergence. Subsequent assessment of uncertainty and sensitivity is instead conducted with the distribution-based PAWN method (Pianosi and Wagener 2015, 2018).","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"note: Sobol' samples\nThe convergence properties of the Sobol' sequence is only valid if the number of samples is a power of 2.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Samples for factors with non-uniform distributions are transformed to their indicated distributions using the Inverse Cumulative Distribution Function method.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Although the Sobol' method is the default, any sampler supported by the Surrogates.jl package may be used. Below is an example using Latin Hypercube sampling.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"import Surrogates.QuasiMonteCarlo: LatinHypercubeSample\n\nscens = ADRIA.sample(dom, 100, LatinHypercubeSample())","category":"page"},{"location":"usage/scenario_generation/#On-model-parameters-and-specifications","page":"Generating scenarios","title":"On model parameters and specifications","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"The current default values can be extracted with:","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"params = ADRIA.param_table(dom)","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Again, params is a DataFrame of a single row and D factors: A single scenario with model factors set to their default values.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Running specific user-defined scenarios is as simple as modifying the DataFrame (referred to as the \"scenario specification\"). A set of scenarios may be specified simply by extending the number of rows of the DataFrame. Details of the ADRIA model - parameter names, the default values, and their bounds - can be extracted as well.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"# Get model specification\nmodel_spec = ADRIA.model_spec(dom)\n\n# Sometimes it is useful to export the model specification to CSV\nADRIA.model_spec(dom, \"model_spec.csv\")","category":"page"},{"location":"usage/scenario_generation/#Constrained-sampling","page":"Generating scenarios","title":"Constrained sampling","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"At times, it is necessary to create samples while holding some model factors constant.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Although a scenario set could be modified to make specific factors constant, doing so runs the risk of creating (many) identical scenarios, thereby wasting computational effort. A more efficient approach is to modify the model specification itself to treat those factors as constants. These then get ignored for the purpose of scenario generation.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"dom = ADRIA.load_domain()\n\n# Could keep a copy of the original model parameters/bounds\n# to reset to later.\n# orig_spec = DataFrame(dom.model)\n\n# Make the assisted adaptation factor a constant\nADRIA.fix_factor!(dom, :a_adapt)\n\n# Set the assisted adaptation factor to a given constant value\nADRIA.fix_factor!(dom, :a_adapt, 3.0)\n\n# Pass in factor names and their constant values as named arguments\n# to fix a set of factors.\nADRIA.fix_factor!(dom;\n seed_TA=Int64(5e5),\n seed_CA=Int64(5e5),\n SRM=0.0, # Never shade\n fogging=0.0, # Never fog\n a_adapt=3.0, # only deploy +3 DHW enhanced corals\n seed_years=5,\n shade_years=0,\n seed_deployment_freq=0,\n seed_year_start=3,\n shade_year_start=3,\n coral_cover_tol=1.0\n)","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Samples can also be taken over a constrained range. For example, if one wanted to investigate only scenarios with high fogging and seeding, the following could be used:","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"dom = ADRIA.load_domain()\n\n# Adjust seeding bounds. Note only lower and upper bounds are needed because the factors in\n# question have a uniform distribution.\ndom = ADRIA.set_factor_bounds(dom, :N_seed_TA, (500000.0, 1000000.0))\ndom = ADRIA.set_factor_bounds(dom, :N_seed_CA, (500000.0, 1000000.0))\ndom = ADRIA.set_factor_bounds(dom, :N_seed_SA, (500000.0, 1000000.0))\n\n# Adjust fogging bounds. Note lower, upper and mode parameters are needed because it\n# is a triangular distribution.\ndom = ADRIA.set_factor_bounds(dom, :fogging, (0.2, 0.3, 0.1))\n\n# Adjust multiple factors simultaneously.\ndom = ADRIA.set_factor_bounds(dom;\n heat_stress=(0.3, 0.7),\n N_seed_TA=(500000.0, 1000000.0),\n N_seed_CA=(500000.0, 1000000.0))","category":"page"},{"location":"usage/scenario_generation/#Sampling-counterfactuals-only","page":"Generating scenarios","title":"Sampling counterfactuals only","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"A convenience function to create scenarios with no interventions (counterfactuals).","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"cf_scens = ADRIA.sample_cf(dom, 1024)","category":"page"},{"location":"usage/scenario_generation/#References","page":"Generating scenarios","title":"References","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Sobol’, I. M. 1993. Sensitivity analysis for non-linear mathematical models. Mathematical Modelling and Computational Experiment 1:407–414. [Translated from Russian, accessible at: https://www.mathnet.ru/php/archive.phtml?wshow=paper&jrnid=mm&paperid=2320&option_lang=eng]\nSobol′, I. M. 2001. Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation 55:271–280. https://doi.org/10.1016/S0378-4754(00)00270-6\nPianosi, F., and T. Wagener. 2015. A simple and efficient method for global sensitivity analysis based on cumulative distribution functions. Environmental Modelling & Software 67:1–11. https://dx.doi.org/10.1016/j.envsoft.2015.01.004\nPianosi, F., and T. Wagener. 2018. Distribution-based sensitivity analysis from a generic input-output sample. Environmental Modelling & Software 108:197–207. https://dx.doi.org/10.1016/j.envsoft.2018.07.019","category":"page"},{"location":"usage/domain/#Loading-a-Domain","page":"Loading a Domain","title":"Loading a Domain","text":"","category":"section"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"ADRIA is designed to work with Domain data packages.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"At their core, data packages are a directory containing a datapackage.json file, following the spec as outlined by Frictionless Data. In short, these are pre-packaged data sets that hold all the necessary data to run simulations for a given spatial domain.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"See Architectural overview for more information.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"A Domain may be loaded by calling the load_domain function with the path to the data package. Note that the data package is the directory.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"By convention we assign the Domain to dom, although this variable can be named anything.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"dom = ADRIA.load_domain(\"path to domain data package\")","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"ReefMod Engine datasets can also be used to run ADRIAmod simulations for the Great Barrier Reef.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"dom = ADRIA.load_domain(RMEDomain, \"path to ReefModEngine dataset\", \"45\")","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"Note that at the moment the target RCP has to be specified.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"ReefMod Matlab datasets that have been converted to NetCDF files can also be used to run ADRIAmod simulation for the Great Barrier Reef.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"dom = ADRIA.load_domain(ReefModDomain, \"path to ReefMod dataset\", \"45\")","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"The target RCP must also be specified.","category":"page"},{"location":"usage/scenario_runs/#Running-scenarios","page":"Running scenarios","title":"Running scenarios","text":"","category":"section"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"# Run sampled scenarios for a given RCP\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# ... or repeat scenario runs across multiple RCPs\nrs = ADRIA.run_scenarios(dom, scens, [\"45\", \"60\", \"85\"])\n\n# The location of the outputs stored on disk\n@info ADRIA.store_name(rs)\n# \"Example_domain__RCPs45__2022-10-19_12_01_26_965\"\n\n@info ADRIA.result_location(rs)\n# \"[some location]/Example_domain__RCPs45__2022-10-19_12_01_26_965\"","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"The rs variable is an ResultSet object which acts as an interface to the stored results.","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"The ResultSet provides:","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"An overview of scenarios run\nAccess to results from key ADRIA metrics\nSeeding/Shading/Fogging logs\ndomain spatial data","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"print(rs)","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"note: on-disk data store\nADRIA uses an on-disk data store (in Zarr format) to reduce memory use. The primary location for these is defined in the project's config.toml file (see instructions in Getting Started).","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"tip: Reloading results\nPre-existing results can also be reloaded by providing the path to the data store.rs = ADRIA.load_results(\"path to result set\")","category":"page"},{"location":"dMCDA/#Dynamic-Multi-Criteria-Decision-Analysis","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"","category":"section"},{"location":"dMCDA/#Multi-Criteria-Decision-Making","page":"Dynamic Multi-Criteria Decision Analysis","title":"Multi-Criteria Decision Making","text":"","category":"section"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"Multi-criteria decision analysis (MCDA) encompasses a series of methods for conducting decision making in a way that is formalised, structured and transparent. It evaluates the decision objective according to numerical measures of decision criteria assembled by the decision maker. Constructing explicit criteria over which to evaluate alternatives allows a transparent evaluation of benefits, negatives and trade-offs in coming to a decision solution.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"Typical approaches to MCDA require the construction of a \"decision matrix\", which takes the form of a X^n cdot m, where n is the number of alternate options available, and m is the number of criteria.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"In the context of ADRIA, the alternate options relate to the locations being assessed. The criteria then relate to the common set of attributes on which the locations are being judged, such as the projected heat stress (in terms of DHW), depth, and level of incoming or outgoing connectivity.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"MCDA methods provide a ranking according to the set of assessed criteria, in the form of:","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"r = g(X w d)","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"where:","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"g()\nrefers to a given MCDA algorithm (see JMcDM.jl).\nX\nis the decision matrix\nw\nis the weights afforded to each criteria, indicating their relative importance\nd\nis the desired directionality for each criterion (to minimize the criteria value, or to maximize)\nr\nis the ranking determined by g()","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"When applied in conjunction with scenario analyses, locations are assessed at each decision point.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"When conducting location selection, the analyses are applied to the initial conditions represented in the Domain.","category":"page"},{"location":"development/metrics/#Contributing-a-metric","page":"Contributing a metric","title":"Contributing a metric","text":"","category":"section"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"At a minimum, all metrics must define:","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"a \"private\" function (i.e., one that starts with an underscore: _) that performs the calculation with expected arguments\na \"private\" function that accepts a ResultSet as its first argument.\na \"public\" Metric function (i.e., no underscore) with some additional metadata","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"The Metric type allows metadata regarding the expected dimension names and unit of measure. Note that the unit of measure is optional and can be left out.","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"Below is the implementation of the total_absolute_cover metric.","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"function _total_absolute_cover(X::AbstractArray{<:Real}, loc_area::Vector{<:Real})::AbstractArray{<:Real}\n return dropdims(sum(X, dims=:species), dims=:species) .* loc_area'\nend\nfunction _total_absolute_cover(rs::ResultSet)::AbstractArray{<:Real}\n return rs.outcomes[:total_absolute_cover]\nend\ntotal_absolute_cover = Metric(_total_absolute_cover, (:timesteps, :sites, :scenarios), \"m²\")\n\n# Unit of measure is optional, in cases where the values are non-dimensional\n# some_example_metric = Metric(_some_example_metric, (:timesteps, :scenarios))","category":"page"},{"location":"architecture/domain_and_resultsets/#Inputs-and-Outputs","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"ADRIA seeks to use Data Packages to define a standard structure, format, and naming convention for its inputs and outputs. By definition, a Data Package is a directory holding the required data for ADRIA to run, or results from model runs.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Data specifications are outlined/stored in this repository: https://github.com/open-AIMS/ADRIA-data-specs","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The overall structure and data formats of the data packages are illustrated in the diagram below.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"(Image: Domain-Results Diagram)","category":"page"},{"location":"architecture/domain_and_resultsets/#Domain-data-package","page":"Inputs and Outputs","title":"Domain data package","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Prior to running the ADRIA coral ecosystem model, the first step (after importing the package) is to load domain data.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dom = ADRIA.load_domain(\"path to some domain\")","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"As the naming suggests, inputs are taken to represent a given spatial area, and so are referred to as a Domain.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The Domain data package consists of:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Connectivity (CSVs, grouped by year)\nDegree-Heating Week trajectories (in netCDF format; dimensions: timestep ⋅ location ⋅ projection)\nWave stress (as netCDFs; dimensions: timestep ⋅ location ⋅ projection)\nGeospatial data\na datapackage.json file with machine-readable metadata\na README.md file with human-readable content","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Geospatial data consists of:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"polygons defining individual reefs/sites in geopackage format\ninitial coral cover (as a netCDF; with dimensions: species/sizes ⋅ locations)","category":"page"},{"location":"architecture/domain_and_resultsets/#ReefMod-Datasets","page":"Inputs and Outputs","title":"ReefMod Datasets","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Datasets from containing inputs and outputs from ReefMod can be loaded for use with ADRIAmod. ADRIAmod requires geospatial data in geopackage format , a csv file containing location ids and reef connectivity data in addition to ReefMod Data.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dom = ADRIA.load_domain(ReefModDomain, \"path to ReefMod dataset\", \"45\")","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The expected directory structure is","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"ReefModDomain\n│ # ReefMod Data\n│ ReefMod_RCP19.nc\n│ ReefMod_RCP26.nc\n│ ReefMod_RCP45.nc\n│ ReefMod_RCP70.nc\n│ ReefMod_RCP85.nc\n│\n├───con_bin # Reef connectivity data\n│ CONNECT_ACRO_2010_11.bin\n│ CONNECT_ACRO_2011_12.bin\n│ CONNECT_ACRO_2012_13.bin\n│ CONNECT_ACRO_2014_15.bin\n│ CONNECT_ACRO_2015_16.bin\n│ CONNECT_ACRO_2016_17.bin\n│\n├───id # location ids\n│ id_list_2023_03_30.csv\n│\n└───region # geospatial data\n reefmod_gbr.gpkg","category":"page"},{"location":"architecture/domain_and_resultsets/#ReefMod-Engine-datasets","page":"Inputs and Outputs","title":"ReefMod Engine datasets","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Datasets intended for use with the ReefMod Engine (RME) can also be loaded for use with ADRIAmod. The RME represents larger spatial scales typically covering the entire Great Barrier Reef.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dom = ADRIA.load_domain(RMEDomain, \"path to ReefMod Engine dataset\", \"45\")","category":"page"},{"location":"architecture/domain_and_resultsets/#Naming-conventions","page":"Inputs and Outputs","title":"Naming conventions","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"By convention, the directory name is typically the name of the reef or reef cluster. Where multiple datasets for the same spatial domain are expected, appending a unique suffix is recommended, such as the date of creation, such as \"Moore_2022-11-17\".","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The geopackage is expected to have the same filename as its Domain. For example, if the domain name is \"Example_domain\", then the geopackage file should be named \"Example_domain.gpkg\".","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Degree-heating Week datasets must follow the convention of: dhwRCP[NN].nc","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Here, [NN] is to be replaced with the two digit RCP code that indicates which RCP scenario is represented by the given data cube. The following are examples of valid/expected filenames:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dhwRCP26.nc\ndhwRCP34.nc\ndhwRCP45.nc\ndhwRCP60.nc\ndhwRCP70.nc\ndhwRCP85.nc","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Similarly, below are examples of valid/expected wave stress filenames:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"wave_RCP26.nc\nwave_RCP34.nc\nwave_RCP45.nc\nwave_RCP60.nc\nwave_RCP70.nc\nwave_RCP85.nc","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Below is a diagram indicating the directory layout","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Example_domain\n│ datapackage.json\n│ README.md\n│\n├───connectivity\n│ ├───2015\n│ │ connect_matrix_2015_1.csv\n│ │ connect_matrix_2015_2.csv\n│ │ connect_matrix_2015_3.csv\n│ │\n│ ├───2016\n│ │ connect_matrix_2016_1.csv\n│ │ connect_matrix_2016_2.csv\n│ │ connect_matrix_2016_3.csv\n│ │\n│ └───2017\n│ connect_matrix_2017_1.csv\n│ connect_matrix_2017_2.csv\n│ connect_matrix_2017_3.csv\n│\n├───DHWs\n│ dhwRCP26.nc\n│ dhwRCP45.nc\n│ dhwRCP60.nc\n│ dhwRCP85.nc\n│\n├───site_data\n│ coral_cover.nc\n│ Example_domain.gpkg\n│\n└───waves\n wave_RCP26.nc\n wave_RCP45.nc\n wave_RCP60.nc\n wave_RCP85.nc","category":"page"},{"location":"architecture/domain_and_resultsets/#ResultSets","page":"Inputs and Outputs","title":"ResultSets","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The directory holding results is also treated as a data package referred to as a ResultSet. Scenario outcomes are written out to disk as they complete to a directory located in the user-defined Output directory (see Getting Started).","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The directory name follows the convention of [Domain Name]__[IDs of RCPs]__[date/time of run]. For example: Moore_2022-11-17__RCPs45_60__2023-01-01_19_00_00_000","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The above example ResultSet indicates the \"Moore_2022-11-17\" Domain was run for RCPs 4.5 and 6.0 at precisely 7pm (i.e., 19:00:00.000, where the trailing \"000\" indicates milliseconds). Note that each \"portion\" of information is separated by a double underscore (__).","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Simulation results are stored in Zarr format. A ResultSet also holds a copy of:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"the scenario specifications\nthe geospatial data used\nSummary statistics for the DHW/wave scenarios run, and\nLogs indicating which locations were intervened on","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Below is a diagram of the directory structure. Filenames are not shown here as there may be hundreds/thousands depending on the scenario set run.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Example_domain__RCP45_60_85__2023-03-11_19_00_00_000\n├───env_stats\n│ ├───dhw\n│ │ ├───45\n│ │ ├───60\n│ │ └───85\n│ └───wave\n│ ├───45\n│ ├───60\n│ └───85\n├───inputs\n├───logs\n│ ├───fog\n│ ├───rankings\n│ ├───seed\n│ └───shade\n├───model_spec\n├───results\n│ ├───absolute_shelter_volume\n│ ├───relative_juveniles\n│ ├───relative_shelter_volume\n│ ├───relative_taxa_cover\n│ └───total_absolute_cover\n└───site_data","category":"page"},{"location":"usage/getting_started/#Getting-Started","page":"Getting Started","title":"Getting Started","text":"","category":"section"},{"location":"usage/getting_started/#Setup","page":"Getting Started","title":"Setup","text":"","category":"section"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"This section outlines how ADRIA may be used to arrive at a select range of possible pathways that are robust to possible future conditions.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Create a directory for your project, and start Julia inside that directory:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"$ julia --project=.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"ADRIA may be installed through the package manager or from the github repository (for the most recent development version).","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"julia> ]add ADRIA\n\n# OR, to install the latest development version:\n\njulia> ]add https://github.com/open-AIMS/ADRIA.jl.git","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Similarly, ADRIA can be updated as new releases are made:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"julia> ]up ADRIA","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"If desired, you can create a config.toml file inside your project directory. This is optional, and the assumed default values are shown below:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"[operation]\nnum_cores = 2 # No. of cores to use. Values <= 0 will use all available cores.\nthreshold = 1e-8 # Result values below this will be set to 0.0 (to save disk space)\ndebug = false # Disable multi-processing to allow error messages to be shown\n\n[results]\noutput_dir = \"./Outputs\" # Change this to point to where you want to store results","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"This config.toml file is specific to your computer and project. It should not be committed to version control.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"tip: Performance\nADRIA uses an on-disk data store to hold results from model runs. Setting output_dir to a directory on an SSD (Solid State Drive) will maximize performance.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"To setup ADRIA for development, see the Development setup page.","category":"page"},{"location":"usage/getting_started/#Quick-Start","page":"Getting Started","title":"Quick Start","text":"","category":"section"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"A common workflow would be the following:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Start Julia from the project directory:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"$ julia --project=.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Load data for a spatial domain. See Loading a Domain for more details:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"using ADRIA\n\ndom = ADRIA.load_domain(\"path to domain data package directory\")","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Generate scenarios based on available environmental data layers and model parameters. The number of scenarios shoud be a power of two. See Generating scenarios for more details:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"num_scenarios = 128\nscens = ADRIA.sample(dom, num_scenarios)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Run sampled scenarios for one or more RCPs. Be aware that this may take a while:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"rcp_45 = \"45\"\nrs = ADRIA.run_scenarios(dom, scens, rcp_45)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Or run scenarios across several RCPs:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"rcps = [\"45\", \"60\", \"85\"]\nrs = ADRIA.run_scenarios(dom, scens, rcps)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"It is also possible to load previously run scenarios. See Running scenarios for more details:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"rs = ADRIA.load_results(\"path to results\")","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Extract some metric for analysis (e.g., the total absolute cover for each site and timestep):","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"s_tc = ADRIA.metrics.scenario_total_cover(rs)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Use the visualization tools to plot the results. The Makie package ecosystem is used for producing plots:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"using GLMakie, GeoMakie, GraphMakie\n\n# Plot a quick scenario overview\nfig = ADRIA.viz.scenarios(rs, s_tc; axis_opts=Dict(:ylabel=>\"Absolute Cover\"))\nsave(\"path_to_save_figure\", fig)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"See Analysis for further examples of analysis and plots.","category":"page"},{"location":"API/#ADRIA-API","page":"ADRIA API","title":"ADRIA API","text":"","category":"section"},{"location":"API/#Metrics","page":"ADRIA API","title":"Metrics","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA.metrics]\nOrder = [:constant, :function, :type]\nPrivate = true","category":"page"},{"location":"API/#ADRIA.metrics._absolute_juveniles-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, DataFrames.DataFrame, AbstractVector{T}}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._absolute_juveniles","text":"absolute_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::AbstractVector{T})::AbstractArray{T,2} where {T<:Real}\nabsolute_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}\n\nJuvenile coral cover in m².\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations)\n\ncoral_spec : Coral spec DataFrame\nk_area : The coral habitable area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._absolute_shelter_volume-Union{Tuple{T}, Tuple{YAXArrays.Cubes.YAXArray{T, 3, A} where A<:AbstractArray{T, 3}, Vector{T}, DataFrames.DataFrameRow}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._absolute_shelter_volume","text":"absolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(X::YAXArray{T,4}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(X::YAXArray{T,4}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(rs::ResultSet)\n\nProvide indication of shelter volume in volume of cubic meters.\n\nThe 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).\n\nArguments\n\nX : raw results\nk_area : area in m^2 for each site\nmax_cover : maximum possible coral cover for each site (in percentage of loc_area)\ninputs : DataFrame of scenario inputs\n\nReferences\n\nUrbina-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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._collate_ranked_locs-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._collate_ranked_locs","text":"_collate_ranked_locs(data::YAXArray)::Matrix{Int64}\n\nCollates number of ranked locations.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._collate_ranks-Tuple{ADRIA.ResultSet, Any}","page":"ADRIA API","title":"ADRIA.metrics._collate_ranks","text":"_collate_ranks(rs, selected)\n\nCollates ranks into seed/fog ranking results into a common structure.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._colony_Lcm2_to_m3m2-Tuple{DataFrames.DataFrame}","page":"ADRIA API","title":"ADRIA.metrics._colony_Lcm2_to_m3m2","text":"_colony_Lcm2_to_m3m2(inputs::DataFrame)::Tuple\n_colony_Lcm2_to_m3m2(inputs::YAXArray)::Tuple{Vector{Float64},Vector{Float64}}\n\nHelper function to convert coral colony values from Litres/cm² to m³/m²\n\nArguments\n\ninputs : Scenario values for the simulation\n\nReturns\n\nTuple : Assumed colony volume (m³/m²) for each species/size class, theoretical maximum for each species/size class\n\nReferences\n\nAston 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._coral_evenness-Union{Tuple{AbstractArray{T, 3}}, Tuple{T}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._coral_evenness","text":"coral_evenness(r_taxa_cover::AbstractArray{T})::AbstractArray{T} where {T<:Real}\ncoral_evenness(rs::ResultSet)::AbstractArray{T} where {T}\n\nCalculates evenness across functional coral groups in ADRIA as a diversity metric. Inverse Simpsons diversity indicator.\n\nReferences\n\nHill, M. O. (1973).\n\nDiversity and Evenness: A Unifying Notation and Its Consequences. Ecology, 54(2), 427-432. https://doi.org/10.2307/1934352\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._get_ranks-Tuple{ADRIA.ResultSet, Symbol}","page":"ADRIA API","title":"ADRIA.metrics._get_ranks","text":"_get_ranks(rs::ResultSet, intervention::Int64; kwargs...)\n\nExtracts results for a specific intervention (:seed or :fog)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._juvenile_indicator-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, DataFrames.DataFrame, Vector{Float64}}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._juvenile_indicator","text":"juvenile_indicator(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::Vector{Float64})::AbstractArray{T,2} where {T<:Real}\njuvenile_indicator(rs::ResultSet)::AbstractArray{<:Real,2}\n\nIndicator for juvenile density (0 - 1), where 1 indicates the maximum theoretical density for juveniles have been achieved.\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations).\n\ncoral_spec : Coral spec DataFrame.\nk_area : The coral habitable area.\n\nNotes\n\nMaximum 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._max_juvenile_area","page":"ADRIA API","title":"ADRIA.metrics._max_juvenile_area","text":"_max_juvenile_area(coral_params::DataFrame, max_juv_density::Float64=51.8)\n\nCalculate the maximum possible area that can be covered by juveniles for a given m².\n\n\n\n\n\n","category":"function"},{"location":"API/#ADRIA.metrics._reef_condition_index-NTuple{4, AbstractArray}","page":"ADRIA API","title":"ADRIA.metrics._reef_condition_index","text":"reef_condition_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray; threshold=2)::AbstractArray\nreef_condition_index(rs::ResultSet)::AbstractArray{<:Real}\n\nEstimates a Reef Condition Index (RCI) providing a single value that indicates the condition of a reef across four metrics:\n\ncoral cover\nevenness (coral diversity)\nshelter volume, and\nabundance of juveniles\n\nNotes\n\nJuveniles are made relative to maximum observed juvenile density (51.8/m²) See notes for juvenile_indicator()\n\nArguments\n\nrc : Relative coral cover across all groups\nevenness : Evenness across all coral groups\nsv : Shelter volume based on coral sizes and abundances\njuves : Abundance of coral juveniles < 5 cm diameter\n\nReturns\n\nYAXArray[timesteps ⋅ locations ⋅ scenarios]\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._reef_fish_index-Tuple{AbstractArray, Any, Any}","page":"ADRIA API","title":"ADRIA.metrics._reef_fish_index","text":"reef_fish_index(rc::AbstractArray)\nreef_fish_index(rs::ResultSet)\n\nThe Reef Fish Index (RFI) estimates fish biomass from relative coral cover.\n\nA 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]).\n\nValues are provided ∈ [0, 1], where 1 indicates maximum fish biomass.\n\nNote: Coral cover here is relative to coral habitable area (k area).\n\nArguments\n\nrc : Relative cover\n\nReturns\n\nYAXArray[timesteps ⋅ locations ⋅ scenarios], values in kg/km²\n\nReferences\n\nGraham, N.A.J., Nash, K.L., 2013.\n\nThe importance of structural complexity in coral reef ecosystems. Coral Reefs 32, 315–326. https://doi.org/10.1007/s00338-012-0984-y\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._reef_tourism_index-Tuple{AbstractArray, AbstractArray, AbstractArray, AbstractArray, Vector}","page":"ADRIA API","title":"ADRIA.metrics._reef_tourism_index","text":"reef_tourism_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray, intcp_u::Vector)::AbstractArray\nreef_tourism_index(rs::ResultSet; intcp_u::Bool=false)::AbstractArray\n\nEstimate tourism index.\n\nNote: 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.\n\nArguments\n\nrc : Relative coral cover across all groups\nevenness : Evenness across all coral groups\nsv : Shelter volume based on coral sizes and abundances\njuves : Abundance of coral juveniles < 5 cm diameter\nintcp_u : ?\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_cover-Tuple{YAXArrays.Cubes.YAXArray{var\"#s395\", N, A} where {var\"#s395\"<:Real, N, A<:AbstractArray{var\"#s395\", N}}}","page":"ADRIA API","title":"ADRIA.metrics._relative_cover","text":"relative_cover(X::AbstractArray{<:Real})::AbstractArray{<:Real}\nrelative_cover(rs::ResultSet)::AbstractArray{<:Real}\n\nIndicate coral cover relative to available hard substrate (k area).\n\nArguments\n\nX : Matrix with dimensions (ntimesteps, nfunctionalgroups * nsize_classes,\n\nn_locations) of raw model results (coral cover relative to available space)\n\nReturns\n\nCoral cover [0 - 1], relative to available k area for a given location.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_juveniles-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, DataFrames.DataFrame}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._relative_juveniles","text":"relative_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame)::AbstractArray{T,2} where {T<:Real}\nrelative_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}\n\nJuvenile coral cover relative to total site area.\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations)\n\ncoral_spec : Coral spec DataFrame\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_loc_taxa_cover-Union{Tuple{T}, Tuple{AbstractArray{T}, Vector{T}, Int64}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._relative_loc_taxa_cover","text":"relative_loc_taxa_cover(X::AbstractArray{T}, k_area::Vector{T}, n_groups::Int64)::AbstractArray{T,3} where {T<:Real}\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations)\n\nk_area : The coral habitable area.\nn_groups : Number of function coral groups.\n\nReturns\n\nCoral cover, grouped by taxa for the given scenario, for each timestep and location, relative to location k area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_shelter_volume-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, Vector{T}, DataFrames.DataFrameRow}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._relative_shelter_volume","text":"relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(rs::ResultSet)\n\nProvide indication of shelter volume relative to theoretical maximum volume for the area covered by coral.\n\nThe 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).\n\nRSV = begincases\nTASV MSV MSV 0 \n0 textotherwise\nendcases\n\nwhere TASV represents Total Absolute Shelter Volume and MSV represents the maximum shelter volume possible.\n\nArguments\n\nX : raw results\nk_area : area in m^2 for each site\nscens : DataFrame of scenario inputs\n\nReturns\n\nShelter volume relative to a theoretical maximum volume for the available k area.\n\nReferences\n\nUrbina-Barreto, I., Chiroleu, F., Pinel, R., Fréchon, L., Mahamadaly, V., Elise, S.,\n\nKulbicki, 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_taxa_cover-Tuple{AbstractArray{<:Real}, Vector{<:Real}, Int64}","page":"ADRIA API","title":"ADRIA.metrics._relative_taxa_cover","text":"relative_taxa_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real}, n_groups::Int64)::AbstractArray{<:Real,2}\nrelative_taxa_cover(rs::ResultSet)::AbstractArray{<:Real,2}\n\nRelative coral cover grouped by taxa/species sumed up across all locations.\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations).\n\nk_area : The coral habitable area.\nn_groups : Number of function coral groups.\n\nReturns\n\nCoral cover, grouped by taxa for the given scenario, summed up across all locations, relative to total k area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_absolute_juveniles-Tuple{YAXArrays.Cubes.YAXArray, DataFrames.DataFrame, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._scenario_absolute_juveniles","text":"scenario_absolute_juveniles(data::YAXArray, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}\nscenario_absolute_juveniles(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean absolute juvenile population for each scenario for the entire domain.\n\nArguments\n\nX : Raw data for a single scenario.\ncoral_spec : Coral spec DataFrame.\nk_area : K_area.\nrs : Resultset.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_asv-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_asv","text":"scenario_asv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}\nscenario_asv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean absolute shelter volumes for each scenario for the entire domain.\n\nArguments\n\nasv : Absolute shelter volume.\nrs : Resultset.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_evenness-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_evenness","text":"scenario_evenness(ev::YAXArray; kwargs...)::AbstractArray{<:Real}\nscenario_evenness(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean coral evenness for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_juvenile_indicator-Tuple{YAXArrays.Cubes.YAXArray, DataFrames.DataFrame, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._scenario_juvenile_indicator","text":"scenario_juvenile_indicator(data::YAXArray, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}\nscenario_juvenile_indicator(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nDetermine juvenile indicator ∈ [0, 1], where 1 indicates maximum mean juvenile density (51.8) has been achieved.\n\nArguments\n\nX : Raw data for a single scenario.\ncoral_spec : Coral spec DataFrame.\nk_area : K_area.\nrs : Resultset.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rci-Tuple{YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rci","text":"scenario_rci(rci::YAXArray, tac::YAXArray; kwargs...)\nscenario_rci(rs::ResultSet; kwargs...)\n\nExtract the total populated area of locations with Reef Condition Index of \"Good\" or higher for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_relative_cover-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics._scenario_relative_cover","text":"scenario_relative_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean relative coral cover for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_relative_juveniles-Tuple{YAXArrays.Cubes.YAXArray{var\"#s388\", 3, A} where {var\"#s388\"<:Real, A<:AbstractArray{var\"#s388\", 3}}, DataFrames.DataFrame, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._scenario_relative_juveniles","text":"scenario_relative_juveniles(X::YAXArray{<:Real,3}, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}\nscenario_relative_juveniles(rs::ResultSet; kwargs...)::YAXArray\n\nCalculate the mean relative juvenile population for each scenario for the entire domain.\n\nArguments\n\nX : Raw data for a single scenario.\nrs : Resultset.\ncoral_spec : Coral spec DataFrame.\nk_area : K_area.\n\nExamples\n\nnum_scens = 2^5\nscens = ADRIA.sample(dom, num_scens)\n\n_coral_spec = ADRIA.to_coral_spec(scens[1,:])\n_k_area = site_k_area(dom)\n\n# X contains raw coral cover results for a single scenario\nADRIA.metrics.scenario_relative_juveniles(X, _coral_spec, _k_area)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rfi-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rfi","text":"scenariorfi(rfi::YAXArray; kwargs...) scenariorfi(rs::ResultSet; kwargs...)\n\nCalculate the mean Reef Fish Index (RFI) for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rsv-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rsv","text":"scenario_rsv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}\nscenario_rsv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean relative shelter volumes for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rti-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rti","text":"scenario_rti(rti::YAXArray; kwargs...)\nscenario_rti(rs::ResultSet; kwargs...)\n\nCalculate the mean Reef Tourism Index (RTI) for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_total_cover-Tuple{AbstractArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_total_cover","text":"scenario_total_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean absolute coral for each scenario for the entire domain.\n\nArguments\n\ntac : Total absolute cover\nrs : ResultSet\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._shelter_species_loop!-Union{Tuple{V}, Tuple{YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray, Int64, V, V}} where V<:(AbstractVector{<:Float64})","page":"ADRIA API","title":"ADRIA.metrics._shelter_species_loop!","text":"shelterspeciesloop!(X::YAXArray, ASV::YAXArray, nspecies::Int64, colonyvolm3perm2::V, karea::V) where {V<:AbstractVector{<:Float64}}\n\nHelper method to calculate absolute shelter volume metric across each species/size class for a given scenario.\n\nArguments\n\nX : raw results (proportional coral cover relative to full site area)\nASV : matrix to hold shelter volume results\nnspecies : number of species (taxa and size classes) considered\nscen : scenario number to calculate metric for\ncolony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class\nk_area : habitable area of site in m²\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._shelter_species_loop-Union{Tuple{F}, Tuple{T1}, Tuple{AbstractArray{T1, 3}, Int64, Array{F}, Array{F}, Array{F}}} where {T1<:Real, F<:Float64}","page":"ADRIA API","title":"ADRIA.metrics._shelter_species_loop","text":"_shelter_species_loop(X::AbstractArray{T1,3}, n_species::Int64, colony_vol_m3_per_m2::Array{F}, max_colony_vol_m3_per_m2::Array{F}, k_area::Array{F})::YAXArray where {T1<:Real,F<:Float64}\n\nHelper method to calculate relative shelter volume metric across each species/size class for a given scenario.\n\nNote: 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.\n\nArguments\n\nX : raw results (proportional coral cover relative to full site area)\nn_group_and_size : number of species (taxa and size classes) considered\ncolony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class\nmax_colony_vol_m3_per_m2 : theoretical maximum volume per m² of coverage for each taxa\nk_area : habitable area of site in m² (i.e., k area)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._total_absolute_cover-Tuple{AbstractArray{<:Real}, Vector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._total_absolute_cover","text":"total_absolute_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real})::AbstractArray{<:Real}\ntotal_absolute_cover(rs::ResultSet)::AbstractArray{<:Real}\n\nThe Total Absolute Coral Cover. Sum of proportional area taken up by all corals, multiplied by total site area.\n\nArguments\n\nrelative_cover : Array with relative_cover\nk_area : Site areas, with sites following the same order as given indicated in X.\n\nReturns\n\nAbsolute coral cover for a given location in m².\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.axes_units-Tuple{Union{Tuple, Vector{Symbol}}}","page":"ADRIA API","title":"ADRIA.metrics.axes_units","text":"axes_units(axes_names::Union{Vector{Symbol},Tuple})::Tuple\n\nGet units for each metric axis.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.call_metric-Tuple{Union{Function, ADRIA.metrics.Metric}, YAXArrays.Cubes.YAXArray, Vararg{Any}}","page":"ADRIA API","title":"ADRIA.metrics.call_metric","text":"call_metric(metric::Union{Function,Metric}, data::YAXArray, args...; kwargs...)\n\nConvenience method that slices the data in the specified manner.\n\nArguments\n\nmetric : Function, the metric function to apply to \"raw\" data.\ndata : YAXArray, data to pass into metric\nargs : Additional positional arguments to pass into metric\nkwargs : Additional keyword arguments to pass into slice_results\ndims : dummy keyword argument, not used but defined to allow use with other methods\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.dims-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.dims","text":"dims(m::Metric)::Tuple\n\nGet dimension names for a given outcome/metric.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.dominates-Tuple{AbstractVector{<:Real}, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics.dominates","text":"dominates(x::Vector{<:Real}, y::Vector{<:Real})::Vector\n\nAdapted from: https://discourse.julialang.org/t/fast-optimized-non-dominated-sorting-algorithms/86793/7\n\nOriginal function name is dominates2()\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.ensemble_loc_difference-Union{Tuple{T}, Tuple{YAXArrays.Cubes.YAXArray{T, 3, A} where A<:AbstractArray{T, 3}, DataFrames.DataFrame}} where T","page":"ADRIA API","title":"ADRIA.metrics.ensemble_loc_difference","text":"ensemble_loc_difference(outcome::YAXArray{T,3}, scens::DataFrame; agg_metric::Union{Function,AbstractFloat}=median, diff_target=:guided, conf::Float64=0.95, rng::AbstractRNG=Random.GLOBAL_RNG)::YAXArray where {T}\n\nMean bootstrapped difference (counterfactual - target) between some outcome aggregated for each location.\n\nArguments\n\noutcome : Metric outcome with dimensions (:timesteps, :locations, :scenarios).\nscens : Scenarios DataFrame.\nagg_metric : Metric used to aggregate scenarios when comparing between counterfactual and\n\ntarget. If it is an AbstractFloat between 0 and 1, it uses the bs_metric-th quantile. Defaults to median.\n\ndiff_target : Target group of scenarios to compare with. Valid options are :guided and\n\n:unguided. Defaults to :guided\n\nconf : Percentile used for the confidence interval. Defaults to 0.95.\nrng : Pseudorandom number generator.\n\nExample\n\n# Load domain\ndom = ADRIA.load_domain(path_to_domain)\n\n# Create scenarios\nnum_scens = 2^6\nscens = ADRIA.sample(dom, num_scens)\n\n# Run model\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# Calculate difference to the counterfactual for given metric\n_relative_cover = metrics.relative_cover(rs)\n\n# Compute difference between guided and counterfactual using the 0.6-th quantile\ngd_res = metrics.ensemble_loc_difference(r_cover, scens; agg_metric=0.6)\n\n# Compute difference between unguided and counterfactual using the median\nug_res = metrics.ensemble_loc_difference(r_cover, scens; diff_target=:unguided)\n\n# Plot maps of difference to the counterfactual\nADRIA.viz.map(rs, gd_res[summary=At(:agg_value)]; diverging=true)\nADRIA.viz.map(rs, ug_res[summary=At(:agg_value)]; diverging=true)\n\nReturns\n\nVector with bootstrapped difference (counterfactual - guided) for each location.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.fill_axes_metadata!-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.fill_axes_metadata!","text":"fill_axes_metadata!(outcomes::YAXArray)::Nothing\n\nFill outcomes axes metadata.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.fill_metadata!-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{YAXArrays.Cubes.YAXArray{T, N, A}, ADRIA.metrics.Metric}} where {T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.fill_metadata!","text":"fill_metadata!(outcomes::YAXArray{T,N,A}, metric::Metric)::YAXArray{T,N,A} where {T,N,A}\nfill_metadata!(outcomes::YAXArray{T,N,A}, metadata::Dict{Symbol,Any})::YAXArray{T,N,A} where {T,N,A}\n\nFill outcomes YAXArray metadata (properties attribute).\n\nArguments\n\noutcomes : YAXArray datacube of metric outcomes.\nmetric : ADRIA.metrics.Metric object.\nmetadata : Dict to be used to fill outcomes metrics metadata.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.fog_ranks-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.fog_ranks","text":"fog_ranks(rs::ResultSet; kwargs...)\n\nArguments\n\nrs : ResultSet\nkwargs : named dimensions to slice across\n\nReturns\n\nYAXArray[timesteps, sites, scenarios]\n\nExample\n\nADRIA.metrics.fog_ranks(rs; timesteps=1:10, scenarios=3:5)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.loc_trajectory-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{D}, Tuple{Any, YAXArrays.Cubes.YAXArray{D, T, N, A}}} where {D, T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.loc_trajectory","text":"loc_trajectory(metric, data::YAXArray{D,T,N,A})::YAXArray where {D,T,N,A}\n\nAlias for summarize(data, [:scenarios], metric). Collate trajectory for each location.\n\nExamples\n\nusing Statistics\n\nrs = ADRIA.load_results(\"some results\")\ntac = ADRIA.metrics.total_absolute_cover(rs)\n\n# Get median trajectory for each site\nADRIA.metrics.loc_trajectory(median, tac)\n#75×216 YAXArray{Float64,2} with dimensions:\n# Dim{:timesteps} Categorical{Any} Any[1, 2, …, 74, 75] Unordered,\n# Dim{:locations} Categorical{Any} Any[1, 2, …, 215, 216] Unordered\n#Total size: 126.56 KB\n\n# Get upper 95% CI for each site\nADRIA.metrics.loc_trajectory(x -> quantile(x, 0.975), tac)\n#75×216 YAXArray{Float64,2} with dimensions:\n# Dim{:timesteps} Categorical{Any} Any[1, 2, …, 74, 75] Unordered,\n# Dim{:locations} Categorical{Any} Any[1, 2, …, 215, 216] Unordered\n#Total size: 126.56 KB\n\nArguments\n\nmetric : Any function (nominally from the Statistics package) to be applied to data\ndata : Data set to apply metric to\n\nReturns\n\n2D array of T S, where T is total number of time steps and S is number of locations\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.metadata-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.metadata","text":"metadata(outcomes::YAXArray)::Dict{Symbol,Any}\n\nHelper function to extract metadata from YAXArrays.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.metric_label-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.metric_label","text":"metric_label(m::Metric)::String\nmetric_label(f::Function, unit::String)\n\nReturn name of metric in the format: \"Title Case [Unit]\", suitable for use as a label.\n\nExample\n\nm_label = metric_label(scenario_total_cover)\n# \"Scenario Total Cover [m²]\"\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.n_fog_locations-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.n_fog_locations","text":"n_fog_locations(rs::ResultSet; kwargs...)::Matrix{Int64}\n\nDetermine the number of locations fogged at each time step, for each scenario.\n\nReturns\n\nYAXArray[timesteps ⋅ scenarios] indicating the number of locations fogged at each time step.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.n_seed_locations-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.n_seed_locations","text":"n_seed_locations(rs::ResultSet; kwargs...)::Matrix{Int64}\n\nDetermine the number of locations seeded at each time step, for each scenario.\n\nReturns\n\nYAXArray[timesteps ⋅ scenarios] indicating the number of locations seeded at each time step.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.nds","page":"ADRIA API","title":"ADRIA.metrics.nds","text":"nds(X::AbstractArray{<:Real}, dist::Int64=0)::Vector{Vector{<:Int}}\n\nNaive n-dimensional non-dominated sorting.\n\nAdapted from: https://discourse.julialang.org/t/fast-optimized-non-dominated-sorting-algorithms/86793/7\n\nOriginal function name is nds4()\n\nArguments\n\nX : outcomes, where rows are scenarios and columns are metric results. dist : distance from front, where 0 is on the frontier.\n\nReturns\n\nVector of Vectors with row indices for each dist from frontier, where 0 is on the frontier.\n\n\n\n\n\n","category":"function"},{"location":"API/#ADRIA.metrics.per_loc-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{D}, Tuple{Any, YAXArrays.Cubes.YAXArray{D, T, N, A}}} where {D, T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.per_loc","text":"per_loc(metric, data::YAXArray{D,T,N,A})::YAXArray where {D,T,N,A}\n\nAlias for summarize(data, [:scenarios, :timesteps], metric). Get metric results applied to the location-level at indicated time (or across timesteps).\n\nArguments\n\nmetric : Any function (nominally from the Statistics package) to be applied to data\ndata : Data set to apply metric to\ntimesteps : timesteps to apply metric across\n\nReturns\n\nNamed Vector of N elements, where N is the number of locations.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.scenario_outcomes-Tuple{ADRIA.ResultSet, Vector{<:ADRIA.metrics.Metric}}","page":"ADRIA API","title":"ADRIA.metrics.scenario_outcomes","text":"scenario_outcomes(rs::ResultSet, metrics::Vector{Metric})::YAXArray\n\nGet outcomes for a given list of metrics and a result set.\n\nArguments\n\nrs : ResultSet\nmetrics : Vector of scenario Metrics (the ones that start with scenario_)\n\nReturns\n\nYAXArray with (:timesteps, :scenarios, :outcomes)\n\nExamples\n\nmetrics::Vector{ADRIA.metrics.Metric} = [\n ADRIA.metrics.scenario_total_cover,\n ADRIA.metrics.scenario_asv,\n ADRIA.metrics.scenario_absolute_juveniles,\n]\n\n# 3-dimensional Array of outcomes\noutcomes = ADRIA.metrics.scenario_outcomes(rs, metrics)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.scenario_trajectory-Tuple{AbstractArray}","page":"ADRIA API","title":"ADRIA.metrics.scenario_trajectory","text":"scenario_trajectory(data::AbstractArray; metric=mean)::YAXArray{<:Real}\n\nProduce scenario trajectories using the provided metric/aggregation function.\n\nArguments\n\ndata : Results to aggregate\nmetric : Function or Callable used to summarize data\n\nReturns\n\nMatrix[timesteps ⋅ scenarios]\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.seed_ranks-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.seed_ranks","text":"seed_ranks(rs::ResultSet; kwargs...)\n\nArguments\n\nrs : ResultSet\nkwargs : named dimensions to slice across\n\nReturns\n\nYAXArray[timesteps, sites, scenarios]\n\nExample\n\nADRIA.metrics.seed_ranks(rs; timesteps=1:10, scenarios=3:5)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.slice_results-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.slice_results","text":"slice_results(data::YAXArray; timesteps=(:), species=(:), locations=(:), scenarios=(:))\n\nSlice data as indicated. Dimensions not found in target data are ignored.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{D}, Tuple{YAXArrays.Cubes.YAXArray{D, T, N, A}, Vector{Symbol}, Function}} where {D, T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.summarize","text":"summarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function)::YAXArray{<:Real}\nsummarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function, timesteps::Union{UnitRange,Vector{Int64},BitVector})::YAXArray{<:Real}\n\nApply summary metric along some axis of a data set across some or all timesteps.\n\nArguments\n\ndata : Data set to apply metric to.\nalongs_axis : which axis will be replaced with (:) when slicing.\nmetric : Any function (nominally from the Statistics package) to be applied to data.\ntimesteps : timesteps to apply metric across.\n\nReturns\n\nYAXArray with summary metric for the remaining axis.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_absolute_shelter_volume-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_absolute_shelter_volume","text":"summarize_absolute_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_absolute_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized coral evenness.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_coral_evenness-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_coral_evenness","text":"summarize_coral_evenness(raw::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_coral_evenness(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized coral evenness.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_raw-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_raw","text":"summarize_raw(data::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nSummarize raw data, aggregating the specified dimensions (e.g., timesteps, scenarios, etc.) and collapsing given dims.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_relative_cover-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_relative_cover","text":"summarize_relative_cover(rc::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_relative_cover(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized relative cover.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_relative_shelter_volume-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_relative_shelter_volume","text":"summarize_relative_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_relative_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized coral evenness.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_total_cover-Tuple{YAXArrays.Cubes.YAXArray, AbstractArray{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics.summarize_total_cover","text":"summarize_total_cover(raw::YAXArray, areas::AbstractArray{<:Real}; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_total_cover(rs::ResultSet; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized total absolute cover.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.to_string-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.to_string","text":"to_string(m::Metric)::String\n\nGet name of metric as a string.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.to_symbol-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.to_symbol","text":"to_symbol(m::Metric)::String\n\nGet name of metric as a symbol.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.top_N_sites-Tuple{ADRIA.ResultSet, Int64}","page":"ADRIA API","title":"ADRIA.metrics.top_N_sites","text":"top_N_sites(rs::ResultSet; N::Int64; metric::relative_cover)\ntop_N_sites(data::AbstractArray{Real}, N::Int64; stat=mean)\n\nReturn the top N sites according to the provided metric (defaulting to mean of relative_cover).\n\nArguments\n\nrs : ResultSet\nN : Number of best performing sites to be selected\nmetric : Metric to use to order sites from best to worst, must take ResultSet as input\nstat : Summary statistic to use for comparison (default: mean)\n\nReturns\n\nYAXArray[:scenarios, :locations], where locations indicates order of location ranking.\n\nExample\n\nADRIA.metrics.top_N_sites(rs, 5)\nADRIA.metrics.top_N_sites(rs, 5; metric=ADRIA.metric.relative_cover)\nADRIA.metrics.top_N_sites(rs, 5; metric=ADRIA.metric.relative_cover, stat=median)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.top_n_seeded_sites-Tuple{ADRIA.ResultSet, Int64}","page":"ADRIA API","title":"ADRIA.metrics.top_n_seeded_sites","text":"top_n_seeded_sites(rs::ResultSet, n::Int64; kwargs...)\n\nGet the top n seeded sites over time by their unique location id. Lower rank values are better (e.g., 1 = first choice)\n\nArguments\n\nrs : ResultSet\nn : n locations to retrieve\nkwargs : dimensions to slice across\n\nReturns\n\nYAXArray[locations, [locid, locname, rank], scenarios]\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.trajectory_heatmap-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.trajectory_heatmap","text":"trajectory_heatmap(data::YAXArray)::HeatMap\n\nEstimate heatmap of trajectories from a 2D dataset.\n\nArguments\n\ndata : An N*D matrix where N is time steps and D is the scenario outcome for the given timestep in N\n\nReturns\n\nOnlineStats.HeatMap\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.trajectory_heatmap_data-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.trajectory_heatmap_data","text":"trajectory_heatmap_data(data::YAXArray)::Tuple{Vector{Float64},Vector{Float64},Matrix{Int64}}\n\nEstimate heatmap of trajectories from a 2D dataset.\n\nArguments\n\ndata : An N*D matrix where N is time steps and D is the scenario outcome for the given timestep in N\n\nReturns\n\nTuple of xedges, yedges, and bi-dimensional histogram matrix\n\n\n\n\n\n","category":"method"},{"location":"API/#Base.ndims-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"Base.ndims","text":"ndims(m::Metric)::Int64\n\nInfer the number of dimensions for a given outcome/metric.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.Metric-Tuple{Any, Vararg{Any}}","page":"ADRIA API","title":"ADRIA.metrics.Metric","text":"(f::Metric)(raw, args...; kwargs...)\n(f::Metric)(rs::ResultSet, args...; kwargs...)\n\nMakes Metric types callable with arbitary arguments that are passed to associated function.\n\n\n\n\n\n","category":"method"},{"location":"API/#Performance-indicators","page":"ADRIA API","title":"Performance indicators","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA.performance]\nOrder = [:function, :type]","category":"page"},{"location":"API/#ADRIA.performance.RMSE-Tuple{Any, Any}","page":"ADRIA API","title":"ADRIA.performance.RMSE","text":"Root Mean Square Error\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.environmental_diversity-Tuple{Any, Any}","page":"ADRIA API","title":"ADRIA.performance.environmental_diversity","text":"environmental_diversity(ms, inputs_i)\n\nObtain an indication of environmental factor diversity for a scenario set. Higher values indicate a greater of mix of environmental conditions were experienced between scenarios.\n\nThis is referred to as E.\n\nArguments\n\nms : model spec\ninputs_i : inputs used for scenarios of interest\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.gmd-Tuple{AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.gmd","text":"gmd(vals::AbstractVector{<:Real})::Float64\ngmd(vals::AbstractMatrix{<:Real})\n\nGini's Mean Difference.\n\nThe absolute mean of all pairwise distances between elements in a given set.\n\nReferences\n\nLa 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\nYitzhaki, 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\nKashif, 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.intervention_diversity-Tuple{Any, Any}","page":"ADRIA API","title":"ADRIA.performance.intervention_diversity","text":"intervention_diversity(ms, inputs_i)\n\nObtain an indication of intervention diversity for a scenario. Higher values indicate a greater of mix of interventions options were applied.\n\nThis is referred to as D.\n\nArguments\n\nms : model spec\ninputs_i : inputs used for scenarios of interest\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.intervention_effort-Tuple{Any, Any, Any}","page":"ADRIA API","title":"ADRIA.performance.intervention_effort","text":"intervention_effort(ms, inputs_i)\n\nObtain an indication of intervention effort for each scenario and intervention type. This is referred to as F.\n\nArguments\n\nms : model spec\ninputs_i : inputs used for scenarios of interest\n\nReturns\n\nMatrix 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.normalize-Tuple{AbstractArray{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.normalize","text":"normalize(vals::AbstractArray{<:Real})\n\nNormalize values using feature scaling such that values are bound between 0 and 1, where 1 is equivalent to the maximum value found.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.probability-Tuple{AbstractArray{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.probability","text":"probability(vals::AbstractArray{<:Real})\n\nCalculate probability of individual trajectories, given a scenario ensemble S.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.temporal_variability-Tuple{AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.temporal_variability","text":"temporal_variability(x::AbstractVector{<:Real})\ntemporal_variability(x::AbstractArray{<:Real, 2})\ntemporal_variability(x::AbstractArray{<:Real}, func_or_data...)\n\nThe V meta-metric.\n\nAs 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.\n\nExamples\n\n# Apply V to a time series\njulia> temporal_variability(rand(50))\n\n# Apply V to an ensemble of time series\njulia> x = rand(50, 200)\njulia> temporal_variability(x)\n\n# Create and apply a modified V metric to an ensemble of time series.\n# Where the argument is an array and not a function, the data is used directly\n# and so it is assumed all matrices are of the same size and shape.\njulia> temporal_variability(x, temporal_variabilty, temporal_variability(P(x)))\njulia> temporal_variability(x, temporal_variabilty, P(x), D(x), E(x))\n\n\n\n\n\n","category":"method"},{"location":"API/#Sensitivity","page":"ADRIA API","title":"Sensitivity","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA.sensitivity]\nOrder = [:function, :type]","category":"page"},{"location":"API/#ADRIA.sensitivity._category_bins-Tuple{DataFrames.DataFrame}","page":"ADRIA API","title":"ADRIA.sensitivity._category_bins","text":"_category_bins(foi_spec::DataFrame)::Int64\n\nGet number of bins for categorical variables.\n\nArguments\n\nfoi_spec : Model specification for factors of interest\n\nReturns\n\nNumber of bins relevant to the factor of interest\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._create_seq_store-Tuple{DataFrames.DataFrame, Vector{Symbol}, Int64}","page":"ADRIA API","title":"ADRIA.sensitivity._create_seq_store","text":"_create_seq_store(model_spec::DataFrame, unordered_cat::Vector{Symbol}, S::Int64)::Dict{Symbol,Vector{Float64}}\n\nGet stored bin sequences for each factor type.\n\nArguments\n\nmodel_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet\nunordered_cat : Factors considered for sensitivity analysis of unordered categorical type.\nS : Number of bins.\n\nReturns\n\nA dictionary containing bin sequences for each factor\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._foi_data_stores-Tuple{Dict{Symbol, Vector{Float64}}, DataFrames.DataFrame, Vector{Symbol}, NamedTuple}","page":"ADRIA API","title":"ADRIA.sensitivity._foi_data_stores","text":"_foi_data_stores(\n seq_store::Dict{Symbol,Vector{Float64}},\n m_spec::DataFrame,\n unordered_cat::Vector{Symbol};\n second_dim::NamedTuple\n)::Dataset\n\nGenerate data stores of correct size for each factor of interest.\n\nArguments\n\nseq_store : Dictionary for storing bin sequences (created by _create_seq_store)\nm_spec : Model specification\nunordered_cat : List of unordered categorical variables.\nsecond_dim : second storage dimension (e.g. (CI=[\"mean\",\"lower\",\"upper\"], ))\n\nReturns\n\nDataset containing storage for sensitivity ranges for each factor.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._get_cat_quantile-Tuple{DataFrames.DataFrame, Symbol, Vector{Float64}}","page":"ADRIA API","title":"ADRIA.sensitivity._get_cat_quantile","text":"_get_cat_quantile(foi_spec::DataFrame, factor_name::Symbol, steps::Vector{Float64})::Vector{Float64}\n\nGet quantiles for a given categorical variable.\n\nArguments\n\nfoi_spec : Model specification for factors of interest\nfactor_name : Contains true where the factor is categorical and false otherwise\nsteps : Number of steps for defining bins\n\nReturns\n\nQuantile for a categorical factor.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._get_factor_quantile-Tuple{Dict{Symbol, Vector{Float64}}, DataFrames.DataFrame, Vector{Float64}, Symbol}","page":"ADRIA API","title":"ADRIA.sensitivity._get_factor_quantile","text":"_get_factor_quantile(seq_store::Dict{Symbol,Vector{Float64}}, foi_spec::DataFrame, fact_t::Symbol)\n\nChecks the type of the factor to calculate its quantile.\n\nArguments\n\nseq_store : storage containing bin sequences for factors considered\nfoi_spec : Model specification for factors of interest\nX_f : Scenario dataframe for factor of interest\nfactor_name : Contains true where the factor is categorical and false otherwise\n\nReturns\n\nQuantile for factor fact_t, given bin sequences in seq_store\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._get_factor_spec-Tuple{DataFrames.DataFrame, Vector{Symbol}}","page":"ADRIA API","title":"ADRIA.sensitivity._get_factor_spec","text":"_get_factor_spec(model_spec::DataFrame, factors::Vector{Symbol})::DataFrame\n\nGet model spec for specified factors.\n\nArguments\n\nmodel_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet\nfactors : Factors considered for sensitivity analysis\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._map_outcomes-Tuple{AbstractVecOrMat{<:Real}, Union{BitVector, Vector{Int64}}}","page":"ADRIA API","title":"ADRIA.sensitivity._map_outcomes","text":"_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Union{BitVector,Vector{Int64}})::Union{BitVector,Vector{Int64}}\n_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Function)::Vector{Int64}\n\nApply rule to create mapping between X (model inputs/parameters/factors) and y (model outcomes).\n\nNote\n\nWhere the rule is a vector indicating true/false, the y argument is ignored. The function accepts the y argument simply to maintain compatibility so the same method name can be applied.\n\nArguments\n\ny : Model outputs/outcomes\nrule : BitVector, or Function that returns a BitVector, indicating outcomes that meet some desired threshold/behavior.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.convergence-Tuple{DataFrames.DataFrame, YAXArrays.Cubes.YAXArray, Vector{Symbol}}","page":"ADRIA API","title":"ADRIA.sensitivity.convergence","text":"convergence(X::DataFrame, y::YAXArray, target_factors::Vector{Symbol}; n_steps::Int64=10)::YAXArray\nconvergence(rs::ResultSet, X::DataFrame, y::YAXArray, components::Vector{String}; n_steps::Int64=10)::YAXArray\n\nCalculates 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.\n\nArguments\n\nrs : Result set (only needed if aggregating over model components).\nX : Model inputs\ny : Model outputs\ntarget_factors : Names of target factors represented by columns in X.\ncomponents : Names of model components to aggregate over (e.g. [:Intervention, :Criteria]).\nn_steps : Number of steps to cut the total number of scenarios into.\n\nReturns\n\nYAXArray, of min, lower bound, mean, median, upper bound, max, std, and cv summary statistics for an increasing number of scenarios.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.ks_statistic-Tuple{HypothesisTests.ApproximateKSTest}","page":"ADRIA API","title":"ADRIA.sensitivity.ks_statistic","text":"ks_statistic(ks)\n\nCalculate the Kolmogorov-Smirnov test statistic.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.outcome_map-Tuple{YAXArrays.Cubes.YAXArray, AbstractArray, AbstractArray, AbstractVecOrMat{<:Real}, BitVector}","page":"ADRIA API","title":"ADRIA.sensitivity.outcome_map","text":"outcome_map(p::YAXArray, X_q::AbstractArray, X_f::AbstractArray, y::AbstractVecOrMat{<:Real}, behave::BitVector; n_boot::Int64=100, conf::Float64=0.95)::YAXArray\noutcome_map(X::DataFrame, y::AbstractVecOrMat{<:Real}, rule::Union{Function,BitVector,Vector{Int64}}, target_factors::Vector{Symbol}, model_spec::DataFrame; S::Int64=10, n_boot::Int64=100, conf::Float64=0.95)::Dataset\noutcome_map(X::DataFrame, y::AbstractVecOrMat{<:Real}, rule::Union{Function,BitVector,Vector{Int64}}, target_factor::Symbol, model_spec::DataFrame; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::YAXArray\noutcome_map(X::DataFrame, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}\noutcome_map(rs::ResultSet, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}, target_factors::Vector{Symbol}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}\noutcome_map(rs::ResultSet, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}, target_factor::Symbol; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::YAXArray where {T<:Real}\noutcome_map(rs::ResultSet, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}\n\nMap normalized outcomes (defined by rule) to factor values discretized into S bins.\n\nProduces 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.\n\nNote:\n\ny is normalized on a per-column basis prior to the analysis\nEmpty areas of factor space (those that do not have any desired outcomes) will be assigned NaN\n\nArguments\n\nX : scenario specification\ny : Vector or Matrix of outcomes corresponding to scenarios in X\nrule : a callable defining a \"desirable\" scenario outcome\ntarget_factors : list of factors of interest to perform analyses on\nS : number of slices of factor space. Higher values equate to finer granularity\nn_boot : number of bootstraps (default: 100)\nconf : confidence interval (default: 0.95)\n\nReturns\n\n3-dimensional YAXArray, of shape S ⋅ D ⋅ 3, where:\n\nS\nis the slices,\nD\nis the number of dimensions, with\nboostrapped mean (dim 1) and the lower/upper 95% confidence interval (dims 2 and 3).\n\nExamples\n\n# Get metric of interest\nmu_tac = vec(mean(ADRIA.metrics.scenario_total_cover(rs), dims=:timesteps))\n\n# Factors of interest\nfoi = [:SRM, :fogging, :a_adapt]\n\n# Find scenarios where all metrics are above their median\nrule = y -> all(y .> 0.5)\n\n# Map input values where to their outcomes\nADRIA.sensitivity.outcome_map(X, y, rule, foi; S=20, n_boot=100, conf=0.95)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.pawn-Tuple{AbstractMatrix{<:Real}, AbstractVector{<:Real}, Vector{String}}","page":"ADRIA API","title":"ADRIA.sensitivity.pawn","text":"pawn(rs::ResultSet, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray\npawn(X::AbstractMatrix{<:Real}, y::AbstractVector{<:Real}, factor_names::Vector{String}; S::Int64=10)::NamedDimsArray\npawn(X::DataFrame, y::AbstractVector{<:Real}; S::Int64=10)::NamedDimsArray\npawn(X::NamedDimsArray, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray\npawn(X::Union{DataFrame,AbstractMatrix{<:Real}}, y::AbstractMatrix{<:Real}; S::Int64=10)::NamedDimsArray\n\nCalculates the PAWN sensitivity index.\n\nThe 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.\n\nThis 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.\n\nArguments\n\nrs : ResultSet\nX : Model inputs\ny : Model outputs\nfactor_names : Names of each factor represented by columns in X\nS : Number of slides (default: 10)\n\nReturns\n\nYAXArray, of min, mean, lower bound, median, upper bound, max, std, and cv summary statistics.\n\nExamples\n\ndom = ADRIA.load_domain(\"example_domain\")\nscens = ADRIA.sample(dom, 128)\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# Get mean coral cover over time and locations\nμ_tac = mean(ADRIA.metrics.scenario_total_cover(rs), dims=:timesteps)\n\nADRIA.sensitivity.pawn(rs, μ_tac)\n\nReferences\n\nPianosi, 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\nBaroni, G., Francke, T., 2020. GSA-cvd Combining variance- and distribution-based global sensitivity analysis https://github.com/baronig/GSA-cvd\nPuy, 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\nhttps://github.com/SAFEtoolbox/Miscellaneous/blob/main/ReviewofPuy_2020.pdf\n\nExtended help\n\nPianosi 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.\n\nPuy et al., found that the ratio of N (number of samples) to S has to be sufficiently high (NS 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 (102410 = 1024). Additionally, lower values of NS is more an indication of faulty experimental design moreso than any deficiency of the PAWN method.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.rsa-Union{Tuple{T}, Tuple{DataFrames.DataFrame, AbstractVector{T}, DataFrames.DataFrame}} where T<:Real","page":"ADRIA API","title":"ADRIA.sensitivity.rsa","text":"rsa(X::DataFrame, y::AbstractVector{<:Real}, model_spec::DataFrame; S::Int64=10)::Dataset\nrsa(r_s::YAXArray, X_q::AbstractArray, X_i::AbstractArray, y::AbstractVecOrMat{<:Real}, sel::BitVector)::YAXArray\nrsa(X::Vector{Float64}, y::AbstractVector{<:Real}, foi_spec::DataFrame; S::Int64=10)::YAXArray\nrsa(rs::ResultSet, y::AbstractVector{T}; S::Int64=10)::Dataset where {T<:Real}\nrsa(rs::ResultSet, y::AbstractVector{T}, factors::Vector{Symbol}; S::Int64=10)::Dataset where {T<:Real}\nrsa(rs::ResultSet, y::AbstractVector{T}, factor::Symbol; S::Int64=10)::YAXArray where {T<:Real}\n\nPerform Regional Sensitivity Analysis.\n\nRegional 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.\n\nThe 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.\n\nRSA can indicate where in factor space model sensitivities may be, and contributes to a Value-of-Information (VoI) analysis.\n\nIncreasing the value of S increases the granularity of the analysis, but necessitates larger sample sizes.\n\nNote: Values of type missing indicate a lack of samples in the region.\n\nArguments\n\nrs : ResultSet\nX : scenario specification\ny : scenario outcomes\nmodel_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet\nfactors : Specific model factors to examine\nS : number of bins to slice factor space into (default: 10)\n\nReturns\n\nDataset\n\nExamples\n\nADRIA.sensitivity.rsa(X, y; S=10)\n\nReferences\n\nPianosi, 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\nSaltelli, 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.tsa-Tuple{DataFrames.DataFrame, AbstractMatrix{<:Real}}","page":"ADRIA API","title":"ADRIA.sensitivity.tsa","text":"tsa(X::DataFrame, y::AbstractMatrix)::YAXArray\n\nPerform Temporal (or time-varying) Sensitivity Analysis using the PAWN sensitivity index.\n\nThe 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.\n\nExamples\n\nrs = ADRIA.load_results(\"a ResultSet of interest\")\n\n# Get scenario outcomes over time (shape: `time ⋅ scenarios`)\ny_tac = ADRIA.metrics.scenario_total_cover(rs)\n\n# Calculate sensitivity of outcome to factors for each time step\nADRIA.sensitivity.tsa(rs.inputs, y_tac)\n\nArguments\n\nX : Scenario specification\ny : scenario outcomes over time\n\nReturns\n\nYAXArray, of shape D ⋅ 6 ⋅ T, where\n\nD\nis the number of dimensions/factors\n6 corresponds to the min, mean, median, max, std, and cv of the PAWN indices\nT\nis the number of time steps\n\n\n\n\n\n","category":"method"},{"location":"API/#General-API","page":"ADRIA API","title":"General API","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA]\nOrder = [:function, :type]\nPrivate = false","category":"page"},{"location":"API/#ADRIA.coral_spec-Tuple{}","page":"ADRIA API","title":"ADRIA.coral_spec","text":"coral_spec()\n\nTemplate for coral parameter values for ADRIA. Includes \"vital\" bio/ecological parameters, to be filled with sampled or user-specified values.\n\nAny parameter added to the params DataFrame defined here will automatically be made available to the ADRIA model.\n\nNotes: Values for the historical, temporal patterns of degree heating weeks between bleaching years come from [1].\n\nReturns\n\nparams : NamedTuple[taxanames, paramnames, params], taxa names, parameter names, and parameter values for each coral taxa, group and size class\n\nReferences\n\nLough, 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\nHall, 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\nBozec, 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\nBozec, 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\nBairos-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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.create_coral_struct","page":"ADRIA API","title":"ADRIA.create_coral_struct","text":"create_coral_struct(bounds=(0.9, 1.1))\n\nGenerates Coral struct using the default parameter spec.\n\nExample\n\n# Define coral struct with auto-generated parameter ranges\n# (default in ADRIA is ± 10%, triangular distribution with peak at 0.5)\ncreate_coral_struct()\ncoral = Coral()\n\n# Recreate coral spec ± 50% from nominal values\ncreate_coral_struct((0.5, 1.5))\ncoral = Coral()\n\n\n\n\n\n","category":"function"},{"location":"API/#ADRIA.env_stats-Tuple{ADRIA.ResultSet, String, String}","page":"ADRIA API","title":"ADRIA.env_stats","text":"env_stats(rs::ResultSet, s_name::String, rcp::String)\nenv_stats(rs::ResultSet, s_name::String, rcp::String, scenario::Int)\nenv_stats(rs::ResultSet, s_name::String, stat::String, rcp::String, scenario::Int)\n\nExtract statistics for a given environmental layer (\"DHW\" or \"wave\")\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.growthODE-Tuple{Matrix{Float64}, Matrix{Float64}, NamedTuple, Real}","page":"ADRIA API","title":"ADRIA.growthODE","text":"growthODE(du, X, p, _)\n\nBase coral growth function.\n\nProportion 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.\n\nNote 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_locs), recruitment is a 6 by n_locs array.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.loc_area-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.loc_area","text":"loc_area(rs::ResultSet)::Vector{Float64}\n\nExtract vector of a location's total area in its areal unit (m², km², etc).\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.loc_area-Tuple{Domain}","page":"ADRIA API","title":"ADRIA.loc_area","text":"loc_area(domain::Domain)::Vector{Float64}\n\nGet site area for the given domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.run_scenario-Tuple{Domain, Int64, Union{DataFrames.DataFrameRow, AbstractVector}, Vector{Vector{CoralBlox.FunctionalGroup}}, NamedTuple}","page":"ADRIA API","title":"ADRIA.run_scenario","text":"run_scenario(domain::Domain, idx::Int64, scenario::Union{AbstractVector,DataFrameRow}, functional_groups::Vector{Vector{FunctionalGroup}}, data_store::NamedTuple)::Nothing\nrun_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow})::NamedTuple\nrun_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow}, RCP::String)::NamedTuple\n\nRun 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.\n\nArguments\n\ndomain : Domain\nidx : Scenario index\n\nReturns\n\nNothing\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.select-Tuple{ADRIA.ResultSet, String}","page":"ADRIA API","title":"ADRIA.select","text":"select(r::ResultSet, op::String)\n\nHacky scenario filtering - to be replaced with more robust approach.\n\nOnly supports filtering by single attribute. Should be expanded to support filtering metric results too.\n\nExamples\n\nselect(result, \"guided .> 0.0\")\n\n# Above expands to:\n# result.inputs.guided .> 0.0\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.site_k_area-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.site_k_area","text":"site_k_area(rs::ResultSet)::Vector{Float64}\n\nExtract vector of a location's coral carrying capacity in terms of absolute area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.site_k_area-Tuple{Domain}","page":"ADRIA API","title":"ADRIA.site_k_area","text":"site_k_area(domain::Domain)::Vector{Float64}\n\nGet maximum coral cover area for the given domain in absolute area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.timesteps-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.timesteps","text":"timesteps(rs::ResultSet)\n\nRetrieve the time steps represented in the result set.\n\nArguments\n\nrs : ResultSet\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.timesteps-Tuple{Domain}","page":"ADRIA API","title":"ADRIA.timesteps","text":"Extract the time steps represented in the data package.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.ADRIADomain","page":"ADRIA API","title":"ADRIA.ADRIADomain","text":"ADRIADomain{Σ,M,I,D,X,Y,Z}\n\nCore ADRIA domain. Represents study area.\n\n\n\n\n\n","category":"type"},{"location":"API/#ADRIA.Domain-Tuple{String, String, String, Vector, Vararg{String, 8}}","page":"ADRIA API","title":"ADRIA.Domain","text":"Domain(name::String, rcp::String, timeframe::Vector, location_data_fn::String, location_id_col::String, cluster_id_col::String, init_coral_fn::String, conn_path::String, dhw_fn::String, wave_fn::String, cyclone_mortality_fn::String)::Domain\n\nConvenience constructor for Domain.\n\nArguments\n\nname : Name of domain\ndpkg_path : location of data package\nrcp : RCP scenario represented\ntimeframe : Time steps represented\nlocation_data_fn : File name of spatial data used\nlocation_id_col : Column holding name of reef the location is associated with (non-unique)\ncluster_id_col : Column holding unique cluster names/ids\ninit_coral_fn : Name of file holding initial coral cover values\nconn_path : Path to directory holding connectivity data\ndhw_fn : Filename of DHW data cube in use\nwave_fn : Filename of wave data cube\ncyclone_mortality_fn : Filename of cyclone mortality data cube\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.Domain-Union{Tuple{T}, Tuple{String, String, ADRIA.EnvLayer, YAXArrays.Cubes.YAXArray{T, N, A} where {N, A<:AbstractArray{T, N}}, DataFrames.DataFrame, String, String, YAXArrays.Cubes.YAXArray, ADRIA.CoralGrowth, Vector{String}, Vector{String}, YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray}} where T<:Union{Float32, Float64}","page":"ADRIA API","title":"ADRIA.Domain","text":"Barrier function to create Domain struct without specifying Intervention/Criteria/Coral/SimConstant parameters.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.SimConstants","page":"ADRIA API","title":"ADRIA.SimConstants","text":"SimConstants\n\nStruct of simulation constants for ADRIA\n\nReferences\n\nLough, 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\nHughes, 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\nBozec, 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\nBozec, 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\n\n\n\n\n\n","category":"type"},{"location":"usage/results/#Loading-Results","page":"Loading Results","title":"Loading Results","text":"","category":"section"},{"location":"usage/results/#Loading-ReefModEngine-Results","page":"Loading Results","title":"Loading ReefModEngine Results","text":"","category":"section"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"Results from ReefModEngine.jl can be loaded with the load_results function.","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"rs = ADRIA.load_results(RMEResultSet, \"\")","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"Expected data directory structure:","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"data_dir\n│\n├───con_bin\n│ CONNECT_ACRO_2010_11.bin\n│ CONNECT_ACRO_2011_12.bin\n│ CONNECT_ACRO_2012_13.bin\n│ CONNECT_ACRO_2014_15.bin\n│ CONNECT_ACRO_2015_16.bin\n│ CONNECT_ACRO_2016_17.bin\n│\n├───id\n│ id_list_2023_03_30.csv\n│\n├───region\n│ reefmod_gbr.gpkg\n│\n└───results\n results.nc\n scenarios.csv","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"In order to reduce the duplication of geospatial and conectivity data, the data directory and results directory can be supplied seperately to avoid having copies for each resuilt set analysed.","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"rs = ADRIA.load_domain(RMEResultSet, \"\", \"\")","category":"page"},{"location":"development/building_docs/#Building-Documentation","page":"Building Documentation","title":"Building Documentation","text":"","category":"section"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"ADRIA documentation is built using Documenter.jl.","category":"page"},{"location":"development/building_docs/#Building-documentation-locally","page":"Building Documentation","title":"Building documentation locally","text":"","category":"section"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"As the documentation is build from a separate environment, it must be maintained/updated to incorporate any changes to ADRIA.","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"$ julia --project=docs\n(docs) pkg> resolve\n(docs) pkg> up","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"If no changes to the environment are necessary, simply run make.jl from the docs folder:","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"$ cd docs\n$ julia --project=. make.jl","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Locally generated documentation can be found under docs/build. Open the index.html file with any web browser.","category":"page"},{"location":"development/building_docs/#Documentation-deployment","page":"Building Documentation","title":"Documentation deployment","text":"","category":"section"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Documentation is hosted on GitHub Pages via GitHub Actions.","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Configuration is found here.","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Documentation is automatically built and deployed:","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"When a PR targeting main is submitted In this case, a preview URL is created: e.g., a URL with previews/PR### at the end, where PR### refers to the PR ID.\nOn commit/merge to main In this case the main documentation website is updated","category":"page"},{"location":"usage/analysis/#Analysis","page":"Analysis","title":"Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"This section presents tools for analysing model generate data, including functions to extract metrics and plot graphs.","category":"page"},{"location":"usage/analysis/#Setup","page":"Analysis","title":"Setup","text":"","category":"section"},{"location":"usage/analysis/#Makie","page":"Analysis","title":"Makie","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The Makie.jl ecosystem is used to produce figures.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Install additional packages if necessary","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"]add GeoMakie GraphMakie","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Install a Makie backend of your choice. WGLMakie is more flexible for our workflows, but GLMakie is a good choice too.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"]add WGLMakie","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Import additional packages and the visualization extension will compile.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"using WGLMakie, GeoMakie, GraphMakie\nusing ADRIA\nusing Statistics","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"If using GLMakie, the plots will appear in the VS Code plots pane. You may prefer figures to appear in a separate window, in which case deactivate the inline plotting feature.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Makie.inline!(false)","category":"page"},{"location":"usage/analysis/#Result-Set","page":"Analysis","title":"Result Set","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"All metrics and visualization tools presented here can be used with data generated from ADRIAmod. Following, we show usage examples considering ADRIA result set rs:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Load domain data\ndom = ADRIA.load_domain(\"path to domain data\")\n\n# Create some scenarios\nnum_samples = 4096\nscens = ADRIA.sample(dom, num_samples)\n\n# Run the model for generated scenarios\nrcp_45 = \"45\"\nrs = ADRIA.run_scenarios(dom, scens, rcp_45)\n\n# Visualize results (in terms of scenario absolute coral cover)\ns_tac = ADRIA.metrics.scenario_total_cover(rs)\nADRIA.viz.scenarios(rs, s_tac)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"See the previous sections Loading a Domain, Generating scenarios and Running scenarios for more information.","category":"page"},{"location":"usage/analysis/#Extracting-results","page":"Analysis","title":"Extracting results","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"A range of metrics are defined as part of the ADRIA framework. See the Metrics page for more details.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Here, we extract results for specific metrics for each timestep and sites for all the scenarios run. The result of each line above is a 3-dimensional Array of timesteps, sites and scenarios:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"tac = ADRIA.metrics.total_absolute_cover(rs)\nrsv = ADRIA.metrics.relative_shelter_volume(rs)\njuves = ADRIA.metrics.relative_juveniles(rs)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"We can also look at scenario-level metrics. They aggregate the above metrics across the site dimension and indicate the outcomes under a given intervention (or non-intervention) option and environmental condition.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The result is a 2-dimensional array of timesteps and scenarios:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"s_tac = ADRIA.metrics.scenario_total_cover(rs)\ns_rsv = ADRIA.metrics.scenario_rsv(rs)\ns_juves = ADRIA.metrics.scenario_relative_juveniles(rs)","category":"page"},{"location":"usage/analysis/#Visualization","page":"Analysis","title":"Visualization","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The examples below are to illustrate usage. For further information on each method of analysis, see the documentation for the given function.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Some options shared for the plots below are defined here.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Some shared options for the example plots below\nfig_opts = Dict(:size => (1600, 800))\n\n# Factors of Interest\nopts = Dict(\n :factors => [\n :RCP,\n :dhw_scenario,\n :wave_scenario,\n :guided,\n :N_seed_TA,\n :N_seed_CA,\n :fogging,\n :SRM,\n :a_adapt\n ]\n)","category":"page"},{"location":"usage/analysis/#Scenario-outcomes","page":"Analysis","title":"Scenario outcomes","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"One can plot a quick scenario overview:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"fig_s_tac = ADRIA.viz.scenarios(\n rs, s_tac; fig_opts=fig_opts, axis_opts=Dict(:ylabel => \"Scenario Total Cover\")\n)\nsave(\"scenarios_tac.png\", fig_s_tac)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Quick scenario plots)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"And compose a figure with subplots. In the example below we also use the parameter opts that accepts the keys by_RCP to group scenarios by RCP (default is false), legend to plot the legend (default is true) and summarize to plot confidence intervals instead of plotting each series (default is true):","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"tf = Figure(size=(1600, 600)) # size of figure\n\n# Implicitly create a single figure with 2 columns\nADRIA.viz.scenarios!(\n tf[1, 1],\n rs,\n s_tac;\n opts=Dict(:by_RCP => false, :legend => false),\n axis_opts=Dict(:title => \"TAC [m²]\"),\n);\nADRIA.viz.scenarios!(\n tf[1, 2],\n rs,\n s_juves;\n opts=Dict(:summarize => false),\n axis_opts=Dict(:title => \"Juveniles [%]\"),\n);\n\ntf # display the figure\nsave(\"aviz_scenario.png\", tf) # save the figure to a file","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Scenarios with subplots)","category":"page"},{"location":"usage/analysis/#Intervention-location-selection-visualisation","page":"Analysis","title":"Intervention location selection - visualisation","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Plot spatial colormaps of site selection frequencies and other available site selection metrics.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Calculate frequencies with which each site was selected at each rank\nrank_freq = ADRIA.decision.ranks_to_frequencies(\n rs.ranks[intervention=1];\n agg_func=x -> dropdims(sum(x; dims=:timesteps); dims=:timesteps),\n)\n\n# Plot 1st rank frequencies as a colormap\nrank_fig = ADRIA.viz.ranks_to_frequencies(rs, rank_freq, 1; fig_opts=Dict(:size=>(1200, 800)))\n\nsave(\"single_rank_plot.png\", rank_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Rank frequency plots for single rank)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Plot 1st, 2nd and 3rd rank frequencies as an overlayed colormap\nrank_fig = ADRIA.viz.ranks_to_frequencies(rs, rank_freq, [1, 2, 3]; fig_opts=Dict(:size=>(1200, 800)))\n\nsave(\"ranks_plot.png\", rank_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Rank frequency plots for multiple ranks)","category":"page"},{"location":"usage/analysis/#PAWN-sensitivity-(heatmap-overview)","page":"Analysis","title":"PAWN sensitivity (heatmap overview)","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The PAWN sensitivity analysis method is a moment-independent approach to Global Sensitivity Analysis. It is described as producing robust results at relatively low sample sizes, and is used to screen factors (i.e., identification of important factors) and rank factors as well (ordering factors by their relative contribution towards a given quantity of interest).","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Sensitivity (of mean scenario outcomes to factors)\nmean_s_tac = vec(mean(s_tac, dims=1))\ntac_Si = ADRIA.sensitivity.pawn(rs, mean_s_tac)\npawn_fig = ADRIA.viz.pawn(\n tac_Si;\n opts,\n fig_opts\n)\nsave(\"pawn_si.png\", pawn_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: PAWN sensitivity plots)","category":"page"},{"location":"usage/analysis/#Temporal-Sensitivity-Analysis","page":"Analysis","title":"Temporal Sensitivity Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Temporal (or Time-varying) Sensitivity Analysis applies sensitivity analysis to model outputs over time. The relative importance of factors and their influence on outputs over time can then be examined through this analysis.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"tsa_s = ADRIA.sensitivity.tsa(rs, s_tac)\ntsa_fig = ADRIA.viz.tsa(\n rs,\n tsa_s;\n opts,\n fig_opts\n)\nsave(\"tsa.png\", tsa_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Temporal Sensitivities)","category":"page"},{"location":"usage/analysis/#Convergence-Analysis","page":"Analysis","title":"Convergence Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"When undertaking sensitivity analysis it is important to have a sufficient number of samples such that the sensitivity measure converges to a stable state. To assess whether sufficient samples have been taken a convergence analysis can be conducted. One approach is to draw a large sample and then iteratively assess stability of the sensitivity metric using an increasing number of sub-samples. The sensitivity metric is described as having \"converged\" if there is little to no fluctuations/variance for a given sample size. The analysis can help determine if too little (or too many) samples have taken for the purpose of sensitivity analysis.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The function sensitivity.convergence can be used to calculate a sensitivity measure for an increasing number of samples. The result can then be plotted as band plots or a heat map using viz.convergence.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"outcome = dropdims(mean(ADRIA.metrics.scenario_total_cover(rs); dims=:timesteps), dims=:timesteps)\n\n# Display convergence for specific factors of interest (\"foi\") within a single figure.\n# Bands represent the 95% confidence interval derived from the number of conditioning\n# points, the default for which is ten (i.e., 10 samples).\n# Due to the limited sample size, care should be taken when interpreting the figure.\nfoi = [:dhw_scenario, :wave_scenario, :guided]\nSi_conv = ADRIA.sensitivity.convergence(scens, outcome, foi)\nconv_series_fig = ADRIA.viz.convergence(Si_conv, foi)\nsave(\"convergence_factors_series.png\", conv_series_fig)\n\n# Convergence analysis of factors grouped by model component as a heat map\ncomponents = [:EnvironmentalLayer, :Intervention, :Coral]\nSi_conv = ADRIA.sensitivity.convergence(rs, scens, outcome, components)\nconv_hm_fig = ADRIA.viz.convergence(Si_conv, components; opts=Dict(:viz_type=>:heatmap))\nsave(\"convergence_components_heatmap.png\", conv_hm_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Convergence analysis of factors overlayed) (Image: Grouped convergence analysis)","category":"page"},{"location":"usage/analysis/#Time-Series-Clustering","page":"Analysis","title":"Time Series Clustering","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The Time Series Clustering algorithm clusters together series (typically time series) with similar behavior. This is achieved by computing the Euclidian distance between each pair of series weighted by a correlation factor that takes into account the quotient between their complexities. When plotting clustered_scenarios, the kwarg opts can be used with the key :summarize to plot the confidence intervals of each cluster instead of each series individually (default is true).","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Extract metric from scenarios\ns_tac = ADRIA.metrics.scenario_total_cover(rs)\n\n# Cluster scenarios\nn_clusters = 4\nclusters = ADRIA.analysis.cluster_scenarios(s_tac, n_clusters)\n\naxis_opts = Dict(\n :title => \"Time Series Clustering with $n_clusters clusters\",\n :ylabel => \"TAC [m²]\",\n :xlabel => \"Timesteps [years]\",\n)\n\ntsc_fig = ADRIA.viz.clustered_scenarios(\n s_tac, clusters; opts=Dict(:summarize => true), fig_opts=fig_opts, axis_opts=axis_opts\n)\n\n# Save final figure\nsave(\"tsc.png\", tsc_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Time Series Cluster)","category":"page"},{"location":"usage/analysis/#Target-clusters","page":"Analysis","title":"Target clusters","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"One can also target scenarios that belong to specific clusters (like clusters with higher median value for some outcome):","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Extract metric from scenarios\nasv = ADRIA.metrics.absolute_shelter_volume(rs)\n\n# Time series summarizing scenarios for each site\nasv_site_series = ADRIA.metrics.loc_trajectory(median, asv)\n\n# Cluster scenarios\nn_clusters = 6\nasv_clusters = ADRIA.analysis.cluster_scenarios(asv_site_series, n_clusters)\n\n# Target scenarios that belong to the two lowest value clusters\nlowest = x -> x .∈ [sort(x; rev=true)[1:2]]\nasv_target = ADRIA.analysis.find_scenarios(asv_site_series, asv_clusters, lowest)\n\n# Plot targeted scenarios\naxis_opts = Dict(:ylabel => \"Absolute Shelter Volume\", :xlabel => \"Timesteps [years]\")\n\ntsc_asc_fig = ADRIA.viz.clustered_scenarios(\n asv_site_series, asv_target; axis_opts=axis_opts, fig_opts=fig_opts\n)\n\n# Save final figure\nsave(\"tsc_asv.png\", tsc_asc_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of targeted lowest clusters)","category":"page"},{"location":"usage/analysis/#Multiple-Time-Series-Clustering","page":"Analysis","title":"Multiple Time Series Clustering","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"It is possible to perform time series clustering for different metric outcomes and find scenarios that behave the same across all of them. Currently there is no visualization function for this.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"metrics::Vector{ADRIA.metrics.Metric} = [\n ADRIA.metrics.scenario_total_cover,\n ADRIA.metrics.scenario_asv,\n ADRIA.metrics.scenario_absolute_juveniles,\n]\n\noutcomes = ADRIA.metrics.scenario_outcomes(rs, metrics)\nn_clusters = 6\n\n# Clusters matrix\noutcomes_clusters::AbstractMatrix{Int64} = ADRIA.analysis.cluster_scenarios(\n outcomes, n_clusters\n)\n\n# Filter scenarios that belong to on of the 4 high value clusters for all outcomes\nhighest_clusters(x) = x .∈ [sort(x; rev=true)[1:4]]\nrobust_scens = ADRIA.analysis.find_scenarios(outcomes, outcomes_clusters, highest_clusters)","category":"page"},{"location":"usage/analysis/#Time-Series-Clustering-Map","page":"Analysis","title":"Time Series Clustering Map","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"When using Time Series Clustering to cluster among multiple locations using some metric, it is possible to visualize the result as a map.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Extract metric from scenarios\ntac = ADRIA.metrics.total_absolute_cover(rs)\n\n# Get a timeseries summarizing the scenarios for each site\ntac_site_series = ADRIA.metrics.loc_trajectory(median, tac)\n\n# Cluster scenarios\nn_clusters = 6\nclusters = ADRIA.analysis.cluster_scenarios(tac_site_series, n_clusters)\n\n# Get a vector summarizing the scenarios and timesteps for each site\ntac_sites = ADRIA.metrics.per_loc(median, tac)\n\n# Plot figure\ntsc_map_fig = ADRIA.viz.map(rs, tac_sites, clusters)\n\n# Save final figure\nsave(\"tsc_map.png\", tsc_map_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Spatial Time Series Clusters)","category":"page"},{"location":"usage/analysis/#Rule-Induction-(using-Series-Clusters)","page":"Analysis","title":"Rule Induction (using Series Clusters)","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"After clustering, it is possible to target some specific scenarios based on each cluster median outcome temporal variability:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Find Time Series Clusters\ns_tac = ADRIA.metrics.scenario_total_cover(rs)\nnum_clusters = 6\nclusters = ADRIA.analysis.cluster_scenarios(s_tac, num_clusters)\n\n# Target scenarios\ntarget_clusters = ADRIA.analysis.target_clusters(clusters, s_tac)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Using this vector if target clusters, together with the parameters used to generate each scenario, it is possible to use a Rule Induction algorithm (SIRUS) and plot each extracted rule as a scatter graph:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Select only desired features\nfields_iv = ADRIA.component_params(rs, [Intervention, CriteriaWeights]).fieldname\nscenarios_iv = scens[:, fields_iv]\n\n# Use SIRUS algorithm to extract rules\nmax_rules = 10\nrules_iv = ADRIA.analysis.cluster_rules(target_clusters, scenarios_iv, max_rules)\n\n# Plot scatters for each rule highlighting the area selected them\nrules_scatter_fig = ADRIA.viz.rules_scatter(\n rs,\n scenarios_iv,\n target_clusters,\n rules_iv;\n fig_opts=fig_opts,\n opts=opts\n)\n\n# Save final figure\nsave(\"rules_scatter.png\", rules_scatter_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Rule Induction)","category":"page"},{"location":"usage/analysis/#Regional-Sensitivity-Analysis","page":"Analysis","title":"Regional Sensitivity Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Regional Sensitivity Analysis is a monte-carlo filtering approach. The aim of RSA is to aid in identifying which (group of) factors drive model outputs and their active areas of factor space.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"mean_s_tac = dropdims(mean(s_tac), dims=1)\n\ntac_rs = ADRIA.sensitivity.rsa(rs, mean_s_tac; S=10)\nrsa_fig = ADRIA.viz.rsa(\n rs,\n tac_rs,\n [:dhw_scenario, :wave_scenario, :N_seed_TA, :N_seed_CA, :fogging, :SRM];\n opts,\n fig_opts\n)\n\nsave(\"rsa.png\", rsa_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Regional Sensitivities)","category":"page"},{"location":"usage/analysis/#Outcome-mapping","page":"Analysis","title":"Outcome mapping","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"A monte-carlo filtering approach similar to Regional Sensitivity Analysis.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"As the name implies, outcome mapping aids in identifying the relationship between model outputs and the region of factor space that led to those outputs.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"mean_s_tac = dropdims(mean(s_tac), dims=1)\n\ntf = Figure(size=(1600, 1200)) # size of figure\n\n# Indicate factor values that are in the top 50 percentile\ntac_top_50 = ADRIA.sensitivity.outcome_map(rs, mean_s_tac, x -> any(x .>= 0.5), foi; S=20)\nADRIA.viz.outcome_map!(\n tf[1, 1],\n rs,\n tac_top_50,\n foi;\n axis_opts=Dict(:title => \"Regions which lead to Top 50th Percentile Outcomes\", :ylabel => \"TAC [m²]\")\n)\n\n# Indicate factor values that are in the top 30 percentile\ntac_top_30 = ADRIA.sensitivity.outcome_map(rs, mean_s_tac, x -> any(x .>= 0.7), foi; S=20)\nADRIA.viz.outcome_map!(\n tf[2, 1],\n rs,\n tac_top_30,\n foi;\n axis_opts=Dict(:title => \"Regions which lead to Top 30th Percentile Outcomes\", :ylabel => \"TAC [m²]\"))\n\nsave(\"outcome_map.png\", tf)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Outcome mapping)","category":"page"},{"location":"usage/analysis/#GUI-for-high-level-exploration-(prototype-only!)","page":"Analysis","title":"GUI for high-level exploration (prototype only!)","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# To explore results interactively\nADRIA.viz.explore(\"path to Result Set\")\n\n# or, if the result set is already loaded:\n# ADRIA.viz.explore(rs)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Standalone app for data exploration)","category":"page"},{"location":"#Introduction","page":"Introduction","title":"Introduction","text":"","category":"section"},{"location":"#What-is-ADRIA.jl?","page":"Introduction","title":"What is ADRIA.jl?","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"ADRIA is a decision support platform for informing reef restoration and adaptation interventions through scenario exploration and analysis, decision heuristics (MCDA), alongside a small coral ecosystem model.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Among the most common usecases are:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Running a number of scenarios under different environmental and intervention conditions (see Loading a Domain, Generating scenarios and Running scenarios);\nExtracting metrics for each scenario and timestep such as coral cover, shelter volume or number of juveniles (see Metrics);\nUsing these metrics to perform a range of analyses like time series clustering (grouping together scenarios with similar temporal behaviour; see Analysis);\nUsing the visualization tools to plot some of the mentioned metrics or analysis (see Analysis);","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"More details about each of these can be found in the next sections.","category":"page"},{"location":"#Docker-documentation","page":"Introduction","title":"Docker documentation","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"ADRIA.jl features a set of Docker build targets which allow usage, development and experimentation of the ADRIA Julia package. See ADRIA Docker Setup for more information.","category":"page"},{"location":"#Troubleshooting-F.A.Q","page":"Introduction","title":"Troubleshooting F.A.Q","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"ADRIA.jl is under active development and from time to time issues may arise. Here are some answers to some issues encountered.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Q. I get this warning when trying to load pre-existing results: Results were produced with a different version of ADRIA (v0.x.x). The installed version of ADRIA is: v0.y.y. Errors may occur when analyzing data. (where x and y are different numbers).","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"A. The result set being loaded were generated by a different version of ADRIA, and in a possibly incompatible format. Sometimes, results may still be produced/analyzed as normal. In other times, ADRIA.jl or the expected metadata in the result set may have changed leading to errors when conducting analyses.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Either go back to the version indicated, or re-run the scenarios to obtain results in the updated format.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Q. I get an error or warning about an ENV variable not being found or set.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"A. Double check the configuration settings in config.toml (see above).","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Q. How do I run my own scenarios?","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"A. Scenarios are defined in a CSV file (with parameter values in columns, so that each row defines a scenario).","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"See the example_scenarios.csv file in the ADRIA data specification repository for an idea of what this looks like.\nSee Extracting model details example in Cookbook examples on how to extract the model specification and parameter table for a given domain.\nSee also the Generating and running scenarios example in Cookbook examples which showcases how to run such a file for a given study area.","category":"page"},{"location":"usage/scenario_discovery/#Scenario-Discovery","page":"Scenario Discovery","title":"Scenario Discovery","text":"","category":"section"},{"location":"usage/scenario_discovery/","page":"Scenario Discovery","title":"Scenario Discovery","text":"using ADRIA\n\ndom = ADRIA.load_domain(\"...\")\nscens = ADRIA.sample(dom, 4096)\n\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n# rs = ADRIA.load_results(\"...\")\n\n# Calculate representative statistic for all metrics of interest\n# Here, total cover, shelter volume and juvenile population\ntac = ADRIA.metrics.scenario_total_cover(rs)\nmean_tac = vec(mean(tac, dims=1))\n\nrsv = ADRIA.metrics.scenario_rsv(rs)\nmean_sv = vec(mean(rsv, dims=1))\n\nr_juves = ADRIA.metrics.scenario_relative_juveniles(rs)\nmean_juves = vec(mean(r_juves, dims=1))\n\n# Create matrix of all metrics\ny = hcat(mean_tac, mean_sv, mean_juves)\n\n# Define \"robust scenario\" as one where all metric outcomes >= 30th percentile.\nrule_func = x -> all(x .>= 0.3)\n\n# Identify robust scenarios for a specific RCP (4.5)\nrobust = ADRIA.analysis.find_robust(rs, y, rule_func, [45])\n\n# Output robust scenario IDs\n@info robust.RCP45\n\n# Could qualitatively examine inputs that led to robust scenarios ...\nrs.inputs[robust.RCP45, :]\n\n# ... or mark behavioural and non-behavioural outcomes for further analysis\n# e.g., with random forest.\nbehave = zeros(size(y, 1))\nbehave[robust.RCP45] .= 1.0\n\n# Next step is to test these for robustness across environmental conditions ...\n# [TODO]","category":"page"}] +[{"location":"development/docker/#ADRIA-Docker-Setup","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This repo contains a multistage Dockerfile for generating containerised applications based on the ADRIA source code in this repository.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"docker configuration\nadria-base\nA note about platform build targets\nPublished base images\nBuilding adria-base\nRunning adria-base with a non-interactive Julia command\nRunning adria-base as an interactive Julia shell\nRunning adria-base with a non-Julia entrypoint\nDeriving an image from adria-base\nadria-dev\nBuilding adria-dev\nRunning adria-dev as an interactive Julia shell\nRunning ADRIA tests with adria-dev\nadria-sandbox\nBuilding adria-sandbox\nRunning adria-sandbox\nInteracting with adria-sandbox","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#Docker-configuration","page":"ADRIA Docker Setup","title":"Docker configuration","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The following build args and defaults are available to configure the build behaviour.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"ARG SANDBOX_FROM=\"adria-dev\": What base image should be used for the sandbox\nARG ADRIA_VERSION=\"0.11.0\": What version of ADRIA from package registry to install in adria-base\nARG JULIA_VERSION=\"1.10.4\": See https://hub.docker.com/*/julia for valid versions.","category":"page"},{"location":"development/docker/#adria-base","page":"ADRIA Docker Setup","title":"adria-base","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-base image variant is a Julia image with ADRIA.jl installed to a shared environment that is included in the Julia LOAD_PATH directly from it's github origin.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The Docker entrypoint for the adria-base image is the julia binary, so you can run just this base container if you want to invoke julia commands, including commands that depend on the ADRIA package being installed.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"It can also be used as a base-image for any Julia application that needs to use ADRIA.","category":"page"},{"location":"development/docker/#A-note-about-platform-build-targets","page":"ADRIA Docker Setup","title":"A note about platform build targets","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This line in the Dockerfile prompts Julia to precompile the ADRIA package and it's predependencies for a larger range of target platforms. Given that the building of the image could occur on any host, we need to specify a range of platforms so that precompilation (which is CPU architecture dependent) does not need to reoccur when the Docker image is run on the user's system.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The below list came from here and is confirmed to work for a x86_64 based architecture.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# Try to coerce Julia to build across multiple targets\nENV JULIA_CPU_TARGET=x86_64;haswell;skylake;skylake-avx512;tigerlake","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"If more platforms are needing to be targeted, please lodge a pull request with the output of uname -m and other details, and we can expand this list of target platforms.","category":"page"},{"location":"development/docker/#Published-base-images","page":"ADRIA Docker Setup","title":"Published base images","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This repository uses GitHub actions to publish, upon version release, the adria-base image - see .github/workflows/PublishDockerImage.yml. The below commands such as running and using the ADRIA base image apply to these published images, replacing your locally tagged image with the GitHub Container Registry label e.g. the following will run in an interactive Julia shell, a precompiled terminal with ADRIA installed, ready to be used.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"docker run --tty --interactive ghcr.io/open-aims/adria.jl/adria-base:latest","category":"page"},{"location":"development/docker/#Building-adria-base","page":"ADRIA Docker Setup","title":"Building adria-base","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose build adria-base\n\n# OR using just `docker build`:\ndocker build --target \"adria-base\" --tag ADRIA.jl/adria-base:latest .","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"You can also opt to specify some custom build arguments to change the versions of Julia or ADRIA.jl that get installed. Supported arguments are:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"ADRIA_REPO: URL for the repository that ADRIA.jl should be cloned from. Defaults to https://github.com/open-AIMS/ADRIA.jl.git\nADRIA_REFSPEC: the branch-name or tag of the ADRIA_REPO that you want to install. Defaults to main.\nJULIA_VERSION: The version of the Julia platform you want to install ADRIA.jl into. This must be one of the versions available for the official Julia base image. Defaults to 1.10.1.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"See the docker-compose.yaml file for an example of how to specify build arguments in docker compose.","category":"page"},{"location":"development/docker/#Running-adria-base-with-a-non-interactive-Julia-command","page":"ADRIA Docker Setup","title":"Running adria-base with a non-interactive Julia command","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"e.g. to list the packages installed in the @adria shared environment:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-base --project=@adria -e 'using Pkg; Pkg.status()'\n\n# OR using just docker run:\ndocker run --rm ADRIA.jl/adria-base:latest --project=@adria -e 'using Pkg; Pkg.status()'","category":"page"},{"location":"development/docker/#Running-adria-base-as-an-interactive-Julia-shell","page":"ADRIA Docker Setup","title":"Running adria-base as an interactive Julia shell","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"To launch an interactive Julia shell:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-base\n\n# OR using just docker run:\ndocker run --rm --interactive --tty ADRIA.jl/adria-base:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In both cases, type CTRL-d to exit the shell and stop the container.","category":"page"},{"location":"development/docker/#Running-adria-base-with-a-non-Julia-entrypoint","page":"ADRIA Docker Setup","title":"Running adria-base with a non-Julia entrypoint","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"If you want to use this image to run something other than a Julia command, you can specify an alternate entrypoint at runtime as well as an alternate command. e.g. to launch an interactive bash shell in the container for checking filesystem permissions or similar:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm --entrypoint /bin/bash adria-base\n\n# OR using just docker run:\ndocker run --rm --interactive --tty --entrypoint /bin/bash ADRIA.jl/adria-base:latest","category":"page"},{"location":"development/docker/#Deriving-an-image-from-adria-base","page":"ADRIA Docker Setup","title":"Deriving an image from adria-base","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"To make a derived ADRIA application:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"Use FROM ADRIA.jl/adria-base:latest (or a related tag)\nInclude a CMD line in your Dockerfile that provides appropriate arguments to the julia command line to invoke your application.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The section of the Dockerfile that defines the adria-sandbox target described below might be useful inspiration.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#adria-dev","page":"ADRIA Docker Setup","title":"adria-dev","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-dev image variant is an alternative to the adria-base image, not a derived application. Instead of installing ADRIA.jl as a normal package, it looks for the ADRIA.jl source code in a local subdirectory, and installs that as a Julia development package.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This allows you to use the adria-dev container as an ADRIA.jl development environment: you can run tests, bind-mount and edit the code, re-resolve dependencies and all sorts of other useful things without needing to a native installation of Julia.","category":"page"},{"location":"development/docker/#Building-adria-dev","page":"ADRIA Docker Setup","title":"Building adria-dev","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"From within the root of the ADRIA.jl project, you can build the adria-dev image like so:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose build adria-dev\n\n# OR using just `docker build`:\ndocker build --target \"adria-dev\" --tag ADRIA.jl/adria-dev:latest .","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The same JULIA_VERSION build argument that works with adria-base will also work with adria-dev.","category":"page"},{"location":"development/docker/#Running-adria-dev-as-an-interactive-Julia-shell","page":"ADRIA Docker Setup","title":"Running adria-dev as an interactive Julia shell","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"Very useful for running commands to update Package manifests and similar! The command will activate the shared @adria environment by default, but you can switch to any other environment as you need to.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-dev\n\n# OR using just docker run:\ndocker run --rm --interactive --tty \\\n --mount type=bind,source=\"$(pwd)\"/ADRIA.jl/,target=/usr/local/src/adria/\n ADRIA.jl/adria-dev:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In both cases, type CTRL-d to exit the shell and stop the container.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#Running-ADRIA-tests-with-adria-dev","page":"ADRIA Docker Setup","title":"Running ADRIA tests with adria-dev","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"ADRIA tests can be run like any other Julia command, but the GOTCHA is that they need to run in the local project environment, NOT in the shared @adria environment:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm adria-dev --project=. -e 'using Pkg; Pkg.test();'\n\n# OR using just docker run:\ndocker run --rm ADRIA.jl/adria-dev:latest --project=. -e 'using Pkg; Pkg.test();'","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This method of running tests is suitable to use in a containerised continuous integration pipeline.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"","category":"page"},{"location":"development/docker/#adria-sandbox","page":"ADRIA Docker Setup","title":"adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-sandbox image variant is set up to run the sandbox Julia application which has its source code in this repository.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This application uses the pre-installed ADRIA package, and can be built on either of adria-base or adria-dev, depending on whether you want the development version of the package or not.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"It depends on input and output data files which must be provided at runtime.","category":"page"},{"location":"development/docker/#Building-adria-sandbox","page":"ADRIA Docker Setup","title":"Building adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The sandbox build supports an optional SANDBOX_FROM build argument which is used to specify a base image. Supported values are adria-dev (the default) or adria-base.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose (edit the compose file to specify which base image to use):\ndocker compose build adria-sandbox\n\n# OR using just `docker build`:\ndocker build --build-arg SANDBOX_FROM=adria-dev --target \"adria-sandbox\" --tag ADRIA.jl/adria-sandbox:latest .","category":"page"},{"location":"development/docker/#Running-adria-sandbox","page":"ADRIA Docker Setup","title":"Running adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The adria-sandbox image is configured to automatically run the dev.jl script when a container made from that image runs.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"For that script to be useful, though, you must first mount two filesystem locations to the container:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"A directory containing your input data files should be mounted at /data/input\nA directory where the sandbox application can create output files should be mounted at /data/output","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"This documentation and the docker-compose.yaml file in the repository demonstrate using bind mounts to data-directories which are local to your current working directory for this purpose, but docker volumes with any supported storage driver should also work fine.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose (which has the bind-mounts predefined):\ndocker compose up adria-sandbox\n\n# OR using docker run:\ndocker run --rm \\\n --mount type=bind,source=\"$(pwd)\"/input,target=/data/input \\\n --mount type=bind,source=\"$(pwd)\"/output,target=/data/output \\\n ADRIA.jl/adria-sandbox:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"The dev.jl script should run with any files you have provided in your input volume, and will create and output files in your output volume. The container will be removed once the script completes.","category":"page"},{"location":"development/docker/#Interacting-with-adria-sandbox","page":"ADRIA Docker Setup","title":"Interacting with adria-sandbox","text":"","category":"section"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"If you prefer to work with the sandbox code from an interactive shell, then you will need to override the default entrypoint and command combination to make the container launch your preferred shell at startup.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In this case, you may also like to bind-mount your sandbox and/or ADRIA.jl source code into the container, so that you can edit it without having to re-build the container each time.","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"e.g. to launch the sandbox container as a development environment with an interactive bash shell and use:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"# EITHER using docker compose:\ndocker compose run --rm --entrypoint /bin/bash adria-sandbox\n\n# OR using just docker run:\ndocker run --rm --interactive --tty --entrypoint /bin/bash \\\n --mount type=bind,source=\"$(pwd)\"/input,target=/data/input \\\n --mount type=bind,source=\"$(pwd)\"/output,target=/data/output \\\n --mount type=bind,source=\"$(pwd)\"/sandbox,target=/opt/adria-sandbox/src \\\n --mount type=bind,source=\"$(pwd)\"/ADRIA.jl,target=/usr/local/src/adria \\\n ADRIA.jl/adria-sandbox:latest","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"In both cases, the initial working directory will be the installation-location for the sandbox application's source code, and you can invoke any command you like from that shell prompt, e.g:","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"julia --project=@. dev.jl","category":"page"},{"location":"development/docker/","page":"ADRIA Docker Setup","title":"ADRIA Docker Setup","text":"Warning: For julia commands, you will probably need to use the --project=@. argument. This tells Julia that it's working environment is based in a parent directory of the one the sandbox source code is installed to, which is where the build configured all the precompiled dependencies. If you omit this, the pre-installed packages may not all be available.","category":"page"},{"location":"synopsis/#Synopsis","page":"Synopsis","title":"Synopsis","text":"","category":"section"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"Climate change is transforming coral reefs. Continued climate change has scope to erode reef biodiversity, key ecosystem functions, and the ecosystem services they provide for people. Conventional management strategies remain essential but will not be sufficient on their own to sustain coral reefs in a warming and acidifying ocean. New interventions are increasingly being considered, including assisted gene flow, cooling and shading, and reef structures that provide reef habitats and substrates for enhanced recruitment.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"Deciding where, when, and how to intervene – if at all - using new reef restoration and adaptation measures is challenging on at least three fronts.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"are new interventions likely to create more benefits than damage? And if so, whom do they benefit, or pose risks to, and at what spatial and temporal scales?\nwhich interventions, individually and in combination, represent solutions that provide the highest return on investment for reef, people, and industries?\nwhich R&D paths and deployment strategies represent optimal solutions given multiple key objectives, trade-offs, and limited time, resources, and logistical constraints?","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"To help reef modellers, decision-support teams and reef managers address these questions, AIMS has developed the Adaptive, Dynamic Reef Intervention Algorithm (ADRIA). In short, ADRIA simulates a reef decision maker operating inside the dynamic state space of a coral reef.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"For reef managers, ADRIA help provide line of sight to conservation solutions in complex settings where multiple objectives need to be considered. For investors, ADRIA helps analysts identify which options (R&D and/or deployment solutions) might have the highest likelihood of providing ecological and social returns on investment across a range of considered environmental conditions. While ADRIA’s key function is as a decision-support tool for intervention deployment, it uses a simple proxy model for reef coral dynamics, consisting of vital rates parameterised in a set of linked differential equations for four coral groups. The growth, mortality and recruitment of those four coral groups are further parameterised by environmental drivers and by different restoration and adaptation interventions.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"The primary purpose of ADRIA is to help guide intervention deployment such that net benefits are maximised against primary objectives and minimised against costs. Solutions can be tuned (eventually optimised) via heuristics that control the selection of sites and/or reefs and the prioritisation of species, ecosystem services or benefits that favour what people (society) want. The key benefits considered in ADRIA are consistent with a triple-bottom-line approach, i.e.","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"ecological (e.g. biodiversity),\neconomic (e.g. tourism and fisheries values) and\nsocial and cultural (e.g. recreation and supporting identities).","category":"page"},{"location":"synopsis/","page":"Synopsis","title":"Synopsis","text":"The guiding principles for decision support in ADRIA are currently a set of dynamic Multi-Criteria Decision Analyses (dMCDA) applied at each time step. Criteria in the model are a composite of spatial environmental variables (risk from wave damage, thermal stress, and water quality) and ecological information (coral cover, substrate availability).","category":"page"},{"location":"development/development_setup/#Development-setup","page":"Development setup","title":"Development setup","text":"","category":"section"},{"location":"development/development_setup/#Install-Julia","page":"Development setup","title":"Install Julia","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Install Julia if not already done so, preferably using juliaup.","category":"page"},{"location":"development/development_setup/#Windows","page":"Development setup","title":"Windows","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"There may be issues installing juliaup from the Windows Store (or otherwise undesirable). In such cases, use the alternate MSIX App installer (https://install.julialang.org/Julia.appinstaller)","category":"page"},{"location":"development/development_setup/#Recommendations","page":"Development setup","title":"Recommendations","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"It is recommended that the juliaup tool be used to ease managing Julia versions.\nWe recommend VS Code with its Julia extension when developing ADRIA.\nInstall the VS Code Julia Formatter extension (note: not the JuliaFormatter.jl package).\nWe also recommend the built-in Julia REPL within VS Code be used (see the notes below).","category":"page"},{"location":"development/development_setup/#Initial-Setup","page":"Development setup","title":"Initial Setup","text":"","category":"section"},{"location":"development/development_setup/#Using-the-console","page":"Development setup","title":"Using the console","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Once Julia is installed, clone the ADRIA.jl repository and navigate to the project folder:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ git clone git@github.com:open-AIMS/ADRIA.jl.git\n$ cd ./ADRIA.jl","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Start Julia specifying the current directory as the project environment:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ julia --project=.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Switch to the package manager (]) and instantiate the project. This only needs to be done once.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"julia> ]\n(ADRIA.jl) pkg> instantiate","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"This will sets up the project packages.","category":"page"},{"location":"development/development_setup/#Sandbox","page":"Development setup","title":"Sandbox","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"For development purposes, set up a sandbox environment (setup only needs to be done once). This environment will function as a project apart from ADRIA, where you can install any packages, including ADRIA.jl, and run your code. When installing ADRIA.jl at the sandbox, use the dev command instead of add. For more information, please refer to Pkg.jl documentation.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Once you are inside ADRIA.jl project folder, create a folder named sandbox and start julia inside it:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ mkdir sandbox\n$ cd sandbox\n$ julia --project=.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Switch to the package manager (]) and add ADRIA.jl as a local package under development","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"julia> ]\n(sandbox) pkg> dev ../","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"You may also install additional packages for visualizations and debugging tools","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"(sandbox) pkg> add GLMakie GeoMakie GraphMakie\n(sandbox) pkg> add Revise Infiltrator BenchmarkTools JET","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Press backspace or Ctrl+C to leave the package manager.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Development scripts/functions can now be worked on in the sandbox folder, and its sub-folders, without these polluting the ADRIA project itself.","category":"page"},{"location":"development/development_setup/#Testing","page":"Development setup","title":"Testing","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"To run the full test suite, rebuilding the environment as necessary:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"$ julia --project=.\njulia> ]test","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Rebuilding the environment can be unnecessary for every test run during development. It such cases, include() the runtests.jl file directly.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"# Assuming the current working directory is the project root.\n# Adjust the filepath as necessary if this is not the case.\ninclude(\"test/runtests.jl\")","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If a specific test case is being run, write the test file to be a standalone script (importing all necessary packages, including Test) and run it directly.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Doing so allows use of debugging packages if necessary.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"include(\"test/some_test_file.jl\")","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Once the test is complete, put the tests in a testset as and if required. If a new file is added to the test suite, include() it in test/runtests.jl","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"See the Test documentation for further details.","category":"page"},{"location":"development/development_setup/#Code-Style","page":"Development setup","title":"Code Style","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"We are currently moving to follow Blue Style Guide. All PRs should follow this style guide. The julia-format GitHub workflow will check that your PR's code is formatted. Note that this check requires all code in the repo to be formatted, not only the files modified by your PR.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Use the VSCode Format Document or Format Selection actions to format your code.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"To reformat the entire project:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"using JuliaFormatter\nformat(\".\")","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If this returns false, call format() again.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Formatter configuration is defined in .JuliaFormatter.toml, see JuliaFormatter docs.","category":"page"},{"location":"development/development_setup/#VSCode-Settings","page":"Development setup","title":"VSCode Settings","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Open Settings (Ctrl+,). Search for trim and ensure the following options are all ticked/enabled:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Files: Trim Final Newlines\nFiles: Trim Trailing Whitespace\nEditor: Trim Auto Whitespace","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"An optional, but recommended, step would be to add a ruler guide to indicate where the character limit/width is.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Search for rulers and click on \"Edit in settings.json\" under \"Editor: Rulers\"","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Add \"92\" to the list of ruler lengths, such that the editor.rulers entry looks like this:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"\"editor.rulers\": [\n 92\n ]","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Adding multiple values adds more guide lines at the indicated widths.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Important: if you installed the oh7z Julia Formatter VSCode extension, uninstall or disable it for this workspace. That extension always uses its formatter settings and does not support .JuliaFormatter.toml whereas the main Julia extension does. The only reason to use the oh7z extension is for Julia projects that do not have a .JuliaFormatter.toml file.","category":"page"},{"location":"development/development_setup/#Git-blame-ignore-revs","page":"Development setup","title":"Git blame ignore revs","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If you have GitLens (or similar extension), it will show the author of a line of code using git blame. To ignore commits like \"re-format entire project\", run this once:","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"git config --local blame.ignoreRevsFile .git-blame-ignore-revs","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"If you reformat code and want to ignore that commit, simply add the commit SHA to the .git-blame-ignore-revs file.","category":"page"},{"location":"development/development_setup/#Notes","page":"Development setup","title":"Notes","text":"","category":"section"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"The very first import of the ADRIA package will be very slow as it attempts to precompile common functions to reduce later start up time. The same applies when running ADRIA for the first time. This slow initial precompilation has to be repeated if the package is modified, but will remain \"fast\" if no changes are made.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Use the Revise package to avoid having to repeatedly restart the REPL to incorporate code changes. By default, the VS Code REPL will auto-load this package.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"A custom sysimage can also be created to reduce start up times.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"VS Code now has (experimental) support for generating a custom sysimage for its REPL. Prior to Julia v1.9, a custom sysimage for the development/sandbox environment was highly recommended. Julia v1.9 introduced an improved precompilation process and the concept of extension packages. As many packages are still in the process of taking advantage of these changes, the sysimage may not successfully build. Given precompilation is now much faster than previously, the sysimage can be considered to be a \"nice to have\".","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"The same caveats as above apply: the sysimage has to be recreated if the project specification (e.g., expected package dependencies) changes.","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"See: This guide","category":"page"},{"location":"development/development_setup/","page":"Development setup","title":"Development setup","text":"Otherwise, if the VS Code build task cannot be used, see the documentation here for a quick how to. Note: compilation time to create a sysimage can be upwards of 15mins and, again, has to be repeated if the project packages are updated.","category":"page"},{"location":"usage/cookbook/#Cookbook-examples","page":"Cookbook examples","title":"Cookbook examples","text":"","category":"section"},{"location":"usage/cookbook/#Extracting-model-details","page":"Cookbook examples","title":"Extracting model details","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"Example showcasing how to extract model details, such as:","category":"page"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"the model parameter table\nmodel specification","category":"page"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"and more specific information/data from the above.","category":"page"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using DataFrames\nusing ADRIA\n\n\n# Loading a dataset for a study area (a \"domain\")\ndata_pkg = \"./Example_domain\"\ndom = ADRIA.load_domain(data_pkg, 45)\n\n# Get current parameter table (fieldnames and their values)\nparam_df = ADRIA.param_table(dom)\n\n# Get model specification with lower/upper bounds separated\nmodel_spec = ADRIA.model_spec(dom)\n\n# Export model specification to CSV\nADRIA.model_spec(dom, \"model_spec.csv\")\n\n\n# Get parameter details\n\n## Parameter names\np_names = dom.model[:fieldname]\n\n## Current values\np_vals = dom.model[:val]\n\n## ADRIA parameter types\np_types = dom.model[:ptype]\n\n## Parameter bounds (for e.g., to pass into a sampler or optimizer)\n## Note: ADRIA integer parameter bounds are set such that ℓ ≤ x ≤ u+1,\n## where ℓ is the lower bound and u is the upper bound.\n## This is because `floor(x)` is assigned with `update_params!()`.\n## Instances where ℓ := x := u indicate uncertain parameters that\n## are nevertheless assumed to be constant.\np_bounds = dom.model[:bounds]\n\n## Component groups\np_groups = dom.model[:component]\n\n## All of above as a DataFrame\nmodel_spec = DataFrame(dom.model)\n\n\n# Get DataFrame of parameter information for a specific sub-component (Intervention, Criteria, Coral)\nADRIA.component_params(dom.model, Intervention)","category":"page"},{"location":"usage/cookbook/#Generating-and-running-scenarios","page":"Cookbook examples","title":"Generating and running scenarios","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using ADRIA\n\n\n# Loading data package\ndom = ADRIA.load_domain(\"Example_domain\")\n\n# Creating 128 scenarios based on parameter bounds using the Sobol' method\nscens = ADRIA.sample(dom, 128)\n\n# Can also use other samplers\n# using Surrogates.QuasiMonteCarlo\n# scens = ADRIA.sample(dom, 100, LatinHypercubeSample())\n\n# Can also sample counterfactuals (scenarios with no interventions)\n# or scenarios with guided interventions only\n# s = ADRIA.sample_cf(dom, 32)\n# s = ADRIA.sample_guided(dom, 32)\n\n# Can also load previously generated scenarios\n# p_df = ADRIA.load_scenarios(dom, joinpath(here, \"example_scenarios.csv\"))\n\n# Batch run scenarios. Returns a ResultSet.\n# Setting up and running scenarios\nrs = ADRIA.run_scenarios(dom, p_df, \"45\")\n\n# Multiple RCPs can be specified, so long as RCP-specific data is available.\n# rs = ADRIA.run_scenarios(dom, p_df, [\"45\", \"60\"])\n\n# Single scenario run (returns NamedTuple of results for a single environmental/intervention scenario).\n# See documentation for more detail.\n# scenario_id = 1\n# result = ADRIA.run_scenario(domain::Domain, scenario_id, param_df::DataFrameRow)\n\n# switch_RCPs!(domain, \"45\")\n# res1 = ADRIA.run_scenario(domain, scens[1, :])\n# res2 = ADRIA.run_scenario(domain, scens[2, :])\n# res3 = ADRIA.run_scenario(domain, scens[3, :], \"60\") # run for a different RCP\n\n# The location of the outputs stored on disk\n@info ADRIA.store_name(rs)\n# \"Example_domain__RCPs45__2022-10-19_12_01_26_965\"\n\n@info ADRIA.result_location(rs)\n# \"[some location]/Example_domain__RCPs45__2022-10-19_12_01_26_965\"\n\n# Can also load results using a path to the stored result set.\n# rs = ADRIA.load_results(\"path to result set\")\n\n# Specific metrics found in the `metrics` submodule.\n# tac = ADRIA.metrics.total_absolute_cover(rs)","category":"page"},{"location":"usage/cookbook/#Intervention-location-selection","page":"Cookbook examples","title":"Intervention location selection","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using ADRIA\nusing ADRIA: rank_locations\n\n\ndom = ADRIA.load_domain(\"path to domain\", \"45\")\nscens = ADRIA.sample_site_selection(dom, 8)\n\n# Area of seeded corals in m^2\narea_to_seed = 962.11\n\n# Initial coral cover matching number of criteria samples (size = (no. criteria scens, no. of sites)).\nsum_cover = repeat(sum(dom.init_coral_cover; dims=1), size(scens, 1))\n\n# Use rank_locations to get ranks\nranks = rank_locations(dom, scens, sum_cover, area_to_seed)","category":"page"},{"location":"usage/cookbook/#Intervention-location-selection-summary-functions","page":"Cookbook examples","title":"Intervention location selection - summary functions","text":"","category":"section"},{"location":"usage/cookbook/","page":"Cookbook examples","title":"Cookbook examples","text":"using ADRIA\nusing ADRIA:\n rank_locations,\n ranks_to_frequencies,\n location_selection_frequencies,\n selection_score\nusing DataFrames\nusing Statistics, StatsBase\n\n# Load data package\ndom = ADRIA.load_domain(\"path to Domain files\", \"RCP\")\n\n# Select locations for interventions without any model runs\nscens = ADRIA.sample_site_selection(dom, 8) # Get site selection scenario dataframe.\n\n# Area of seeded corals in m^2\narea_to_seed = 962.11\n\n# Initial coral cover matching number of criteria samples\nsum_cover = repeat(sum(dom.init_coral_cover; dims=1), size(scens, 1))\n\n# Use rank_locations to get ranks\nranks = rank_locations(dom, scens, sum_cover, area_to_seed)\n\n# Get frequencies with which each site is selected for each rank for set of stand alone\n# location selections\nrank_freq = ranks_to_frequencies(ranks[intervention=1])\n\n# Calculate rank aggregations\n# Get location selection freqencies for set of standalone location selections\nlocation_selection_frequency = location_selection_frequencies(ranks[intervention=1])\n\n# Get summed inverse rank for set of standalone location selections\n# Measure of magnitude and frequency of high rank\nsel_score = selection_score(ranks[intervention=1])\n\n# Use aggregation function within rank_locations to get direct output\n# To get rank frequencies:\nrank_frequencies_seed = rank_locations(\n dom, scens, sum_cover, area_to_seed, ranks_to_frequencies, 1\n)\nrank_frequencies_seed = rank_locations(\n dom, scens, sum_cover, area_to_seed, location_selection_frequencies, 1\n)\nrank_frequencies_seed = rank_locations(\n dom, scens, sum_cover, area_to_seed, selection_score, 1\n)\n\n# Example using ADRIA runs\nscens = ADRIA.sample(dom, 8)\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# Get frequencies with which each site was selected for each rank for a set of runs\nrank_freq = ranks_to_frequencies(rs.ranks[intervention=1]) # with timesteps not aggregated\n\n# With timesteps aggregated\nrank_freq = ranks_to_frequencies(\n rs.ranks[intervention=1];\n agg_func=x -> dropdims(sum(x; dims=:timesteps); dims=:timesteps),\n)\n\n# Get selection frequencies for set of runs\nselection_freq = location_selection_frequencies(rs.ranks[intervention=1])\n\n# Get selection frequencies over time for unguided runs only\nunguided_freq = location_selection_frequencies(\n rs.seed_log[scenarios=findall(scens.guided .>= 1)]\n)\n\n# Get selection score for set of runs\n# Measure of magnitude and frequency of high rank\nsel_score = selection_score(rs.ranks[intervention=1])\n\n# Get selection score for locations over time\nsel_score = selection_score(rs.ranks[intervention=1]; dims=[:scenarios])","category":"page"},{"location":"architecture/architecture/#Architectural-overview","page":"Architectural overview","title":"Architectural overview","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"ADRIA consists of three overarching components:","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"a set of Multi-Criteria Decision Analysis methods used to emulate decision-makers\na coral ecosystem model (referred to as ADRIAmod)\na suite of analysis and assessment methods","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Each component may be applied separately, or altogether to perform an end-to-end analysis. This page documents the underlying architectural implementation of ADRIA, detailing how the above components interact.","category":"page"},{"location":"architecture/architecture/#General-Structure","page":"Architectural overview","title":"General Structure","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"The primary purpose of ADRIA is to support reef restoration and adaptation through the development of robust intervention strategies under deep uncertainty. Here, \"robustness\" refers to the ability of an intervention strategy to meet desired outcomes under uncertain future conditions, which themselves are unknown and may be unexpected. To do so, ADRIA adopts an Exploratory Scenario Modelling framework to explore the range of possible futures and their outcomes.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Exploratory Scenario Modelling (ESM) itself leverages uncertainty and sensitivity analysis (UA/SA). Uncertainty analysis quantifies the variability of uncertainties in a given system and its expected range of outcomes. Sensitivity analysis examines the effect of a change in a model's inputs to its outputs. Common workflows to such analyses involve a three-step process (as discussed in Pianosi et al., 2016):","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Input sampling\nModel evaluation\nPost-processing","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"When ADRIA is applied in its entirety, \"input sampling\" is analogous to scenario generation: all model factors (the inputs) are collated and are sampled through a quasi-monte carlo process. The Sobol' sampling method is adopted as the default, although any method provided by the QuasiMonteCarlo.jl package can be used. Sample adjustment is required to map sampled values (which are continuous) to categorical or whole number values (e.g., Baroni and Tarantola, 2014) as may be expected by some factors. Values are also adjusted to avoid implausible factor combinations, such as active intervention factors in the case of non-intervention scenarios.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Model evaluation is simply running the model with the generated scenario set.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Post-processing is the analysis and visualization step.","category":"page"},{"location":"architecture/architecture/#Model-Factors","page":"Architectural overview","title":"Model Factors","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Factors in ADRIA are defined across four sub-components:","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Intervention\nCriteriaWeights\nEnvironmentalLayer\nCoral","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Each sub-component is represented by a struct with fields for each parameter. The Intervention sub-component holds parameters that define a given adopted intervention strategy/option: how many (and type of) corals are to be seeded, the length of any deployment, the start/end years, and so on. The CriteriaWeights sub-component relates to the preferences for the Multi-Criteria Decision Analysis methods, further detailed in Dynamic Multi-Criteria Decision Analysis. For the ADRIA ecosystem model (ADRIAmod), EnviromentalLayer relate to the environmental scenarios available for a given simulation (a time series of DHW and Wave stress), itself determined on the loading of data (see Running scenarios).","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"The Coral sub-component relates to ADRIAmod, currently representing six coral species:","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Arborescent Acropora\nTabular Acropora\nCorymbose Acropora\nCorymbose non-Acropora\nSmall massives and encrusting\nLarge massives","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"ADRIAmod represents these across six size classes, with six parameter sets for each coral species and size class. These six parameter sets are further detailed in Model Factors, however, it results in a large number of unique factors (6 groups x 6 size classes x 6 parameters: 216 factors). Instead of specifying all coral factors by hand, ADRIA instead auto-generates the sub-component using a common template (see coral_spec() and create_coral_struct() in General API). Through discussion with expert stakeholders, factor bounds were set to +/- 10% of their default values following a triangular distribution, the peak of which is the default value.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"The ModelParameters.jl package is used to provide a simple table-like interface to model factors. ADRIA provides a wrapper to the Param type provided by ModelParameters.jl called a Factor. These Factors requires ADRIA-specific metadata to be provided alongside the default value for a given model factor. These include the assumed distribution of the factor, distribution factors (principally the lower and upper bounds), and a human-readable name and description. An example from the Intervention sub-component is shown below.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"guided::N = Factor(0.0, ptype=\"ordered categorical\", dist=(-1.0, 3.0), dist_params=DiscreteUniform,\n name=\"Guided\", description=\"Choice of MCDA approach.\")","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Note that factor values are provided as floats - even where discrete values are expected - to maintain type stability. Mixing floats with integers will lead to an error. Similarly, values used to update the model should always be floats.","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"Combinations of the realized factor values then represent a \"scenario\".","category":"page"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"note: Parameter Collation and Scenario Generation\nSee Cookbook examples for an example how-to on collating model factors and generating samples.","category":"page"},{"location":"architecture/architecture/#References","page":"Architectural overview","title":"References","text":"","category":"section"},{"location":"architecture/architecture/","page":"Architectural overview","title":"Architectural overview","text":"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.","category":"page"},{"location":"development/release_guide/#Release-Guide","page":"Release Guide","title":"Release Guide","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"All releases are done on main.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Note: version numbers should follow Semantic Versioning.","category":"page"},{"location":"development/release_guide/#Public-\"Final\"-Releases","page":"Release Guide","title":"Public \"Final\" Releases","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Increase the version number (manually) following SemVer in the Project.toml file\nUpdate environment and run tests locally to ensure all pass. Testing\nSubmit a PR with the updated version number. Wait for approval.\nOnce approved, go to the releases page and click the \"Draft a new release\" button at the top right\nUnder \"Choose a tag\" on the left, enter the new version number (e.g., \"v0.99.0\") and then select \"Create new tag: on publish\"\nAt the top-right of the textbox, select the last full release then click the \"Generate release notes\" button (at the top-right of the textbox).\nUnder \"What's Changed\" add a short description of the major changes. Explicitly note any major breaking changes (i.e., anything that results obtained with previous versions of ADRIA incompatible) Copy the release notes (for step 8). Click \"Publish release\".\nRegister the updated package by opening a new issue with the title \"Register [version number]\" e.g., Register v1.0\nState in the comment: @JuliaRegistrator register Paste in the generated text from step 6 (an example is shown below)\nSubmit the issue. The JuliaRegistrator bot should take care of the rest.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"@JuliaRegistrator register\n\nRelease notes:\n\nPaste the generated release notes here.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"See Julia Registrator usage notes here for more details.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"note: Issues can block release\nThe JuliaRegistrator bot submits a corresponding Pull Request with the Julia package registry. Registration may be blocked for a number of reasons. Keep an eye on the auto-submitted Pull Request and resolve any issues reported there. Otherwise the package version will never be released.","category":"page"},{"location":"development/release_guide/#Development-Release","page":"Release Guide","title":"Development Release","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Development releases provide users with the most recent \"working\" version of ADRIA and may still have some known bugs. It provides users a chance to try new features and/or provide feedback before a public release.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Deploying a Development Release follows the same steps as \"Public\" releases, except:","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Add \"-dev.x\" to the version number. e.g., v1.2.3-dev.1; v1.2.3-dev.2 for the second development release, etc.\nUntick \"Set as the latest release\" and tick the \"Set as a pre-release\" option.\nIgnore Step 8 through 10; DO NOT trigger the JuliaRegistrator bot.","category":"page"},{"location":"development/release_guide/#Release-Candidates","page":"Release Guide","title":"Release Candidates","text":"","category":"section"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Release candidates are releases that are not yet \"final\" but are close to it. Release candidates provide a \"last chance\" opportunity for users to report bugs prior to a \"final\" release.","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Deploying a Release Candidate follows the same steps as \"Public\" releases, except:","category":"page"},{"location":"development/release_guide/","page":"Release Guide","title":"Release Guide","text":"Add \"-rc.x\" to the version number. e.g., v1.2.3-rc.1; v1.2.3-rc.2 for the second release candidate, etc.\nUntick \"Set as the latest release\" and tick the \"Set as a pre-release\" option.\nIgnore Step 8 through 10; DO NOT trigger the JuliaRegistrator bot.","category":"page"},{"location":"usage/scenario_generation/#Generating-scenarios","page":"Generating scenarios","title":"Generating scenarios","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Typical use of ADRIA is to generate a number of scenarios by sampling from combinations of possible factors relating to environmental, intervention, and coral conditions.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"A scenario is defined as a combination of all factors (i.e., all the model inputs).","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"# Load domain before generating scenarios\ndom = ADRIA.load_domain(\"path to domain data package\")\n\n# Generate 128 scenarios based on available environmental data layers and model parameters\nscens = ADRIA.sample(dom, 128)","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Here, the scens variable holds a DataFrame of scenarios of shape N by D, where N is the number of scenarios (rows) and D is the number of factors (columns). Because it is a DataFrame, it can be modified after the fact.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"The Sobol' method (Sobol' 1993, 2001) with Owen Scrambling is the default sampling approach. The Sobol' sampling method is a deterministic low-discrepancy quasi-monte carlo method. Samples are described as having low discrepancy if the samples are equi-distributed, and thus guarantee an even exploration of factor space. Owen Scrambling is an approach to introduce randomness to the quasi-monte carlo sequence, and belong to a class of sampling methods known as randomized Quasi-Monte Carlo (rQMC). rQMC approaches offer a balance between good space-filling properties and associated exploration of factor space with improved convergence characteristics.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"One limitation of the Sobol' method is that all factors are assumed to be independent. For most factors represented in ADRIA, this assumption holds true. Specific factors relating to intervention options may conditionally co-vary however, and this dependency is introduced by adjusting the sample values a posteriori to restrict sampled values to their plausible combinations, and to map continuous values to their expected discrete factor values (where necessary), as is in the case with categorical factors. The Sobol' scheme is therefore disrupted due to the adjustment and so a Sobol' sensitivity analysis may exhibit comparatively poor convergence. Subsequent assessment of uncertainty and sensitivity is instead conducted with the distribution-based PAWN method (Pianosi and Wagener 2015, 2018).","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"note: Sobol' samples\nThe convergence properties of the Sobol' sequence is only valid if the number of samples is a power of 2.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Samples for factors with non-uniform distributions are transformed to their indicated distributions using the Inverse Cumulative Distribution Function method.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Although the Sobol' method is the default, any sampler supported by the Surrogates.jl package may be used. Below is an example using Latin Hypercube sampling.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"import Surrogates.QuasiMonteCarlo: LatinHypercubeSample\n\nscens = ADRIA.sample(dom, 100, LatinHypercubeSample())","category":"page"},{"location":"usage/scenario_generation/#On-model-parameters-and-specifications","page":"Generating scenarios","title":"On model parameters and specifications","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"The current default values can be extracted with:","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"params = ADRIA.param_table(dom)","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Again, params is a DataFrame of a single row and D factors: A single scenario with model factors set to their default values.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Running specific user-defined scenarios is as simple as modifying the DataFrame (referred to as the \"scenario specification\"). A set of scenarios may be specified simply by extending the number of rows of the DataFrame. Details of the ADRIA model - parameter names, the default values, and their bounds - can be extracted as well.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"# Get model specification\nmodel_spec = ADRIA.model_spec(dom)\n\n# Sometimes it is useful to export the model specification to CSV\nADRIA.model_spec(dom, \"model_spec.csv\")","category":"page"},{"location":"usage/scenario_generation/#Constrained-sampling","page":"Generating scenarios","title":"Constrained sampling","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"At times, it is necessary to create samples while holding some model factors constant.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Although a scenario set could be modified to make specific factors constant, doing so runs the risk of creating (many) identical scenarios, thereby wasting computational effort. A more efficient approach is to modify the model specification itself to treat those factors as constants. These then get ignored for the purpose of scenario generation.","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"dom = ADRIA.load_domain()\n\n# Could keep a copy of the original model parameters/bounds\n# to reset to later.\n# orig_spec = DataFrame(dom.model)\n\n# Make the assisted adaptation factor a constant\nADRIA.fix_factor!(dom, :a_adapt)\n\n# Set the assisted adaptation factor to a given constant value\nADRIA.fix_factor!(dom, :a_adapt, 3.0)\n\n# Pass in factor names and their constant values as named arguments\n# to fix a set of factors.\nADRIA.fix_factor!(dom;\n seed_TA=Int64(5e5),\n seed_CA=Int64(5e5),\n SRM=0.0, # Never shade\n fogging=0.0, # Never fog\n a_adapt=3.0, # only deploy +3 DHW enhanced corals\n seed_years=5,\n shade_years=0,\n seed_deployment_freq=0,\n seed_year_start=3,\n shade_year_start=3,\n coral_cover_tol=1.0\n)","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Samples can also be taken over a constrained range. For example, if one wanted to investigate only scenarios with high fogging and seeding, the following could be used:","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"dom = ADRIA.load_domain()\n\n# Adjust seeding bounds. Note only lower and upper bounds are needed because the factors in\n# question have a uniform distribution.\ndom = ADRIA.set_factor_bounds(dom, :N_seed_TA, (500000.0, 1000000.0))\ndom = ADRIA.set_factor_bounds(dom, :N_seed_CA, (500000.0, 1000000.0))\ndom = ADRIA.set_factor_bounds(dom, :N_seed_SA, (500000.0, 1000000.0))\n\n# Adjust fogging bounds. Note lower, upper and mode parameters are needed because it\n# is a triangular distribution.\ndom = ADRIA.set_factor_bounds(dom, :fogging, (0.2, 0.3, 0.1))\n\n# Adjust multiple factors simultaneously.\ndom = ADRIA.set_factor_bounds(dom;\n heat_stress=(0.3, 0.7),\n N_seed_TA=(500000.0, 1000000.0),\n N_seed_CA=(500000.0, 1000000.0))","category":"page"},{"location":"usage/scenario_generation/#Sampling-counterfactuals-only","page":"Generating scenarios","title":"Sampling counterfactuals only","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"A convenience function to create scenarios with no interventions (counterfactuals).","category":"page"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"cf_scens = ADRIA.sample_cf(dom, 1024)","category":"page"},{"location":"usage/scenario_generation/#References","page":"Generating scenarios","title":"References","text":"","category":"section"},{"location":"usage/scenario_generation/","page":"Generating scenarios","title":"Generating scenarios","text":"Sobol’, I. M. 1993. Sensitivity analysis for non-linear mathematical models. Mathematical Modelling and Computational Experiment 1:407–414. [Translated from Russian, accessible at: https://www.mathnet.ru/php/archive.phtml?wshow=paper&jrnid=mm&paperid=2320&option_lang=eng]\nSobol′, I. M. 2001. Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation 55:271–280. https://doi.org/10.1016/S0378-4754(00)00270-6\nPianosi, F., and T. Wagener. 2015. A simple and efficient method for global sensitivity analysis based on cumulative distribution functions. Environmental Modelling & Software 67:1–11. https://dx.doi.org/10.1016/j.envsoft.2015.01.004\nPianosi, F., and T. Wagener. 2018. Distribution-based sensitivity analysis from a generic input-output sample. Environmental Modelling & Software 108:197–207. https://dx.doi.org/10.1016/j.envsoft.2018.07.019","category":"page"},{"location":"usage/domain/#Loading-a-Domain","page":"Loading a Domain","title":"Loading a Domain","text":"","category":"section"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"ADRIA is designed to work with Domain data packages.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"At their core, data packages are a directory containing a datapackage.json file, following the spec as outlined by Frictionless Data. In short, these are pre-packaged data sets that hold all the necessary data to run simulations for a given spatial domain.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"See Architectural overview for more information.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"A Domain may be loaded by calling the load_domain function with the path to the data package. Note that the data package is the directory.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"By convention we assign the Domain to dom, although this variable can be named anything.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"dom = ADRIA.load_domain(\"path to domain data package\")","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"ReefMod Engine datasets can also be used to run ADRIAmod simulations for the Great Barrier Reef.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"dom = ADRIA.load_domain(RMEDomain, \"path to ReefModEngine dataset\", \"45\")","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"Note that at the moment the target RCP has to be specified.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"ReefMod Matlab datasets that have been converted to NetCDF files can also be used to run ADRIAmod simulation for the Great Barrier Reef.","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"dom = ADRIA.load_domain(ReefModDomain, \"path to ReefMod dataset\", \"45\")","category":"page"},{"location":"usage/domain/","page":"Loading a Domain","title":"Loading a Domain","text":"The target RCP must also be specified.","category":"page"},{"location":"usage/scenario_runs/#Running-scenarios","page":"Running scenarios","title":"Running scenarios","text":"","category":"section"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"# Run sampled scenarios for a given RCP\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# ... or repeat scenario runs across multiple RCPs\nrs = ADRIA.run_scenarios(dom, scens, [\"45\", \"60\", \"85\"])\n\n# The location of the outputs stored on disk\n@info ADRIA.store_name(rs)\n# \"Example_domain__RCPs45__2022-10-19_12_01_26_965\"\n\n@info ADRIA.result_location(rs)\n# \"[some location]/Example_domain__RCPs45__2022-10-19_12_01_26_965\"","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"The rs variable is an ResultSet object which acts as an interface to the stored results.","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"The ResultSet provides:","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"An overview of scenarios run\nAccess to results from key ADRIA metrics\nSeeding/Shading/Fogging logs\ndomain spatial data","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"print(rs)","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"note: on-disk data store\nADRIA uses an on-disk data store (in Zarr format) to reduce memory use. The primary location for these is defined in the project's config.toml file (see instructions in Getting Started).","category":"page"},{"location":"usage/scenario_runs/","page":"Running scenarios","title":"Running scenarios","text":"tip: Reloading results\nPre-existing results can also be reloaded by providing the path to the data store.rs = ADRIA.load_results(\"path to result set\")","category":"page"},{"location":"dMCDA/#Dynamic-Multi-Criteria-Decision-Analysis","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"","category":"section"},{"location":"dMCDA/#Multi-Criteria-Decision-Making","page":"Dynamic Multi-Criteria Decision Analysis","title":"Multi-Criteria Decision Making","text":"","category":"section"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"Multi-criteria decision analysis (MCDA) encompasses a series of methods for conducting decision making in a way that is formalised, structured and transparent. It evaluates the decision objective according to numerical measures of decision criteria assembled by the decision maker. Constructing explicit criteria over which to evaluate alternatives allows a transparent evaluation of benefits, negatives and trade-offs in coming to a decision solution.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"Typical approaches to MCDA require the construction of a \"decision matrix\", which takes the form of a X^n cdot m, where n is the number of alternate options available, and m is the number of criteria.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"In the context of ADRIA, the alternate options relate to the locations being assessed. The criteria then relate to the common set of attributes on which the locations are being judged, such as the projected heat stress (in terms of DHW), depth, and level of incoming or outgoing connectivity.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"MCDA methods provide a ranking according to the set of assessed criteria, in the form of:","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"r = g(X w d)","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"where:","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"g()\nrefers to a given MCDA algorithm (see JMcDM.jl).\nX\nis the decision matrix\nw\nis the weights afforded to each criteria, indicating their relative importance\nd\nis the desired directionality for each criterion (to minimize the criteria value, or to maximize)\nr\nis the ranking determined by g()","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"When applied in conjunction with scenario analyses, locations are assessed at each decision point.","category":"page"},{"location":"dMCDA/","page":"Dynamic Multi-Criteria Decision Analysis","title":"Dynamic Multi-Criteria Decision Analysis","text":"When conducting location selection, the analyses are applied to the initial conditions represented in the Domain.","category":"page"},{"location":"development/metrics/#Contributing-a-metric","page":"Contributing a metric","title":"Contributing a metric","text":"","category":"section"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"At a minimum, all metrics must define:","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"a \"private\" function (i.e., one that starts with an underscore: _) that performs the calculation with expected arguments\na \"private\" function that accepts a ResultSet as its first argument.\na \"public\" Metric function (i.e., no underscore) with some additional metadata","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"The Metric type allows metadata regarding the expected dimension names and unit of measure. Note that the unit of measure is optional and can be left out.","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"Below is the implementation of the total_absolute_cover metric.","category":"page"},{"location":"development/metrics/","page":"Contributing a metric","title":"Contributing a metric","text":"function _total_absolute_cover(X::AbstractArray{<:Real}, loc_area::Vector{<:Real})::AbstractArray{<:Real}\n return dropdims(sum(X, dims=:species), dims=:species) .* loc_area'\nend\nfunction _total_absolute_cover(rs::ResultSet)::AbstractArray{<:Real}\n return rs.outcomes[:total_absolute_cover]\nend\ntotal_absolute_cover = Metric(_total_absolute_cover, (:timesteps, :sites, :scenarios), \"m²\")\n\n# Unit of measure is optional, in cases where the values are non-dimensional\n# some_example_metric = Metric(_some_example_metric, (:timesteps, :scenarios))","category":"page"},{"location":"architecture/domain_and_resultsets/#Inputs-and-Outputs","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"ADRIA seeks to use Data Packages to define a standard structure, format, and naming convention for its inputs and outputs. By definition, a Data Package is a directory holding the required data for ADRIA to run, or results from model runs.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Data specifications are outlined/stored in this repository: https://github.com/open-AIMS/ADRIA-data-specs","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The overall structure and data formats of the data packages are illustrated in the diagram below.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"(Image: Domain-Results Diagram)","category":"page"},{"location":"architecture/domain_and_resultsets/#Domain-data-package","page":"Inputs and Outputs","title":"Domain data package","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Prior to running the ADRIA coral ecosystem model, the first step (after importing the package) is to load domain data.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dom = ADRIA.load_domain(\"path to some domain\")","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"As the naming suggests, inputs are taken to represent a given spatial area, and so are referred to as a Domain.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The Domain data package consists of:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Connectivity (CSVs, grouped by year)\nDegree-Heating Week trajectories (in netCDF format; dimensions: timestep ⋅ location ⋅ projection)\nWave stress (as netCDFs; dimensions: timestep ⋅ location ⋅ projection)\nGeospatial data\na datapackage.json file with machine-readable metadata\na README.md file with human-readable content","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Geospatial data consists of:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"polygons defining individual reefs/sites in geopackage format\ninitial coral cover (as a netCDF; with dimensions: species/sizes ⋅ locations)","category":"page"},{"location":"architecture/domain_and_resultsets/#ReefMod-Datasets","page":"Inputs and Outputs","title":"ReefMod Datasets","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Datasets from containing inputs and outputs from ReefMod can be loaded for use with ADRIAmod. ADRIAmod requires geospatial data in geopackage format , a csv file containing location ids and reef connectivity data in addition to ReefMod Data.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dom = ADRIA.load_domain(ReefModDomain, \"path to ReefMod dataset\", \"45\")","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The expected directory structure is","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"ReefModDomain\n│ # ReefMod Data\n│ ReefMod_RCP19.nc\n│ ReefMod_RCP26.nc\n│ ReefMod_RCP45.nc\n│ ReefMod_RCP70.nc\n│ ReefMod_RCP85.nc\n│\n├───con_bin # Reef connectivity data\n│ CONNECT_ACRO_2010_11.bin\n│ CONNECT_ACRO_2011_12.bin\n│ CONNECT_ACRO_2012_13.bin\n│ CONNECT_ACRO_2014_15.bin\n│ CONNECT_ACRO_2015_16.bin\n│ CONNECT_ACRO_2016_17.bin\n│\n├───id # location ids\n│ id_list_2023_03_30.csv\n│\n└───region # geospatial data\n reefmod_gbr.gpkg","category":"page"},{"location":"architecture/domain_and_resultsets/#ReefMod-Engine-datasets","page":"Inputs and Outputs","title":"ReefMod Engine datasets","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Datasets intended for use with the ReefMod Engine (RME) can also be loaded for use with ADRIAmod. The RME represents larger spatial scales typically covering the entire Great Barrier Reef.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dom = ADRIA.load_domain(RMEDomain, \"path to ReefMod Engine dataset\", \"45\")","category":"page"},{"location":"architecture/domain_and_resultsets/#Naming-conventions","page":"Inputs and Outputs","title":"Naming conventions","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"By convention, the directory name is typically the name of the reef or reef cluster. Where multiple datasets for the same spatial domain are expected, appending a unique suffix is recommended, such as the date of creation, such as \"Moore_2022-11-17\".","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The geopackage is expected to have the same filename as its Domain. For example, if the domain name is \"Example_domain\", then the geopackage file should be named \"Example_domain.gpkg\".","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Degree-heating Week datasets must follow the convention of: dhwRCP[NN].nc","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Here, [NN] is to be replaced with the two digit RCP code that indicates which RCP scenario is represented by the given data cube. The following are examples of valid/expected filenames:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"dhwRCP26.nc\ndhwRCP34.nc\ndhwRCP45.nc\ndhwRCP60.nc\ndhwRCP70.nc\ndhwRCP85.nc","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Similarly, below are examples of valid/expected wave stress filenames:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"wave_RCP26.nc\nwave_RCP34.nc\nwave_RCP45.nc\nwave_RCP60.nc\nwave_RCP70.nc\nwave_RCP85.nc","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Below is a diagram indicating the directory layout","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Example_domain\n│ datapackage.json\n│ README.md\n│\n├───connectivity\n│ ├───2015\n│ │ connect_matrix_2015_1.csv\n│ │ connect_matrix_2015_2.csv\n│ │ connect_matrix_2015_3.csv\n│ │\n│ ├───2016\n│ │ connect_matrix_2016_1.csv\n│ │ connect_matrix_2016_2.csv\n│ │ connect_matrix_2016_3.csv\n│ │\n│ └───2017\n│ connect_matrix_2017_1.csv\n│ connect_matrix_2017_2.csv\n│ connect_matrix_2017_3.csv\n│\n├───DHWs\n│ dhwRCP26.nc\n│ dhwRCP45.nc\n│ dhwRCP60.nc\n│ dhwRCP85.nc\n│\n├───site_data\n│ coral_cover.nc\n│ Example_domain.gpkg\n│\n└───waves\n wave_RCP26.nc\n wave_RCP45.nc\n wave_RCP60.nc\n wave_RCP85.nc","category":"page"},{"location":"architecture/domain_and_resultsets/#ResultSets","page":"Inputs and Outputs","title":"ResultSets","text":"","category":"section"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The directory holding results is also treated as a data package referred to as a ResultSet. Scenario outcomes are written out to disk as they complete to a directory located in the user-defined Output directory (see Getting Started).","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The directory name follows the convention of [Domain Name]__[IDs of RCPs]__[date/time of run]. For example: Moore_2022-11-17__RCPs45_60__2023-01-01_19_00_00_000","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"The above example ResultSet indicates the \"Moore_2022-11-17\" Domain was run for RCPs 4.5 and 6.0 at precisely 7pm (i.e., 19:00:00.000, where the trailing \"000\" indicates milliseconds). Note that each \"portion\" of information is separated by a double underscore (__).","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Simulation results are stored in Zarr format. A ResultSet also holds a copy of:","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"the scenario specifications\nthe geospatial data used\nSummary statistics for the DHW/wave scenarios run, and\nLogs indicating which locations were intervened on","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Below is a diagram of the directory structure. Filenames are not shown here as there may be hundreds/thousands depending on the scenario set run.","category":"page"},{"location":"architecture/domain_and_resultsets/","page":"Inputs and Outputs","title":"Inputs and Outputs","text":"Example_domain__RCP45_60_85__2023-03-11_19_00_00_000\n├───env_stats\n│ ├───dhw\n│ │ ├───45\n│ │ ├───60\n│ │ └───85\n│ └───wave\n│ ├───45\n│ ├───60\n│ └───85\n├───inputs\n├───logs\n│ ├───fog\n│ ├───rankings\n│ ├───seed\n│ └───shade\n├───model_spec\n├───results\n│ ├───absolute_shelter_volume\n│ ├───relative_juveniles\n│ ├───relative_shelter_volume\n│ ├───relative_taxa_cover\n│ └───total_absolute_cover\n└───site_data","category":"page"},{"location":"usage/getting_started/#Getting-Started","page":"Getting Started","title":"Getting Started","text":"","category":"section"},{"location":"usage/getting_started/#Setup","page":"Getting Started","title":"Setup","text":"","category":"section"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"This section outlines how ADRIA may be used to arrive at a select range of possible pathways that are robust to possible future conditions.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Create a directory for your project, and start Julia inside that directory:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"$ julia --project=.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"ADRIA may be installed through the package manager or from the github repository (for the most recent development version).","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"julia> ]add ADRIA\n\n# OR, to install the latest development version:\n\njulia> ]add https://github.com/open-AIMS/ADRIA.jl.git","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Similarly, ADRIA can be updated as new releases are made:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"julia> ]up ADRIA","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"If desired, you can create a config.toml file inside your project directory. This is optional, and the assumed default values are shown below:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"[operation]\nnum_cores = 2 # No. of cores to use. Values <= 0 will use all available cores.\nthreshold = 1e-8 # Result values below this will be set to 0.0 (to save disk space)\ndebug = false # Disable multi-processing to allow error messages to be shown\n\n[results]\noutput_dir = \"./Outputs\" # Change this to point to where you want to store results","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"This config.toml file is specific to your computer and project. It should not be committed to version control.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"tip: Performance\nADRIA uses an on-disk data store to hold results from model runs. Setting output_dir to a directory on an SSD (Solid State Drive) will maximize performance.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"To setup ADRIA for development, see the Development setup page.","category":"page"},{"location":"usage/getting_started/#Quick-Start","page":"Getting Started","title":"Quick Start","text":"","category":"section"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"A common workflow would be the following:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Start Julia from the project directory:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"$ julia --project=.","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Load data for a spatial domain. See Loading a Domain for more details:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"using ADRIA\n\ndom = ADRIA.load_domain(\"path to domain data package directory\")","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Generate scenarios based on available environmental data layers and model parameters. The number of scenarios shoud be a power of two. See Generating scenarios for more details:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"num_scenarios = 128\nscens = ADRIA.sample(dom, num_scenarios)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Run sampled scenarios for one or more RCPs. Be aware that this may take a while:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"rcp_45 = \"45\"\nrs = ADRIA.run_scenarios(dom, scens, rcp_45)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Or run scenarios across several RCPs:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"rcps = [\"45\", \"60\", \"85\"]\nrs = ADRIA.run_scenarios(dom, scens, rcps)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"It is also possible to load previously run scenarios. See Running scenarios for more details:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"rs = ADRIA.load_results(\"path to results\")","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Extract some metric for analysis (e.g., the total absolute cover for each site and timestep):","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"s_tc = ADRIA.metrics.scenario_total_cover(rs)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"Use the visualization tools to plot the results. The Makie package ecosystem is used for producing plots:","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"using GLMakie, GeoMakie, GraphMakie\n\n# Plot a quick scenario overview\nfig = ADRIA.viz.scenarios(rs, s_tc; axis_opts=Dict(:ylabel=>\"Absolute Cover\"))\nsave(\"path_to_save_figure\", fig)","category":"page"},{"location":"usage/getting_started/","page":"Getting Started","title":"Getting Started","text":"See Analysis for further examples of analysis and plots.","category":"page"},{"location":"API/#ADRIA-API","page":"ADRIA API","title":"ADRIA API","text":"","category":"section"},{"location":"API/#Metrics","page":"ADRIA API","title":"Metrics","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA.metrics]\nOrder = [:constant, :function, :type]\nPrivate = true","category":"page"},{"location":"API/#ADRIA.metrics._absolute_juveniles-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, DataFrames.DataFrame, AbstractVector{T}}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._absolute_juveniles","text":"absolute_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::AbstractVector{T})::AbstractArray{T,2} where {T<:Real}\nabsolute_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}\n\nJuvenile coral cover in m².\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations)\n\ncoral_spec : Coral spec DataFrame\nk_area : The coral habitable area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._absolute_shelter_volume-Union{Tuple{T}, Tuple{YAXArrays.Cubes.YAXArray{T, 3, A} where A<:AbstractArray{T, 3}, Vector{T}, DataFrames.DataFrameRow}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._absolute_shelter_volume","text":"absolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(X::YAXArray{T,4}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(X::YAXArray{T,3}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(X::YAXArray{T,4}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nabsolute_shelter_volume(rs::ResultSet)\n\nProvide indication of shelter volume in volume of cubic meters.\n\nThe 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).\n\nArguments\n\nX : raw results\nk_area : area in m^2 for each site\nmax_cover : maximum possible coral cover for each site (in percentage of loc_area)\ninputs : DataFrame of scenario inputs\n\nReferences\n\nUrbina-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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._collate_ranked_locs-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._collate_ranked_locs","text":"_collate_ranked_locs(data::YAXArray)::Matrix{Int64}\n\nCollates number of ranked locations.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._collate_ranks-Tuple{ADRIA.ResultSet, Any}","page":"ADRIA API","title":"ADRIA.metrics._collate_ranks","text":"_collate_ranks(rs, selected)\n\nCollates ranks into seed/fog ranking results into a common structure.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._colony_Lcm2_to_m3m2-Tuple{DataFrames.DataFrame}","page":"ADRIA API","title":"ADRIA.metrics._colony_Lcm2_to_m3m2","text":"_colony_Lcm2_to_m3m2(inputs::DataFrame)::Tuple\n_colony_Lcm2_to_m3m2(inputs::YAXArray)::Tuple{Vector{Float64},Vector{Float64}}\n\nHelper function to convert coral colony values from Litres/cm² to m³/m²\n\nArguments\n\ninputs : Scenario values for the simulation\n\nReturns\n\nTuple : Assumed colony volume (m³/m²) for each species/size class, theoretical maximum for each species/size class\n\nReferences\n\nAston 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._coral_evenness-Union{Tuple{AbstractArray{T, 3}}, Tuple{T}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._coral_evenness","text":"coral_evenness(r_taxa_cover::AbstractArray{T})::AbstractArray{T} where {T<:Real}\ncoral_evenness(rs::ResultSet)::AbstractArray{T} where {T}\n\nCalculates evenness across functional coral groups in ADRIA as a diversity metric. Inverse Simpsons diversity indicator.\n\nReferences\n\nHill, M. O. (1973).\n\nDiversity and Evenness: A Unifying Notation and Its Consequences. Ecology, 54(2), 427-432. https://doi.org/10.2307/1934352\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._get_ranks-Tuple{ADRIA.ResultSet, Symbol}","page":"ADRIA API","title":"ADRIA.metrics._get_ranks","text":"_get_ranks(rs::ResultSet, intervention::Int64; kwargs...)\n\nExtracts results for a specific intervention (:seed or :fog)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._juvenile_indicator-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, DataFrames.DataFrame, Vector{Float64}}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._juvenile_indicator","text":"juvenile_indicator(X::AbstractArray{T,3}, coral_spec::DataFrame, k_area::Vector{Float64})::AbstractArray{T,2} where {T<:Real}\njuvenile_indicator(rs::ResultSet)::AbstractArray{<:Real,2}\n\nIndicator for juvenile density (0 - 1), where 1 indicates the maximum theoretical density for juveniles have been achieved.\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations).\n\ncoral_spec : Coral spec DataFrame.\nk_area : The coral habitable area.\n\nNotes\n\nMaximum 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._max_juvenile_area","page":"ADRIA API","title":"ADRIA.metrics._max_juvenile_area","text":"_max_juvenile_area(coral_params::DataFrame, max_juv_density::Float64=51.8)\n\nCalculate the maximum possible area that can be covered by juveniles for a given m².\n\n\n\n\n\n","category":"function"},{"location":"API/#ADRIA.metrics._reef_condition_index-NTuple{4, AbstractArray}","page":"ADRIA API","title":"ADRIA.metrics._reef_condition_index","text":"reef_condition_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray; threshold=2)::AbstractArray\nreef_condition_index(rs::ResultSet)::AbstractArray{<:Real}\n\nEstimates a Reef Condition Index (RCI) providing a single value that indicates the condition of a reef across four metrics:\n\ncoral cover\nevenness (coral diversity)\nshelter volume, and\nabundance of juveniles\n\nNotes\n\nJuveniles are made relative to maximum observed juvenile density (51.8/m²) See notes for juvenile_indicator()\n\nArguments\n\nrc : Relative coral cover across all groups\nevenness : Evenness across all coral groups\nsv : Shelter volume based on coral sizes and abundances\njuves : Abundance of coral juveniles < 5 cm diameter\n\nReturns\n\nYAXArray[timesteps ⋅ locations ⋅ scenarios]\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._reef_fish_index-Tuple{AbstractArray, Any, Any}","page":"ADRIA API","title":"ADRIA.metrics._reef_fish_index","text":"reef_fish_index(rc::AbstractArray)\nreef_fish_index(rs::ResultSet)\n\nThe Reef Fish Index (RFI) estimates fish biomass from relative coral cover.\n\nA 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]).\n\nValues are provided ∈ [0, 1], where 1 indicates maximum fish biomass.\n\nNote: Coral cover here is relative to coral habitable area (k area).\n\nArguments\n\nrc : Relative cover\n\nReturns\n\nYAXArray[timesteps ⋅ locations ⋅ scenarios], values in kg/km²\n\nReferences\n\nGraham, N.A.J., Nash, K.L., 2013.\n\nThe importance of structural complexity in coral reef ecosystems. Coral Reefs 32, 315–326. https://doi.org/10.1007/s00338-012-0984-y\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._reef_tourism_index-Tuple{AbstractArray, AbstractArray, AbstractArray, AbstractArray, Vector}","page":"ADRIA API","title":"ADRIA.metrics._reef_tourism_index","text":"reef_tourism_index(rc::AbstractArray, evenness::AbstractArray, sv::AbstractArray, juves::AbstractArray, intcp_u::Vector)::AbstractArray\nreef_tourism_index(rs::ResultSet; intcp_u::Bool=false)::AbstractArray\n\nEstimate tourism index.\n\nNote: 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.\n\nArguments\n\nrc : Relative coral cover across all groups\nevenness : Evenness across all coral groups\nsv : Shelter volume based on coral sizes and abundances\njuves : Abundance of coral juveniles < 5 cm diameter\nintcp_u : ?\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_cover-Tuple{YAXArrays.Cubes.YAXArray{var\"#s395\", N, A} where {var\"#s395\"<:Real, N, A<:AbstractArray{var\"#s395\", N}}}","page":"ADRIA API","title":"ADRIA.metrics._relative_cover","text":"relative_cover(X::AbstractArray{<:Real})::AbstractArray{<:Real}\nrelative_cover(rs::ResultSet)::AbstractArray{<:Real}\n\nIndicate coral cover relative to available hard substrate (k area).\n\nArguments\n\nX : Matrix with dimensions (ntimesteps, nfunctionalgroups * nsize_classes,\n\nn_locations) of raw model results (coral cover relative to available space)\n\nReturns\n\nCoral cover [0 - 1], relative to available k area for a given location.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_juveniles-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, DataFrames.DataFrame}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._relative_juveniles","text":"relative_juveniles(X::AbstractArray{T,3}, coral_spec::DataFrame)::AbstractArray{T,2} where {T<:Real}\nrelative_juveniles(rs::ResultSet)::AbstractArray{<:Real,2}\n\nJuvenile coral cover relative to total site area.\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations)\n\ncoral_spec : Coral spec DataFrame\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_loc_taxa_cover-Union{Tuple{T}, Tuple{AbstractArray{T}, Vector{T}, Int64}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._relative_loc_taxa_cover","text":"relative_loc_taxa_cover(X::AbstractArray{T}, k_area::Vector{T}, n_groups::Int64)::AbstractArray{T,3} where {T<:Real}\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations)\n\nk_area : The coral habitable area.\nn_groups : Number of function coral groups.\n\nReturns\n\nCoral cover, grouped by taxa for the given scenario, for each timestep and location, relative to location k area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_shelter_volume-Union{Tuple{T}, Tuple{AbstractArray{T, 3}, Vector{T}, DataFrames.DataFrameRow}} where T<:Real","page":"ADRIA API","title":"ADRIA.metrics._relative_shelter_volume","text":"relative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,3}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrameRow)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::DataFrame)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(X::AbstractArray{T,4}, k_area::Vector{T}, inputs::YAXArray)::AbstractArray{T} where {T<:Real}\nrelative_shelter_volume(rs::ResultSet)\n\nProvide indication of shelter volume relative to theoretical maximum volume for the area covered by coral.\n\nThe 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).\n\nRSV = begincases\nTASV MSV MSV 0 \n0 textotherwise\nendcases\n\nwhere TASV represents Total Absolute Shelter Volume and MSV represents the maximum shelter volume possible.\n\nArguments\n\nX : raw results\nk_area : area in m^2 for each site\nscens : DataFrame of scenario inputs\n\nReturns\n\nShelter volume relative to a theoretical maximum volume for the available k area.\n\nReferences\n\nUrbina-Barreto, I., Chiroleu, F., Pinel, R., Fréchon, L., Mahamadaly, V., Elise, S.,\n\nKulbicki, 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._relative_taxa_cover-Tuple{AbstractArray{<:Real}, Vector{<:Real}, Int64}","page":"ADRIA API","title":"ADRIA.metrics._relative_taxa_cover","text":"relative_taxa_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real}, n_groups::Int64)::AbstractArray{<:Real,2}\nrelative_taxa_cover(rs::ResultSet)::AbstractArray{<:Real,2}\n\nRelative coral cover grouped by taxa/species sumed up across all locations.\n\nArguments\n\nX : Raw model results for a single scenario. Dimensions (ntimesteps, ngroup_sizes,\n\nn_locations).\n\nk_area : The coral habitable area.\nn_groups : Number of function coral groups.\n\nReturns\n\nCoral cover, grouped by taxa for the given scenario, summed up across all locations, relative to total k area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_absolute_juveniles-Tuple{YAXArrays.Cubes.YAXArray, DataFrames.DataFrame, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._scenario_absolute_juveniles","text":"scenario_absolute_juveniles(data::YAXArray, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}\nscenario_absolute_juveniles(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean absolute juvenile population for each scenario for the entire domain.\n\nArguments\n\nX : Raw data for a single scenario.\ncoral_spec : Coral spec DataFrame.\nk_area : K_area.\nrs : Resultset.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_asv-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_asv","text":"scenario_asv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}\nscenario_asv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean absolute shelter volumes for each scenario for the entire domain.\n\nArguments\n\nasv : Absolute shelter volume.\nrs : Resultset.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_evenness-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_evenness","text":"scenario_evenness(ev::YAXArray; kwargs...)::AbstractArray{<:Real}\nscenario_evenness(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean coral evenness for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_juvenile_indicator-Tuple{YAXArrays.Cubes.YAXArray, DataFrames.DataFrame, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._scenario_juvenile_indicator","text":"scenario_juvenile_indicator(data::YAXArray, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}\nscenario_juvenile_indicator(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nDetermine juvenile indicator ∈ [0, 1], where 1 indicates maximum mean juvenile density (51.8) has been achieved.\n\nArguments\n\nX : Raw data for a single scenario.\ncoral_spec : Coral spec DataFrame.\nk_area : K_area.\nrs : Resultset.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rci-Tuple{YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rci","text":"scenario_rci(rci::YAXArray, tac::YAXArray; kwargs...)\nscenario_rci(rs::ResultSet; kwargs...)\n\nExtract the total populated area of locations with Reef Condition Index of \"Good\" or higher for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_relative_cover-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics._scenario_relative_cover","text":"scenario_relative_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean relative coral cover for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_relative_juveniles-Tuple{YAXArrays.Cubes.YAXArray{var\"#s388\", 3, A} where {var\"#s388\"<:Real, A<:AbstractArray{var\"#s388\", 3}}, DataFrames.DataFrame, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._scenario_relative_juveniles","text":"scenario_relative_juveniles(X::YAXArray{<:Real,3}, coral_spec::DataFrame, k_area::AbstractVector{<:Real}; kwargs...)::AbstractArray{<:Real}\nscenario_relative_juveniles(rs::ResultSet; kwargs...)::YAXArray\n\nCalculate the mean relative juvenile population for each scenario for the entire domain.\n\nArguments\n\nX : Raw data for a single scenario.\nrs : Resultset.\ncoral_spec : Coral spec DataFrame.\nk_area : K_area.\n\nExamples\n\nnum_scens = 2^5\nscens = ADRIA.sample(dom, num_scens)\n\n_coral_spec = ADRIA.to_coral_spec(scens[1,:])\n_k_area = site_k_area(dom)\n\n# X contains raw coral cover results for a single scenario\nADRIA.metrics.scenario_relative_juveniles(X, _coral_spec, _k_area)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rfi-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rfi","text":"scenariorfi(rfi::YAXArray; kwargs...) scenariorfi(rs::ResultSet; kwargs...)\n\nCalculate the mean Reef Fish Index (RFI) for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rsv-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rsv","text":"scenario_rsv(sv::YAXArray; kwargs...)::AbstractArray{<:Real}\nscenario_rsv(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean relative shelter volumes for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_rti-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_rti","text":"scenario_rti(rti::YAXArray; kwargs...)\nscenario_rti(rs::ResultSet; kwargs...)\n\nCalculate the mean Reef Tourism Index (RTI) for each scenario for the entire domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._scenario_total_cover-Tuple{AbstractArray}","page":"ADRIA API","title":"ADRIA.metrics._scenario_total_cover","text":"scenario_total_cover(rs::ResultSet; kwargs...)::AbstractArray{<:Real}\n\nCalculate the mean absolute coral for each scenario for the entire domain.\n\nArguments\n\ntac : Total absolute cover\nrs : ResultSet\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._shelter_species_loop!-Union{Tuple{V}, Tuple{YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray, Int64, V, V}} where V<:(AbstractVector{<:Float64})","page":"ADRIA API","title":"ADRIA.metrics._shelter_species_loop!","text":"shelterspeciesloop!(X::YAXArray, ASV::YAXArray, nspecies::Int64, colonyvolm3perm2::V, karea::V) where {V<:AbstractVector{<:Float64}}\n\nHelper method to calculate absolute shelter volume metric across each species/size class for a given scenario.\n\nArguments\n\nX : raw results (proportional coral cover relative to full site area)\nASV : matrix to hold shelter volume results\nnspecies : number of species (taxa and size classes) considered\nscen : scenario number to calculate metric for\ncolony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class\nk_area : habitable area of site in m²\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._shelter_species_loop-Union{Tuple{F}, Tuple{T1}, Tuple{AbstractArray{T1, 3}, Int64, Array{F}, Array{F}, Array{F}}} where {T1<:Real, F<:Float64}","page":"ADRIA API","title":"ADRIA.metrics._shelter_species_loop","text":"_shelter_species_loop(X::AbstractArray{T1,3}, n_species::Int64, colony_vol_m3_per_m2::Array{F}, max_colony_vol_m3_per_m2::Array{F}, k_area::Array{F})::YAXArray where {T1<:Real,F<:Float64}\n\nHelper method to calculate relative shelter volume metric across each species/size class for a given scenario.\n\nNote: 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.\n\nArguments\n\nX : raw results (proportional coral cover relative to full site area)\nn_group_and_size : number of species (taxa and size classes) considered\ncolony_vol_m3_per_m2 : estimated cubic volume per m² of coverage for each species/size class\nmax_colony_vol_m3_per_m2 : theoretical maximum volume per m² of coverage for each taxa\nk_area : habitable area of site in m² (i.e., k area)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics._total_absolute_cover-Tuple{AbstractArray{<:Real}, Vector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics._total_absolute_cover","text":"total_absolute_cover(X::AbstractArray{<:Real}, k_area::Vector{<:Real})::AbstractArray{<:Real}\ntotal_absolute_cover(rs::ResultSet)::AbstractArray{<:Real}\n\nThe Total Absolute Coral Cover. Sum of proportional area taken up by all corals, multiplied by total site area.\n\nArguments\n\nrelative_cover : Array with relative_cover\nk_area : Site areas, with sites following the same order as given indicated in X.\n\nReturns\n\nAbsolute coral cover for a given location in m².\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.axes_units-Tuple{Union{Tuple, Vector{Symbol}}}","page":"ADRIA API","title":"ADRIA.metrics.axes_units","text":"axes_units(axes_names::Union{Vector{Symbol},Tuple})::Tuple\n\nGet units for each metric axis.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.call_metric-Tuple{Union{Function, ADRIA.metrics.Metric}, YAXArrays.Cubes.YAXArray, Vararg{Any}}","page":"ADRIA API","title":"ADRIA.metrics.call_metric","text":"call_metric(metric::Union{Function,Metric}, data::YAXArray, args...; kwargs...)\n\nConvenience method that slices the data in the specified manner.\n\nArguments\n\nmetric : Function, the metric function to apply to \"raw\" data.\ndata : YAXArray, data to pass into metric\nargs : Additional positional arguments to pass into metric\nkwargs : Additional keyword arguments to pass into slice_results\ndims : dummy keyword argument, not used but defined to allow use with other methods\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.dims-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.dims","text":"dims(m::Metric)::Tuple\n\nGet dimension names for a given outcome/metric.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.dominates-Tuple{AbstractVector{<:Real}, AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics.dominates","text":"dominates(x::Vector{<:Real}, y::Vector{<:Real})::Vector\n\nAdapted from: https://discourse.julialang.org/t/fast-optimized-non-dominated-sorting-algorithms/86793/7\n\nOriginal function name is dominates2()\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.ensemble_loc_difference-Union{Tuple{T}, Tuple{YAXArrays.Cubes.YAXArray{T, 3, A} where A<:AbstractArray{T, 3}, DataFrames.DataFrame}} where T","page":"ADRIA API","title":"ADRIA.metrics.ensemble_loc_difference","text":"ensemble_loc_difference(outcome::YAXArray{T,3}, scens::DataFrame; agg_metric::Union{Function,AbstractFloat}=median, diff_target=:guided, conf::Float64=0.95, rng::AbstractRNG=Random.GLOBAL_RNG)::YAXArray where {T}\n\nMean bootstrapped difference (counterfactual - target) between some outcome aggregated for each location.\n\nArguments\n\noutcome : Metric outcome with dimensions (:timesteps, :locations, :scenarios).\nscens : Scenarios DataFrame.\nagg_metric : Metric used to aggregate scenarios when comparing between counterfactual and\n\ntarget. If it is an AbstractFloat between 0 and 1, it uses the bs_metric-th quantile. Defaults to median.\n\ndiff_target : Target group of scenarios to compare with. Valid options are :guided and\n\n:unguided. Defaults to :guided\n\nconf : Percentile used for the confidence interval. Defaults to 0.95.\nrng : Pseudorandom number generator.\n\nExample\n\n# Load domain\ndom = ADRIA.load_domain(path_to_domain)\n\n# Create scenarios\nnum_scens = 2^6\nscens = ADRIA.sample(dom, num_scens)\n\n# Run model\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# Calculate difference to the counterfactual for given metric\n_relative_cover = metrics.relative_cover(rs)\n\n# Compute difference between guided and counterfactual using the 0.6-th quantile\ngd_res = metrics.ensemble_loc_difference(r_cover, scens; agg_metric=0.6)\n\n# Compute difference between unguided and counterfactual using the median\nug_res = metrics.ensemble_loc_difference(r_cover, scens; diff_target=:unguided)\n\n# Plot maps of difference to the counterfactual\nADRIA.viz.map(rs, gd_res[summary=At(:agg_value)]; diverging=true)\nADRIA.viz.map(rs, ug_res[summary=At(:agg_value)]; diverging=true)\n\nReturns\n\nVector with bootstrapped difference (counterfactual - guided) for each location.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.fill_axes_metadata!-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.fill_axes_metadata!","text":"fill_axes_metadata!(outcomes::YAXArray)::Nothing\n\nFill outcomes axes metadata.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.fill_metadata!-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{YAXArrays.Cubes.YAXArray{T, N, A}, ADRIA.metrics.Metric}} where {T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.fill_metadata!","text":"fill_metadata!(outcomes::YAXArray{T,N,A}, metric::Metric)::YAXArray{T,N,A} where {T,N,A}\nfill_metadata!(outcomes::YAXArray{T,N,A}, metadata::Dict{Symbol,Any})::YAXArray{T,N,A} where {T,N,A}\n\nFill outcomes YAXArray metadata (properties attribute).\n\nArguments\n\noutcomes : YAXArray datacube of metric outcomes.\nmetric : ADRIA.metrics.Metric object.\nmetadata : Dict to be used to fill outcomes metrics metadata.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.fog_ranks-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.fog_ranks","text":"fog_ranks(rs::ResultSet; kwargs...)\n\nArguments\n\nrs : ResultSet\nkwargs : named dimensions to slice across\n\nReturns\n\nYAXArray[timesteps, sites, scenarios]\n\nExample\n\nADRIA.metrics.fog_ranks(rs; timesteps=1:10, scenarios=3:5)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.loc_trajectory-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{D}, Tuple{Any, YAXArrays.Cubes.YAXArray{D, T, N, A}}} where {D, T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.loc_trajectory","text":"loc_trajectory(metric, data::YAXArray{D,T,N,A})::YAXArray where {D,T,N,A}\n\nAlias for summarize(data, [:scenarios], metric). Collate trajectory for each location.\n\nExamples\n\nusing Statistics\n\nrs = ADRIA.load_results(\"some results\")\ntac = ADRIA.metrics.total_absolute_cover(rs)\n\n# Get median trajectory for each site\nADRIA.metrics.loc_trajectory(median, tac)\n#75×216 YAXArray{Float64,2} with dimensions:\n# Dim{:timesteps} Categorical{Any} Any[1, 2, …, 74, 75] Unordered,\n# Dim{:locations} Categorical{Any} Any[1, 2, …, 215, 216] Unordered\n#Total size: 126.56 KB\n\n# Get upper 95% CI for each site\nADRIA.metrics.loc_trajectory(x -> quantile(x, 0.975), tac)\n#75×216 YAXArray{Float64,2} with dimensions:\n# Dim{:timesteps} Categorical{Any} Any[1, 2, …, 74, 75] Unordered,\n# Dim{:locations} Categorical{Any} Any[1, 2, …, 215, 216] Unordered\n#Total size: 126.56 KB\n\nArguments\n\nmetric : Any function (nominally from the Statistics package) to be applied to data\ndata : Data set to apply metric to\n\nReturns\n\n2D array of T S, where T is total number of time steps and S is number of locations\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.metadata-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.metadata","text":"metadata(outcomes::YAXArray)::Dict{Symbol,Any}\n\nHelper function to extract metadata from YAXArrays.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.metric_label-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.metric_label","text":"metric_label(m::Metric)::String\nmetric_label(f::Function, unit::String)\n\nReturn name of metric in the format: \"Title Case [Unit]\", suitable for use as a label.\n\nExample\n\nm_label = metric_label(scenario_total_cover)\n# \"Scenario Total Cover [m²]\"\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.n_fog_locations-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.n_fog_locations","text":"n_fog_locations(rs::ResultSet; kwargs...)::Matrix{Int64}\n\nDetermine the number of locations fogged at each time step, for each scenario.\n\nReturns\n\nYAXArray[timesteps ⋅ scenarios] indicating the number of locations fogged at each time step.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.n_seed_locations-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.n_seed_locations","text":"n_seed_locations(rs::ResultSet; kwargs...)::Matrix{Int64}\n\nDetermine the number of locations seeded at each time step, for each scenario.\n\nReturns\n\nYAXArray[timesteps ⋅ scenarios] indicating the number of locations seeded at each time step.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.nds","page":"ADRIA API","title":"ADRIA.metrics.nds","text":"nds(X::AbstractArray{<:Real}, dist::Int64=0)::Vector{Vector{<:Int}}\n\nNaive n-dimensional non-dominated sorting.\n\nAdapted from: https://discourse.julialang.org/t/fast-optimized-non-dominated-sorting-algorithms/86793/7\n\nOriginal function name is nds4()\n\nArguments\n\nX : outcomes, where rows are scenarios and columns are metric results. dist : distance from front, where 0 is on the frontier.\n\nReturns\n\nVector of Vectors with row indices for each dist from frontier, where 0 is on the frontier.\n\n\n\n\n\n","category":"function"},{"location":"API/#ADRIA.metrics.per_loc-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{D}, Tuple{Any, YAXArrays.Cubes.YAXArray{D, T, N, A}}} where {D, T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.per_loc","text":"per_loc(metric, data::YAXArray{D,T,N,A})::YAXArray where {D,T,N,A}\n\nAlias for summarize(data, [:scenarios, :timesteps], metric). Get metric results applied to the location-level at indicated time (or across timesteps).\n\nArguments\n\nmetric : Any function (nominally from the Statistics package) to be applied to data\ndata : Data set to apply metric to\ntimesteps : timesteps to apply metric across\n\nReturns\n\nNamed Vector of N elements, where N is the number of locations.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.scenario_outcomes-Tuple{ADRIA.ResultSet, Vector{<:ADRIA.metrics.Metric}}","page":"ADRIA API","title":"ADRIA.metrics.scenario_outcomes","text":"scenario_outcomes(rs::ResultSet, metrics::Vector{Metric})::YAXArray\n\nGet outcomes for a given list of metrics and a result set.\n\nArguments\n\nrs : ResultSet\nmetrics : Vector of scenario Metrics (the ones that start with scenario_)\n\nReturns\n\nYAXArray with (:timesteps, :scenarios, :outcomes)\n\nExamples\n\nmetrics::Vector{ADRIA.metrics.Metric} = [\n ADRIA.metrics.scenario_total_cover,\n ADRIA.metrics.scenario_asv,\n ADRIA.metrics.scenario_absolute_juveniles,\n]\n\n# 3-dimensional Array of outcomes\noutcomes = ADRIA.metrics.scenario_outcomes(rs, metrics)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.scenario_trajectory-Tuple{AbstractArray}","page":"ADRIA API","title":"ADRIA.metrics.scenario_trajectory","text":"scenario_trajectory(data::AbstractArray; metric=mean)::YAXArray{<:Real}\n\nProduce scenario trajectories using the provided metric/aggregation function.\n\nArguments\n\ndata : Results to aggregate\nmetric : Function or Callable used to summarize data\n\nReturns\n\nMatrix[timesteps ⋅ scenarios]\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.seed_ranks-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.metrics.seed_ranks","text":"seed_ranks(rs::ResultSet; kwargs...)\n\nArguments\n\nrs : ResultSet\nkwargs : named dimensions to slice across\n\nReturns\n\nYAXArray[timesteps, sites, scenarios]\n\nExample\n\nADRIA.metrics.seed_ranks(rs; timesteps=1:10, scenarios=3:5)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.slice_results-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.slice_results","text":"slice_results(data::YAXArray; timesteps=(:), species=(:), locations=(:), scenarios=(:))\n\nSlice data as indicated. Dimensions not found in target data are ignored.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize-Union{Tuple{A}, Tuple{N}, Tuple{T}, Tuple{D}, Tuple{YAXArrays.Cubes.YAXArray{D, T, N, A}, Vector{Symbol}, Function}} where {D, T, N, A}","page":"ADRIA API","title":"ADRIA.metrics.summarize","text":"summarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function)::YAXArray{<:Real}\nsummarize(data::YAXArray{<:Real}, alongs_axis::Vector{Symbol}, metric::Function, timesteps::Union{UnitRange,Vector{Int64},BitVector})::YAXArray{<:Real}\n\nApply summary metric along some axis of a data set across some or all timesteps.\n\nArguments\n\ndata : Data set to apply metric to.\nalongs_axis : which axis will be replaced with (:) when slicing.\nmetric : Any function (nominally from the Statistics package) to be applied to data.\ntimesteps : timesteps to apply metric across.\n\nReturns\n\nYAXArray with summary metric for the remaining axis.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_absolute_shelter_volume-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_absolute_shelter_volume","text":"summarize_absolute_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_absolute_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized coral evenness.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_coral_evenness-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_coral_evenness","text":"summarize_coral_evenness(raw::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_coral_evenness(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized coral evenness.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_raw-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_raw","text":"summarize_raw(data::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nSummarize raw data, aggregating the specified dimensions (e.g., timesteps, scenarios, etc.) and collapsing given dims.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_relative_cover-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_relative_cover","text":"summarize_relative_cover(rc::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_relative_cover(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized relative cover.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_relative_shelter_volume-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.summarize_relative_shelter_volume","text":"summarize_relative_shelter_volume(sv::YAXArray; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_relative_shelter_volume(rs::ResultSet, kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized coral evenness.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.summarize_total_cover-Tuple{YAXArrays.Cubes.YAXArray, AbstractArray{<:Real}}","page":"ADRIA API","title":"ADRIA.metrics.summarize_total_cover","text":"summarize_total_cover(raw::YAXArray, areas::AbstractArray{<:Real}; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\nsummarize_total_cover(rs::ResultSet; kwargs...)::Dict{Symbol,AbstractArray{<:Real}}\n\nCalculate summarized total absolute cover.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.to_string-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.to_string","text":"to_string(m::Metric)::String\n\nGet name of metric as a string.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.to_symbol-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"ADRIA.metrics.to_symbol","text":"to_symbol(m::Metric)::String\n\nGet name of metric as a symbol.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.top_N_sites-Tuple{ADRIA.ResultSet, Int64}","page":"ADRIA API","title":"ADRIA.metrics.top_N_sites","text":"top_N_sites(rs::ResultSet; N::Int64; metric::relative_cover)\ntop_N_sites(data::AbstractArray{Real}, N::Int64; stat=mean)\n\nReturn the top N sites according to the provided metric (defaulting to mean of relative_cover).\n\nArguments\n\nrs : ResultSet\nN : Number of best performing sites to be selected\nmetric : Metric to use to order sites from best to worst, must take ResultSet as input\nstat : Summary statistic to use for comparison (default: mean)\n\nReturns\n\nYAXArray[:scenarios, :locations], where locations indicates order of location ranking.\n\nExample\n\nADRIA.metrics.top_N_sites(rs, 5)\nADRIA.metrics.top_N_sites(rs, 5; metric=ADRIA.metric.relative_cover)\nADRIA.metrics.top_N_sites(rs, 5; metric=ADRIA.metric.relative_cover, stat=median)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.top_n_seeded_sites-Tuple{ADRIA.ResultSet, Int64}","page":"ADRIA API","title":"ADRIA.metrics.top_n_seeded_sites","text":"top_n_seeded_sites(rs::ResultSet, n::Int64; kwargs...)\n\nGet the top n seeded sites over time by their unique location id. Lower rank values are better (e.g., 1 = first choice)\n\nArguments\n\nrs : ResultSet\nn : n locations to retrieve\nkwargs : dimensions to slice across\n\nReturns\n\nYAXArray[locations, [locid, locname, rank], scenarios]\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.trajectory_heatmap-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.trajectory_heatmap","text":"trajectory_heatmap(data::YAXArray)::HeatMap\n\nEstimate heatmap of trajectories from a 2D dataset.\n\nArguments\n\ndata : An N*D matrix where N is time steps and D is the scenario outcome for the given timestep in N\n\nReturns\n\nOnlineStats.HeatMap\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.trajectory_heatmap_data-Tuple{YAXArrays.Cubes.YAXArray}","page":"ADRIA API","title":"ADRIA.metrics.trajectory_heatmap_data","text":"trajectory_heatmap_data(data::YAXArray)::Tuple{Vector{Float64},Vector{Float64},Matrix{Int64}}\n\nEstimate heatmap of trajectories from a 2D dataset.\n\nArguments\n\ndata : An N*D matrix where N is time steps and D is the scenario outcome for the given timestep in N\n\nReturns\n\nTuple of xedges, yedges, and bi-dimensional histogram matrix\n\n\n\n\n\n","category":"method"},{"location":"API/#Base.ndims-Tuple{ADRIA.metrics.Metric}","page":"ADRIA API","title":"Base.ndims","text":"ndims(m::Metric)::Int64\n\nInfer the number of dimensions for a given outcome/metric.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.metrics.Metric-Tuple{Any, Vararg{Any}}","page":"ADRIA API","title":"ADRIA.metrics.Metric","text":"(f::Metric)(raw, args...; kwargs...)\n(f::Metric)(rs::ResultSet, args...; kwargs...)\n\nMakes Metric types callable with arbitary arguments that are passed to associated function.\n\n\n\n\n\n","category":"method"},{"location":"API/#Performance-indicators","page":"ADRIA API","title":"Performance indicators","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA.performance]\nOrder = [:function, :type]","category":"page"},{"location":"API/#ADRIA.performance.RMSE-Tuple{Any, Any}","page":"ADRIA API","title":"ADRIA.performance.RMSE","text":"Root Mean Square Error\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.environmental_diversity-Tuple{Any, Any}","page":"ADRIA API","title":"ADRIA.performance.environmental_diversity","text":"environmental_diversity(ms, inputs_i)\n\nObtain an indication of environmental factor diversity for a scenario set. Higher values indicate a greater of mix of environmental conditions were experienced between scenarios.\n\nThis is referred to as E.\n\nArguments\n\nms : model spec\ninputs_i : inputs used for scenarios of interest\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.gmd-Tuple{AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.gmd","text":"gmd(vals::AbstractVector{<:Real})::Float64\ngmd(vals::AbstractMatrix{<:Real})\n\nGini's Mean Difference.\n\nThe absolute mean of all pairwise distances between elements in a given set.\n\nReferences\n\nLa 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\nYitzhaki, 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\nKashif, 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.intervention_diversity-Tuple{Any, Any}","page":"ADRIA API","title":"ADRIA.performance.intervention_diversity","text":"intervention_diversity(ms, inputs_i)\n\nObtain an indication of intervention diversity for a scenario. Higher values indicate a greater of mix of interventions options were applied.\n\nThis is referred to as D.\n\nArguments\n\nms : model spec\ninputs_i : inputs used for scenarios of interest\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.intervention_effort-Tuple{Any, Any, Any}","page":"ADRIA API","title":"ADRIA.performance.intervention_effort","text":"intervention_effort(ms, inputs_i)\n\nObtain an indication of intervention effort for each scenario and intervention type. This is referred to as F.\n\nArguments\n\nms : model spec\ninputs_i : inputs used for scenarios of interest\n\nReturns\n\nMatrix 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.normalize-Tuple{AbstractArray{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.normalize","text":"normalize(vals::AbstractArray{<:Real})\n\nNormalize values using feature scaling such that values are bound between 0 and 1, where 1 is equivalent to the maximum value found.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.probability-Tuple{AbstractArray{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.probability","text":"probability(vals::AbstractArray{<:Real})\n\nCalculate probability of individual trajectories, given a scenario ensemble S.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.performance.temporal_variability-Tuple{AbstractVector{<:Real}}","page":"ADRIA API","title":"ADRIA.performance.temporal_variability","text":"temporal_variability(x::AbstractVector{<:Real})\ntemporal_variability(x::AbstractArray{<:Real, 2})\ntemporal_variability(x::AbstractArray{<:Real}, func_or_data...)\n\nThe V meta-metric.\n\nAs 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.\n\nExamples\n\n# Apply V to a time series\njulia> temporal_variability(rand(50))\n\n# Apply V to an ensemble of time series\njulia> x = rand(50, 200)\njulia> temporal_variability(x)\n\n# Create and apply a modified V metric to an ensemble of time series.\n# Where the argument is an array and not a function, the data is used directly\n# and so it is assumed all matrices are of the same size and shape.\njulia> temporal_variability(x, temporal_variabilty, temporal_variability(P(x)))\njulia> temporal_variability(x, temporal_variabilty, P(x), D(x), E(x))\n\n\n\n\n\n","category":"method"},{"location":"API/#Sensitivity","page":"ADRIA API","title":"Sensitivity","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA.sensitivity]\nOrder = [:function, :type]","category":"page"},{"location":"API/#ADRIA.sensitivity._category_bins-Tuple{DataFrames.DataFrame}","page":"ADRIA API","title":"ADRIA.sensitivity._category_bins","text":"_category_bins(foi_spec::DataFrame)::Int64\n\nGet number of bins for categorical variables.\n\nArguments\n\nfoi_spec : Model specification for factors of interest\n\nReturns\n\nNumber of bins relevant to the factor of interest\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._create_seq_store-Tuple{DataFrames.DataFrame, Vector{Symbol}, Int64}","page":"ADRIA API","title":"ADRIA.sensitivity._create_seq_store","text":"_create_seq_store(model_spec::DataFrame, unordered_cat::Vector{Symbol}, S::Int64)::Dict{Symbol,Vector{Float64}}\n\nGet stored bin sequences for each factor type.\n\nArguments\n\nmodel_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet\nunordered_cat : Factors considered for sensitivity analysis of unordered categorical type.\nS : Number of bins.\n\nReturns\n\nA dictionary containing bin sequences for each factor\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._foi_data_stores-Tuple{Dict{Symbol, Vector{Float64}}, DataFrames.DataFrame, Vector{Symbol}, NamedTuple}","page":"ADRIA API","title":"ADRIA.sensitivity._foi_data_stores","text":"_foi_data_stores(\n seq_store::Dict{Symbol,Vector{Float64}},\n m_spec::DataFrame,\n unordered_cat::Vector{Symbol};\n second_dim::NamedTuple\n)::Dataset\n\nGenerate data stores of correct size for each factor of interest.\n\nArguments\n\nseq_store : Dictionary for storing bin sequences (created by _create_seq_store)\nm_spec : Model specification\nunordered_cat : List of unordered categorical variables.\nsecond_dim : second storage dimension (e.g. (CI=[\"mean\",\"lower\",\"upper\"], ))\n\nReturns\n\nDataset containing storage for sensitivity ranges for each factor.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._get_cat_quantile-Tuple{DataFrames.DataFrame, Symbol, Vector{Float64}}","page":"ADRIA API","title":"ADRIA.sensitivity._get_cat_quantile","text":"_get_cat_quantile(foi_spec::DataFrame, factor_name::Symbol, steps::Vector{Float64})::Vector{Float64}\n\nGet quantiles for a given categorical variable.\n\nArguments\n\nfoi_spec : Model specification for factors of interest\nfactor_name : Contains true where the factor is categorical and false otherwise\nsteps : Number of steps for defining bins\n\nReturns\n\nQuantile for a categorical factor.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._get_factor_quantile-Tuple{Dict{Symbol, Vector{Float64}}, DataFrames.DataFrame, Vector{Float64}, Symbol}","page":"ADRIA API","title":"ADRIA.sensitivity._get_factor_quantile","text":"_get_factor_quantile(seq_store::Dict{Symbol,Vector{Float64}}, foi_spec::DataFrame, fact_t::Symbol)\n\nChecks the type of the factor to calculate its quantile.\n\nArguments\n\nseq_store : storage containing bin sequences for factors considered\nfoi_spec : Model specification for factors of interest\nX_f : Scenario dataframe for factor of interest\nfactor_name : Contains true where the factor is categorical and false otherwise\n\nReturns\n\nQuantile for factor fact_t, given bin sequences in seq_store\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._get_factor_spec-Tuple{DataFrames.DataFrame, Vector{Symbol}}","page":"ADRIA API","title":"ADRIA.sensitivity._get_factor_spec","text":"_get_factor_spec(model_spec::DataFrame, factors::Vector{Symbol})::DataFrame\n\nGet model spec for specified factors.\n\nArguments\n\nmodel_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet\nfactors : Factors considered for sensitivity analysis\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity._map_outcomes-Tuple{AbstractVecOrMat{<:Real}, Union{BitVector, Vector{Int64}}}","page":"ADRIA API","title":"ADRIA.sensitivity._map_outcomes","text":"_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Union{BitVector,Vector{Int64}})::Union{BitVector,Vector{Int64}}\n_map_outcomes(y::AbstractVecOrMat{<:Real}, rule::Function)::Vector{Int64}\n\nApply rule to create mapping between X (model inputs/parameters/factors) and y (model outcomes).\n\nNote\n\nWhere the rule is a vector indicating true/false, the y argument is ignored. The function accepts the y argument simply to maintain compatibility so the same method name can be applied.\n\nArguments\n\ny : Model outputs/outcomes\nrule : BitVector, or Function that returns a BitVector, indicating outcomes that meet some desired threshold/behavior.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.convergence-Tuple{DataFrames.DataFrame, YAXArrays.Cubes.YAXArray, Vector{Symbol}}","page":"ADRIA API","title":"ADRIA.sensitivity.convergence","text":"convergence(X::DataFrame, y::YAXArray, target_factors::Vector{Symbol}; n_steps::Int64=10)::YAXArray\nconvergence(rs::ResultSet, X::DataFrame, y::YAXArray, components::Vector{String}; n_steps::Int64=10)::YAXArray\n\nCalculates 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.\n\nArguments\n\nrs : Result set (only needed if aggregating over model components).\nX : Model inputs\ny : Model outputs\ntarget_factors : Names of target factors represented by columns in X.\ncomponents : Names of model components to aggregate over (e.g. [:Intervention, :Criteria]).\nn_steps : Number of steps to cut the total number of scenarios into.\n\nReturns\n\nYAXArray, of min, lower bound, mean, median, upper bound, max, std, and cv summary statistics for an increasing number of scenarios.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.ks_statistic-Tuple{HypothesisTests.ApproximateKSTest}","page":"ADRIA API","title":"ADRIA.sensitivity.ks_statistic","text":"ks_statistic(ks)\n\nCalculate the Kolmogorov-Smirnov test statistic.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.outcome_map-Tuple{YAXArrays.Cubes.YAXArray, AbstractArray, AbstractArray, AbstractVecOrMat{<:Real}, BitVector}","page":"ADRIA API","title":"ADRIA.sensitivity.outcome_map","text":"outcome_map(p::YAXArray, X_q::AbstractArray, X_f::AbstractArray, y::AbstractVecOrMat{<:Real}, behave::BitVector; n_boot::Int64=100, conf::Float64=0.95)::YAXArray\noutcome_map(X::DataFrame, y::AbstractVecOrMat{<:Real}, rule::Union{Function,BitVector,Vector{Int64}}, target_factors::Vector{Symbol}, model_spec::DataFrame; S::Int64=10, n_boot::Int64=100, conf::Float64=0.95)::Dataset\noutcome_map(X::DataFrame, y::AbstractVecOrMat{<:Real}, rule::Union{Function,BitVector,Vector{Int64}}, target_factor::Symbol, model_spec::DataFrame; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::YAXArray\noutcome_map(X::DataFrame, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}\noutcome_map(rs::ResultSet, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}, target_factors::Vector{Symbol}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}\noutcome_map(rs::ResultSet, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}, target_factor::Symbol; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::YAXArray where {T<:Real}\noutcome_map(rs::ResultSet, y::AbstractVector{T}, rule::Union{Function,BitVector,Vector{Int64}}; S::Int64=20, n_boot::Int64=100, conf::Float64=0.95)::Dataset where {T<:Real}\n\nMap normalized outcomes (defined by rule) to factor values discretized into S bins.\n\nProduces 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.\n\nNote:\n\ny is normalized on a per-column basis prior to the analysis\nEmpty areas of factor space (those that do not have any desired outcomes) will be assigned NaN\n\nArguments\n\nX : scenario specification\ny : Vector or Matrix of outcomes corresponding to scenarios in X\nrule : a callable defining a \"desirable\" scenario outcome\ntarget_factors : list of factors of interest to perform analyses on\nS : number of slices of factor space. Higher values equate to finer granularity\nn_boot : number of bootstraps (default: 100)\nconf : confidence interval (default: 0.95)\n\nReturns\n\n3-dimensional YAXArray, of shape S ⋅ D ⋅ 3, where:\n\nS\nis the slices,\nD\nis the number of dimensions, with\nboostrapped mean (dim 1) and the lower/upper 95% confidence interval (dims 2 and 3).\n\nExamples\n\n# Get metric of interest\nmu_tac = vec(mean(ADRIA.metrics.scenario_total_cover(rs), dims=:timesteps))\n\n# Factors of interest\nfoi = [:SRM, :fogging, :a_adapt]\n\n# Find scenarios where all metrics are above their median\nrule = y -> all(y .> 0.5)\n\n# Map input values where to their outcomes\nADRIA.sensitivity.outcome_map(X, y, rule, foi; S=20, n_boot=100, conf=0.95)\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.pawn-Tuple{AbstractMatrix{<:Real}, AbstractVector{<:Real}, Vector{String}}","page":"ADRIA API","title":"ADRIA.sensitivity.pawn","text":"pawn(rs::ResultSet, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray\npawn(X::AbstractMatrix{<:Real}, y::AbstractVector{<:Real}, factor_names::Vector{String}; S::Int64=10)::NamedDimsArray\npawn(X::DataFrame, y::AbstractVector{<:Real}; S::Int64=10)::NamedDimsArray\npawn(X::NamedDimsArray, y::Union{NamedDimsArray,AbstractVector{<:Real}}; S::Int64=10)::NamedDimsArray\npawn(X::Union{DataFrame,AbstractMatrix{<:Real}}, y::AbstractMatrix{<:Real}; S::Int64=10)::NamedDimsArray\n\nCalculates the PAWN sensitivity index.\n\nThe 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.\n\nThis 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.\n\nArguments\n\nrs : ResultSet\nX : Model inputs\ny : Model outputs\nfactor_names : Names of each factor represented by columns in X\nS : Number of slides (default: 10)\n\nReturns\n\nYAXArray, of min, mean, lower bound, median, upper bound, max, std, and cv summary statistics.\n\nExamples\n\ndom = ADRIA.load_domain(\"example_domain\")\nscens = ADRIA.sample(dom, 128)\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n\n# Get mean coral cover over time and locations\nμ_tac = mean(ADRIA.metrics.scenario_total_cover(rs), dims=:timesteps)\n\nADRIA.sensitivity.pawn(rs, μ_tac)\n\nReferences\n\nPianosi, 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\nBaroni, G., Francke, T., 2020. GSA-cvd Combining variance- and distribution-based global sensitivity analysis https://github.com/baronig/GSA-cvd\nPuy, 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\nhttps://github.com/SAFEtoolbox/Miscellaneous/blob/main/ReviewofPuy_2020.pdf\n\nExtended help\n\nPianosi 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.\n\nPuy et al., found that the ratio of N (number of samples) to S has to be sufficiently high (NS 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 (102410 = 1024). Additionally, lower values of NS is more an indication of faulty experimental design moreso than any deficiency of the PAWN method.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.rsa-Union{Tuple{T}, Tuple{DataFrames.DataFrame, AbstractVector{T}, DataFrames.DataFrame}} where T<:Real","page":"ADRIA API","title":"ADRIA.sensitivity.rsa","text":"rsa(X::DataFrame, y::AbstractVector{<:Real}, model_spec::DataFrame; S::Int64=10)::Dataset\nrsa(r_s::YAXArray, X_q::AbstractArray, X_i::AbstractArray, y::AbstractVecOrMat{<:Real}, sel::BitVector)::YAXArray\nrsa(X::Vector{Float64}, y::AbstractVector{<:Real}, foi_spec::DataFrame; S::Int64=10)::YAXArray\nrsa(rs::ResultSet, y::AbstractVector{T}; S::Int64=10)::Dataset where {T<:Real}\nrsa(rs::ResultSet, y::AbstractVector{T}, factors::Vector{Symbol}; S::Int64=10)::Dataset where {T<:Real}\nrsa(rs::ResultSet, y::AbstractVector{T}, factor::Symbol; S::Int64=10)::YAXArray where {T<:Real}\n\nPerform Regional Sensitivity Analysis.\n\nRegional 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.\n\nThe 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.\n\nRSA can indicate where in factor space model sensitivities may be, and contributes to a Value-of-Information (VoI) analysis.\n\nIncreasing the value of S increases the granularity of the analysis, but necessitates larger sample sizes.\n\nNote: Values of type missing indicate a lack of samples in the region.\n\nArguments\n\nrs : ResultSet\nX : scenario specification\ny : scenario outcomes\nmodel_spec : Model specification, as extracted by ADRIA.model_spec(domain) or from a ResultSet\nfactors : Specific model factors to examine\nS : number of bins to slice factor space into (default: 10)\n\nReturns\n\nDataset\n\nExamples\n\nADRIA.sensitivity.rsa(X, y; S=10)\n\nReferences\n\nPianosi, 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\nSaltelli, 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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.sensitivity.tsa-Tuple{DataFrames.DataFrame, AbstractMatrix{<:Real}}","page":"ADRIA API","title":"ADRIA.sensitivity.tsa","text":"tsa(X::DataFrame, y::AbstractMatrix)::YAXArray\n\nPerform Temporal (or time-varying) Sensitivity Analysis using the PAWN sensitivity index.\n\nThe 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.\n\nExamples\n\nrs = ADRIA.load_results(\"a ResultSet of interest\")\n\n# Get scenario outcomes over time (shape: `time ⋅ scenarios`)\ny_tac = ADRIA.metrics.scenario_total_cover(rs)\n\n# Calculate sensitivity of outcome to factors for each time step\nADRIA.sensitivity.tsa(rs.inputs, y_tac)\n\nArguments\n\nX : Scenario specification\ny : scenario outcomes over time\n\nReturns\n\nYAXArray, of shape D ⋅ 6 ⋅ T, where\n\nD\nis the number of dimensions/factors\n6 corresponds to the min, mean, median, max, std, and cv of the PAWN indices\nT\nis the number of time steps\n\n\n\n\n\n","category":"method"},{"location":"API/#General-API","page":"ADRIA API","title":"General API","text":"","category":"section"},{"location":"API/","page":"ADRIA API","title":"ADRIA API","text":"Modules = [ADRIA]\nOrder = [:function, :type]\nPrivate = false","category":"page"},{"location":"API/#ADRIA.coral_spec-Tuple{}","page":"ADRIA API","title":"ADRIA.coral_spec","text":"coral_spec()\n\nTemplate for coral parameter values for ADRIA. Includes \"vital\" bio/ecological parameters, to be filled with sampled or user-specified values.\n\nAny parameter added to the params DataFrame defined here will automatically be made available to the ADRIA model.\n\nNotes: Values for the historical, temporal patterns of degree heating weeks between bleaching years come from [1].\n\nReturns\n\nparams : NamedTuple[taxanames, paramnames, params], taxa names, parameter names, and parameter values for each coral taxa, group and size class\n\nReferences\n\nLough, 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\nHall, 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\nBozec, 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\nBozec, 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\nBairos-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\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.create_coral_struct","page":"ADRIA API","title":"ADRIA.create_coral_struct","text":"create_coral_struct(bounds=(0.9, 1.1))\n\nGenerates Coral struct using the default parameter spec.\n\nExample\n\n# Define coral struct with auto-generated parameter ranges\n# (default in ADRIA is ± 10%, triangular distribution with peak at 0.5)\ncreate_coral_struct()\ncoral = Coral()\n\n# Recreate coral spec ± 50% from nominal values\ncreate_coral_struct((0.5, 1.5))\ncoral = Coral()\n\n\n\n\n\n","category":"function"},{"location":"API/#ADRIA.env_stats-Tuple{ADRIA.ResultSet, String, String}","page":"ADRIA API","title":"ADRIA.env_stats","text":"env_stats(rs::ResultSet, s_name::String, rcp::String)\nenv_stats(rs::ResultSet, s_name::String, rcp::String, scenario::Int)\nenv_stats(rs::ResultSet, s_name::String, stat::String, rcp::String, scenario::Int)\n\nExtract statistics for a given environmental layer (\"DHW\" or \"wave\")\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.growthODE-Tuple{Matrix{Float64}, Matrix{Float64}, NamedTuple, Real}","page":"ADRIA API","title":"ADRIA.growthODE","text":"growthODE(du, X, p, _)\n\nBase coral growth function.\n\nProportion 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.\n\nNote 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_locs), recruitment is a 6 by n_locs array.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.loc_area-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.loc_area","text":"loc_area(rs::ResultSet)::Vector{Float64}\n\nExtract vector of a location's total area in its areal unit (m², km², etc).\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.loc_area-Tuple{Domain}","page":"ADRIA API","title":"ADRIA.loc_area","text":"loc_area(domain::Domain)::Vector{Float64}\n\nGet site area for the given domain.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.run_scenario-Tuple{Domain, Int64, Union{DataFrames.DataFrameRow, AbstractVector}, Vector{Vector{CoralBlox.FunctionalGroup}}, NamedTuple}","page":"ADRIA API","title":"ADRIA.run_scenario","text":"run_scenario(domain::Domain, idx::Int64, scenario::Union{AbstractVector,DataFrameRow}, functional_groups::Vector{Vector{FunctionalGroup}}, data_store::NamedTuple)::Nothing\nrun_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow})::NamedTuple\nrun_scenario(domain::Domain, scenario::Union{AbstractVector,DataFrameRow}, RCP::String)::NamedTuple\n\nRun 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.\n\nArguments\n\ndomain : Domain\nidx : Scenario index\n\nReturns\n\nNothing\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.select-Tuple{ADRIA.ResultSet, String}","page":"ADRIA API","title":"ADRIA.select","text":"select(r::ResultSet, op::String)\n\nHacky scenario filtering - to be replaced with more robust approach.\n\nOnly supports filtering by single attribute. Should be expanded to support filtering metric results too.\n\nExamples\n\nselect(result, \"guided .> 0.0\")\n\n# Above expands to:\n# result.inputs.guided .> 0.0\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.site_k_area-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.site_k_area","text":"site_k_area(rs::ResultSet)::Vector{Float64}\n\nExtract vector of a location's coral carrying capacity in terms of absolute area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.site_k_area-Tuple{Domain}","page":"ADRIA API","title":"ADRIA.site_k_area","text":"site_k_area(domain::Domain)::Vector{Float64}\n\nGet maximum coral cover area for the given domain in absolute area.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.timesteps-Tuple{ADRIA.ResultSet}","page":"ADRIA API","title":"ADRIA.timesteps","text":"timesteps(rs::ResultSet)\n\nRetrieve the time steps represented in the result set.\n\nArguments\n\nrs : ResultSet\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.timesteps-Tuple{Domain}","page":"ADRIA API","title":"ADRIA.timesteps","text":"Extract the time steps represented in the data package.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.ADRIADomain","page":"ADRIA API","title":"ADRIA.ADRIADomain","text":"ADRIADomain{Σ,M,I,D,X,Y,Z}\n\nCore ADRIA domain. Represents study area.\n\n\n\n\n\n","category":"type"},{"location":"API/#ADRIA.Domain-Tuple{String, String, String, Vector, Vararg{String, 8}}","page":"ADRIA API","title":"ADRIA.Domain","text":"Domain(name::String, rcp::String, timeframe::Vector, location_data_fn::String, location_id_col::String, cluster_id_col::String, init_coral_fn::String, conn_path::String, dhw_fn::String, wave_fn::String, cyclone_mortality_fn::String)::Domain\n\nConvenience constructor for Domain.\n\nArguments\n\nname : Name of domain\ndpkg_path : location of data package\nrcp : RCP scenario represented\ntimeframe : Time steps represented\nlocation_data_fn : File name of spatial data used\nlocation_id_col : Column holding name of reef the location is associated with (non-unique)\ncluster_id_col : Column holding unique cluster names/ids\ninit_coral_fn : Name of file holding initial coral cover values\nconn_path : Path to directory holding connectivity data\ndhw_fn : Filename of DHW data cube in use\nwave_fn : Filename of wave data cube\ncyclone_mortality_fn : Filename of cyclone mortality data cube\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.Domain-Union{Tuple{T}, Tuple{String, String, ADRIA.EnvLayer, YAXArrays.Cubes.YAXArray{T, N, A} where {N, A<:AbstractArray{T, N}}, DataFrames.DataFrame, String, String, YAXArrays.Cubes.YAXArray, ADRIA.CoralGrowth, Vector{String}, Vector{String}, YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray, YAXArrays.Cubes.YAXArray}} where T<:Union{Float32, Float64}","page":"ADRIA API","title":"ADRIA.Domain","text":"Barrier function to create Domain struct without specifying Intervention/Criteria/Coral/SimConstant parameters.\n\n\n\n\n\n","category":"method"},{"location":"API/#ADRIA.SimConstants","page":"ADRIA API","title":"ADRIA.SimConstants","text":"SimConstants\n\nStruct of simulation constants for ADRIA\n\nReferences\n\nLough, 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\nHughes, 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\nBozec, 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\nBozec, 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\n\n\n\n\n\n","category":"type"},{"location":"usage/results/#Loading-Results","page":"Loading Results","title":"Loading Results","text":"","category":"section"},{"location":"usage/results/#Loading-ReefModEngine-Results","page":"Loading Results","title":"Loading ReefModEngine Results","text":"","category":"section"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"Results from ReefModEngine.jl can be loaded with the load_results function.","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"rs = ADRIA.load_results(RMEResultSet, \"\")","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"Expected data directory structure:","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"data_dir\n│\n├───con_bin\n│ CONNECT_ACRO_2010_11.bin\n│ CONNECT_ACRO_2011_12.bin\n│ CONNECT_ACRO_2012_13.bin\n│ CONNECT_ACRO_2014_15.bin\n│ CONNECT_ACRO_2015_16.bin\n│ CONNECT_ACRO_2016_17.bin\n│\n├───id\n│ id_list_2023_03_30.csv\n│\n├───region\n│ reefmod_gbr.gpkg\n│\n└───results\n results.nc\n scenarios.csv","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"In order to reduce the duplication of geospatial and conectivity data, the data directory and results directory can be supplied seperately to avoid having copies for each resuilt set analysed.","category":"page"},{"location":"usage/results/","page":"Loading Results","title":"Loading Results","text":"rs = ADRIA.load_domain(RMEResultSet, \"\", \"\")","category":"page"},{"location":"development/building_docs/#Building-Documentation","page":"Building Documentation","title":"Building Documentation","text":"","category":"section"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"ADRIA documentation is built using Documenter.jl.","category":"page"},{"location":"development/building_docs/#Building-documentation-locally","page":"Building Documentation","title":"Building documentation locally","text":"","category":"section"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"As the documentation is build from a separate environment, it must be maintained/updated to incorporate any changes to ADRIA.","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"$ julia --project=docs\n(docs) pkg> resolve\n(docs) pkg> up","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"If no changes to the environment are necessary, simply run make.jl from the docs folder:","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"$ cd docs\n$ julia --project=. make.jl","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Locally generated documentation can be found under docs/build. Open the index.html file with any web browser.","category":"page"},{"location":"development/building_docs/#Documentation-deployment","page":"Building Documentation","title":"Documentation deployment","text":"","category":"section"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Documentation is hosted on GitHub Pages via GitHub Actions.","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Configuration is found here.","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"Documentation is automatically built and deployed:","category":"page"},{"location":"development/building_docs/","page":"Building Documentation","title":"Building Documentation","text":"When a PR targeting main is submitted In this case, a preview URL is created: e.g., a URL with previews/PR### at the end, where PR### refers to the PR ID.\nOn commit/merge to main In this case the main documentation website is updated","category":"page"},{"location":"usage/analysis/#Analysis","page":"Analysis","title":"Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"This section presents tools for analysing model generate data, including functions to extract metrics and plot graphs.","category":"page"},{"location":"usage/analysis/#Setup","page":"Analysis","title":"Setup","text":"","category":"section"},{"location":"usage/analysis/#Makie","page":"Analysis","title":"Makie","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The Makie.jl ecosystem is used to produce figures.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Install additional packages if necessary","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"]add GeoMakie GraphMakie","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Install a Makie backend of your choice. WGLMakie is more flexible for our workflows, but GLMakie is a good choice too.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"]add WGLMakie","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Import additional packages and the visualization extension will compile.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"using WGLMakie, GeoMakie, GraphMakie\nusing ADRIA\nusing Statistics","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"If using GLMakie, the plots will appear in the VS Code plots pane. You may prefer figures to appear in a separate window, in which case deactivate the inline plotting feature.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Makie.inline!(false)","category":"page"},{"location":"usage/analysis/#Result-Set","page":"Analysis","title":"Result Set","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"All metrics and visualization tools presented here can be used with data generated from ADRIAmod. Following, we show usage examples considering ADRIA result set rs:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Load domain data\ndom = ADRIA.load_domain(\"path to domain data\")\n\n# Create some scenarios\nnum_samples = 4096\nscens = ADRIA.sample(dom, num_samples)\n\n# Run the model for generated scenarios\nrcp_45 = \"45\"\nrs = ADRIA.run_scenarios(dom, scens, rcp_45)\n\n# Visualize results (in terms of scenario absolute coral cover)\ns_tac = ADRIA.metrics.scenario_total_cover(rs)\nADRIA.viz.scenarios(rs, s_tac)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"See the previous sections Loading a Domain, Generating scenarios and Running scenarios for more information.","category":"page"},{"location":"usage/analysis/#Extracting-results","page":"Analysis","title":"Extracting results","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"A range of metrics are defined as part of the ADRIA framework. See the Metrics page for more details.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Here, we extract results for specific metrics for each timestep and sites for all the scenarios run. The result of each line above is a 3-dimensional Array of timesteps, sites and scenarios:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"tac = ADRIA.metrics.total_absolute_cover(rs)\nrsv = ADRIA.metrics.relative_shelter_volume(rs)\njuves = ADRIA.metrics.relative_juveniles(rs)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"We can also look at scenario-level metrics. They aggregate the above metrics across the site dimension and indicate the outcomes under a given intervention (or non-intervention) option and environmental condition.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The result is a 2-dimensional array of timesteps and scenarios:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"s_tac = ADRIA.metrics.scenario_total_cover(rs)\ns_rsv = ADRIA.metrics.scenario_rsv(rs)\ns_juves = ADRIA.metrics.scenario_relative_juveniles(rs)","category":"page"},{"location":"usage/analysis/#Visualization","page":"Analysis","title":"Visualization","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The examples below are to illustrate usage. For further information on each method of analysis, see the documentation for the given function.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Some options shared for the plots below are defined here.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Some shared options for the example plots below\nfig_opts = Dict(:size => (1600, 800))\n\n# Factors of Interest\nopts = Dict(\n :factors => [\n :RCP,\n :dhw_scenario,\n :wave_scenario,\n :guided,\n :N_seed_TA,\n :N_seed_CA,\n :fogging,\n :SRM,\n :a_adapt\n ]\n)","category":"page"},{"location":"usage/analysis/#Scenario-outcomes","page":"Analysis","title":"Scenario outcomes","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"One can plot a quick scenario overview:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"fig_s_tac = ADRIA.viz.scenarios(\n rs, s_tac; fig_opts=fig_opts, axis_opts=Dict(:ylabel => \"Scenario Total Cover\")\n)\nsave(\"scenarios_tac.png\", fig_s_tac)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Quick scenario plots)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"And compose a figure with subplots. In the example below we also use the parameter opts that accepts the keys by_RCP to group scenarios by RCP (default is false), legend to plot the legend (default is true) and summarize to plot confidence intervals instead of plotting each series (default is true):","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"tf = Figure(size=(1600, 600)) # size of figure\n\n# Implicitly create a single figure with 2 columns\nADRIA.viz.scenarios!(\n tf[1, 1],\n rs,\n s_tac;\n opts=Dict(:by_RCP => false, :legend => false),\n axis_opts=Dict(:title => \"TAC [m²]\"),\n);\nADRIA.viz.scenarios!(\n tf[1, 2],\n rs,\n s_juves;\n opts=Dict(:summarize => false),\n axis_opts=Dict(:title => \"Juveniles [%]\"),\n);\n\ntf # display the figure\nsave(\"aviz_scenario.png\", tf) # save the figure to a file","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Scenarios with subplots)","category":"page"},{"location":"usage/analysis/#Intervention-location-selection-visualisation","page":"Analysis","title":"Intervention location selection - visualisation","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Plot spatial colormaps of site selection frequencies and other available site selection metrics.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Calculate frequencies with which each site was selected at each rank\nrank_freq = ADRIA.decision.ranks_to_frequencies(\n rs.ranks[intervention=1];\n agg_func=x -> dropdims(sum(x; dims=:timesteps); dims=:timesteps),\n)\n\n# Plot 1st rank frequencies as a colormap\nrank_fig = ADRIA.viz.ranks_to_frequencies(rs, rank_freq, 1; fig_opts=Dict(:size=>(1200, 800)))\n\nsave(\"single_rank_plot.png\", rank_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Rank frequency plots for single rank)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Plot 1st, 2nd and 3rd rank frequencies as an overlayed colormap\nrank_fig = ADRIA.viz.ranks_to_frequencies(rs, rank_freq, [1, 2, 3]; fig_opts=Dict(:size=>(1200, 800)))\n\nsave(\"ranks_plot.png\", rank_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Rank frequency plots for multiple ranks)","category":"page"},{"location":"usage/analysis/#PAWN-sensitivity-(heatmap-overview)","page":"Analysis","title":"PAWN sensitivity (heatmap overview)","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The PAWN sensitivity analysis method is a moment-independent approach to Global Sensitivity Analysis. It is described as producing robust results at relatively low sample sizes, and is used to screen factors (i.e., identification of important factors) and rank factors as well (ordering factors by their relative contribution towards a given quantity of interest).","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Sensitivity (of mean scenario outcomes to factors)\nmean_s_tac = vec(mean(s_tac, dims=1))\ntac_Si = ADRIA.sensitivity.pawn(rs, mean_s_tac)\npawn_fig = ADRIA.viz.pawn(\n tac_Si;\n opts,\n fig_opts\n)\nsave(\"pawn_si.png\", pawn_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: PAWN sensitivity plots)","category":"page"},{"location":"usage/analysis/#Temporal-Sensitivity-Analysis","page":"Analysis","title":"Temporal Sensitivity Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Temporal (or Time-varying) Sensitivity Analysis applies sensitivity analysis to model outputs over time. The relative importance of factors and their influence on outputs over time can then be examined through this analysis.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"tsa_s = ADRIA.sensitivity.tsa(rs, s_tac)\ntsa_fig = ADRIA.viz.tsa(\n rs,\n tsa_s;\n opts,\n fig_opts\n)\nsave(\"tsa.png\", tsa_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Temporal Sensitivities)","category":"page"},{"location":"usage/analysis/#Convergence-Analysis","page":"Analysis","title":"Convergence Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"When undertaking sensitivity analysis it is important to have a sufficient number of samples such that the sensitivity measure converges to a stable state. To assess whether sufficient samples have been taken a convergence analysis can be conducted. One approach is to draw a large sample and then iteratively assess stability of the sensitivity metric using an increasing number of sub-samples. The sensitivity metric is described as having \"converged\" if there is little to no fluctuations/variance for a given sample size. The analysis can help determine if too little (or too many) samples have taken for the purpose of sensitivity analysis.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The function sensitivity.convergence can be used to calculate a sensitivity measure for an increasing number of samples. The result can then be plotted as band plots or a heat map using viz.convergence.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"outcome = dropdims(mean(ADRIA.metrics.scenario_total_cover(rs); dims=:timesteps), dims=:timesteps)\n\n# Display convergence for specific factors of interest (\"foi\") within a single figure.\n# Bands represent the 95% confidence interval derived from the number of conditioning\n# points, the default for which is ten (i.e., 10 samples).\n# Due to the limited sample size, care should be taken when interpreting the figure.\nfoi = [:dhw_scenario, :wave_scenario, :guided]\nSi_conv = ADRIA.sensitivity.convergence(scens, outcome, foi)\nconv_series_fig = ADRIA.viz.convergence(Si_conv, foi)\nsave(\"convergence_factors_series.png\", conv_series_fig)\n\n# Convergence analysis of factors grouped by model component as a heat map\ncomponents = [:EnvironmentalLayer, :Intervention, :Coral]\nSi_conv = ADRIA.sensitivity.convergence(rs, scens, outcome, components)\nconv_hm_fig = ADRIA.viz.convergence(Si_conv, components; opts=Dict(:viz_type=>:heatmap))\nsave(\"convergence_components_heatmap.png\", conv_hm_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Convergence analysis of factors overlayed) (Image: Grouped convergence analysis)","category":"page"},{"location":"usage/analysis/#Time-Series-Clustering","page":"Analysis","title":"Time Series Clustering","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"The Time Series Clustering algorithm clusters together series (typically time series) with similar behavior. This is achieved by computing the Euclidian distance between each pair of series weighted by a correlation factor that takes into account the quotient between their complexities. When plotting clustered_scenarios, the kwarg opts can be used with the key :summarize to plot the confidence intervals of each cluster instead of each series individually (default is true).","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Extract metric from scenarios\ns_tac = ADRIA.metrics.scenario_total_cover(rs)\n\n# Cluster scenarios\nn_clusters = 4\nclusters = ADRIA.analysis.cluster_scenarios(s_tac, n_clusters)\n\naxis_opts = Dict(\n :title => \"Time Series Clustering with $n_clusters clusters\",\n :ylabel => \"TAC [m²]\",\n :xlabel => \"Timesteps [years]\",\n)\n\ntsc_fig = ADRIA.viz.clustered_scenarios(\n s_tac, clusters; opts=Dict(:summarize => true), fig_opts=fig_opts, axis_opts=axis_opts\n)\n\n# Save final figure\nsave(\"tsc.png\", tsc_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Time Series Cluster)","category":"page"},{"location":"usage/analysis/#Target-clusters","page":"Analysis","title":"Target clusters","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"One can also target scenarios that belong to specific clusters (like clusters with higher median value for some outcome):","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Extract metric from scenarios\nasv = ADRIA.metrics.absolute_shelter_volume(rs)\n\n# Time series summarizing scenarios for each site\nasv_site_series = ADRIA.metrics.loc_trajectory(median, asv)\n\n# Cluster scenarios\nn_clusters = 6\nasv_clusters = ADRIA.analysis.cluster_scenarios(asv_site_series, n_clusters)\n\n# Target scenarios that belong to the two lowest value clusters\nlowest = x -> x .∈ [sort(x; rev=true)[1:2]]\nasv_target = ADRIA.analysis.find_scenarios(asv_site_series, asv_clusters, lowest)\n\n# Plot targeted scenarios\naxis_opts = Dict(:ylabel => \"Absolute Shelter Volume\", :xlabel => \"Timesteps [years]\")\n\ntsc_asc_fig = ADRIA.viz.clustered_scenarios(\n asv_site_series, asv_target; axis_opts=axis_opts, fig_opts=fig_opts\n)\n\n# Save final figure\nsave(\"tsc_asv.png\", tsc_asc_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of targeted lowest clusters)","category":"page"},{"location":"usage/analysis/#Multiple-Time-Series-Clustering","page":"Analysis","title":"Multiple Time Series Clustering","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"It is possible to perform time series clustering for different metric outcomes and find scenarios that behave the same across all of them. Currently there is no visualization function for this.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"metrics::Vector{ADRIA.metrics.Metric} = [\n ADRIA.metrics.scenario_total_cover,\n ADRIA.metrics.scenario_asv,\n ADRIA.metrics.scenario_absolute_juveniles,\n]\n\noutcomes = ADRIA.metrics.scenario_outcomes(rs, metrics)\nn_clusters = 6\n\n# Clusters matrix\noutcomes_clusters::AbstractMatrix{Int64} = ADRIA.analysis.cluster_scenarios(\n outcomes, n_clusters\n)\n\n# Filter scenarios that belong to on of the 4 high value clusters for all outcomes\nhighest_clusters(x) = x .∈ [sort(x; rev=true)[1:4]]\nrobust_scens = ADRIA.analysis.find_scenarios(outcomes, outcomes_clusters, highest_clusters)","category":"page"},{"location":"usage/analysis/#Time-Series-Clustering-Map","page":"Analysis","title":"Time Series Clustering Map","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"When using Time Series Clustering to cluster among multiple locations using some metric, it is possible to visualize the result as a map.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Extract metric from scenarios\ntac = ADRIA.metrics.total_absolute_cover(rs)\n\n# Get a timeseries summarizing the scenarios for each site\ntac_site_series = ADRIA.metrics.loc_trajectory(median, tac)\n\n# Cluster scenarios\nn_clusters = 6\nclusters = ADRIA.analysis.cluster_scenarios(tac_site_series, n_clusters)\n\n# Get a vector summarizing the scenarios and timesteps for each site\ntac_sites = ADRIA.metrics.per_loc(median, tac)\n\n# Plot figure\ntsc_map_fig = ADRIA.viz.map(rs, tac_sites, clusters)\n\n# Save final figure\nsave(\"tsc_map.png\", tsc_map_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Spatial Time Series Clusters)","category":"page"},{"location":"usage/analysis/#Rule-Induction-(using-Series-Clusters)","page":"Analysis","title":"Rule Induction (using Series Clusters)","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"After clustering, it is possible to target some specific scenarios based on each cluster median outcome temporal variability:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Find Time Series Clusters\ns_tac = ADRIA.metrics.scenario_total_cover(rs)\nn_clusters = 6\nclusters = ADRIA.analysis.cluster_scenarios(s_tac, n_clusters)\n\n# Target scenarios\ntarget_clusters = ADRIA.analysis.target_clusters(clusters, s_tac)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Using this vector if target clusters, together with the parameters used to generate each scenario, it is possible to use a Rule Induction algorithm (SIRUS) and plot each extracted rule as a scatter graph:","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# Select features of interest\nfoi = ADRIA.component_params(rs, [Intervention, SeedCriteriaWeights]).fieldname\n\n# Use SIRUS algorithm to extract rules.\nmax_rules = 10\nrules_iv = ADRIA.analysis.cluster_rules(\n rs, target_clusters, scens, foi, max_rules; remove_duplicates=true\n)\n\n\n# Plot scatters for each rule highlighting the area selected them\nrules_scatter_fig = ADRIA.viz.rules_scatter(\n rs,\n scens,\n target_clusters,\n rules_iv;\n fig_opts=fig_opts,\n opts=opts\n)\n\n# Save final figure\nsave(\"rules_scatter.png\", rules_scatter_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Rule Induction)","category":"page"},{"location":"usage/analysis/#Regional-Sensitivity-Analysis","page":"Analysis","title":"Regional Sensitivity Analysis","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"Regional Sensitivity Analysis is a monte-carlo filtering approach. The aim of RSA is to aid in identifying which (group of) factors drive model outputs and their active areas of factor space.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"mean_s_tac = dropdims(mean(s_tac), dims=1)\n\ntac_rs = ADRIA.sensitivity.rsa(rs, mean_s_tac; S=10)\nrsa_fig = ADRIA.viz.rsa(\n rs,\n tac_rs,\n [:dhw_scenario, :wave_scenario, :N_seed_TA, :N_seed_CA, :fogging, :SRM];\n opts,\n fig_opts\n)\n\nsave(\"rsa.png\", rsa_fig)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Plots of Regional Sensitivities)","category":"page"},{"location":"usage/analysis/#Outcome-mapping","page":"Analysis","title":"Outcome mapping","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"A monte-carlo filtering approach similar to Regional Sensitivity Analysis.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"As the name implies, outcome mapping aids in identifying the relationship between model outputs and the region of factor space that led to those outputs.","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"mean_s_tac = dropdims(mean(s_tac), dims=1)\n\ntf = Figure(size=(1600, 1200)) # size of figure\n\n# Indicate factor values that are in the top 50 percentile\ntac_top_50 = ADRIA.sensitivity.outcome_map(rs, mean_s_tac, x -> any(x .>= 0.5), foi; S=20)\nADRIA.viz.outcome_map!(\n tf[1, 1],\n rs,\n tac_top_50,\n foi;\n axis_opts=Dict(:title => \"Regions which lead to Top 50th Percentile Outcomes\", :ylabel => \"TAC [m²]\")\n)\n\n# Indicate factor values that are in the top 30 percentile\ntac_top_30 = ADRIA.sensitivity.outcome_map(rs, mean_s_tac, x -> any(x .>= 0.7), foi; S=20)\nADRIA.viz.outcome_map!(\n tf[2, 1],\n rs,\n tac_top_30,\n foi;\n axis_opts=Dict(:title => \"Regions which lead to Top 30th Percentile Outcomes\", :ylabel => \"TAC [m²]\"))\n\nsave(\"outcome_map.png\", tf)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Outcome mapping)","category":"page"},{"location":"usage/analysis/#GUI-for-high-level-exploration-(prototype-only!)","page":"Analysis","title":"GUI for high-level exploration (prototype only!)","text":"","category":"section"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"# To explore results interactively\nADRIA.viz.explore(\"path to Result Set\")\n\n# or, if the result set is already loaded:\n# ADRIA.viz.explore(rs)","category":"page"},{"location":"usage/analysis/","page":"Analysis","title":"Analysis","text":"(Image: Standalone app for data exploration)","category":"page"},{"location":"#Introduction","page":"Introduction","title":"Introduction","text":"","category":"section"},{"location":"#What-is-ADRIA.jl?","page":"Introduction","title":"What is ADRIA.jl?","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"ADRIA is a decision support platform for informing reef restoration and adaptation interventions through scenario exploration and analysis, decision heuristics (MCDA), alongside a small coral ecosystem model.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Among the most common usecases are:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Running a number of scenarios under different environmental and intervention conditions (see Loading a Domain, Generating scenarios and Running scenarios);\nExtracting metrics for each scenario and timestep such as coral cover, shelter volume or number of juveniles (see Metrics);\nUsing these metrics to perform a range of analyses like time series clustering (grouping together scenarios with similar temporal behaviour; see Analysis);\nUsing the visualization tools to plot some of the mentioned metrics or analysis (see Analysis);","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"More details about each of these can be found in the next sections.","category":"page"},{"location":"#Docker-documentation","page":"Introduction","title":"Docker documentation","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"ADRIA.jl features a set of Docker build targets which allow usage, development and experimentation of the ADRIA Julia package. See ADRIA Docker Setup for more information.","category":"page"},{"location":"#Troubleshooting-F.A.Q","page":"Introduction","title":"Troubleshooting F.A.Q","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"ADRIA.jl is under active development and from time to time issues may arise. Here are some answers to some issues encountered.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Q. I get this warning when trying to load pre-existing results: Results were produced with a different version of ADRIA (v0.x.x). The installed version of ADRIA is: v0.y.y. Errors may occur when analyzing data. (where x and y are different numbers).","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"A. The result set being loaded were generated by a different version of ADRIA, and in a possibly incompatible format. Sometimes, results may still be produced/analyzed as normal. In other times, ADRIA.jl or the expected metadata in the result set may have changed leading to errors when conducting analyses.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Either go back to the version indicated, or re-run the scenarios to obtain results in the updated format.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Q. I get an error or warning about an ENV variable not being found or set.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"A. Double check the configuration settings in config.toml (see above).","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Q. How do I run my own scenarios?","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"A. Scenarios are defined in a CSV file (with parameter values in columns, so that each row defines a scenario).","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"See the example_scenarios.csv file in the ADRIA data specification repository for an idea of what this looks like.\nSee Extracting model details example in Cookbook examples on how to extract the model specification and parameter table for a given domain.\nSee also the Generating and running scenarios example in Cookbook examples which showcases how to run such a file for a given study area.","category":"page"},{"location":"usage/scenario_discovery/#Scenario-Discovery","page":"Scenario Discovery","title":"Scenario Discovery","text":"","category":"section"},{"location":"usage/scenario_discovery/","page":"Scenario Discovery","title":"Scenario Discovery","text":"using ADRIA\n\ndom = ADRIA.load_domain(\"...\")\nscens = ADRIA.sample(dom, 4096)\n\nrs = ADRIA.run_scenarios(dom, scens, \"45\")\n# rs = ADRIA.load_results(\"...\")\n\n# Calculate representative statistic for all metrics of interest\n# Here, total cover, shelter volume and juvenile population\ntac = ADRIA.metrics.scenario_total_cover(rs)\nmean_tac = vec(mean(tac, dims=1))\n\nrsv = ADRIA.metrics.scenario_rsv(rs)\nmean_sv = vec(mean(rsv, dims=1))\n\nr_juves = ADRIA.metrics.scenario_relative_juveniles(rs)\nmean_juves = vec(mean(r_juves, dims=1))\n\n# Create matrix of all metrics\ny = hcat(mean_tac, mean_sv, mean_juves)\n\n# Define \"robust scenario\" as one where all metric outcomes >= 30th percentile.\nrule_func = x -> all(x .>= 0.3)\n\n# Identify robust scenarios for a specific RCP (4.5)\nrobust = ADRIA.analysis.find_robust(rs, y, rule_func, [45])\n\n# Output robust scenario IDs\n@info robust.RCP45\n\n# Could qualitatively examine inputs that led to robust scenarios ...\nrs.inputs[robust.RCP45, :]\n\n# ... or mark behavioural and non-behavioural outcomes for further analysis\n# e.g., with random forest.\nbehave = zeros(size(y, 1))\nbehave[robust.RCP45] .= 1.0\n\n# Next step is to test these for robustness across environmental conditions ...\n# [TODO]","category":"page"}] } diff --git a/dev/synopsis/index.html b/dev/synopsis/index.html index 6ef599f21..1209f8293 100644 --- a/dev/synopsis/index.html +++ b/dev/synopsis/index.html @@ -1,2 +1,2 @@ -Synopsis · ADRIA.jl
GitHub

Synopsis

Climate change is transforming coral reefs. Continued climate change has scope to erode reef biodiversity, key ecosystem functions, and the ecosystem services they provide for people. Conventional management strategies remain essential but will not be sufficient on their own to sustain coral reefs in a warming and acidifying ocean. New interventions are increasingly being considered, including assisted gene flow, cooling and shading, and reef structures that provide reef habitats and substrates for enhanced recruitment.

Deciding where, when, and how to intervene – if at all - using new reef restoration and adaptation measures is challenging on at least three fronts.

  1. are new interventions likely to create more benefits than damage? And if so, whom do they benefit, or pose risks to, and at what spatial and temporal scales?
  2. which interventions, individually and in combination, represent solutions that provide the highest return on investment for reef, people, and industries?
  3. which R&D paths and deployment strategies represent optimal solutions given multiple key objectives, trade-offs, and limited time, resources, and logistical constraints?

To help reef modellers, decision-support teams and reef managers address these questions, AIMS has developed the Adaptive, Dynamic Reef Intervention Algorithm (ADRIA). In short, ADRIA simulates a reef decision maker operating inside the dynamic state space of a coral reef.

For reef managers, ADRIA help provide line of sight to conservation solutions in complex settings where multiple objectives need to be considered. For investors, ADRIA helps analysts identify which options (R&D and/or deployment solutions) might have the highest likelihood of providing ecological and social returns on investment across a range of considered environmental conditions. While ADRIA’s key function is as a decision-support tool for intervention deployment, it uses a simple proxy model for reef coral dynamics, consisting of vital rates parameterised in a set of linked differential equations for four coral groups. The growth, mortality and recruitment of those four coral groups are further parameterised by environmental drivers and by different restoration and adaptation interventions.

The primary purpose of ADRIA is to help guide intervention deployment such that net benefits are maximised against primary objectives and minimised against costs. Solutions can be tuned (eventually optimised) via heuristics that control the selection of sites and/or reefs and the prioritisation of species, ecosystem services or benefits that favour what people (society) want. The key benefits considered in ADRIA are consistent with a triple-bottom-line approach, i.e.

  1. ecological (e.g. biodiversity),
  2. economic (e.g. tourism and fisheries values) and
  3. social and cultural (e.g. recreation and supporting identities).

The guiding principles for decision support in ADRIA are currently a set of dynamic Multi-Criteria Decision Analyses (dMCDA) applied at each time step. Criteria in the model are a composite of spatial environmental variables (risk from wave damage, thermal stress, and water quality) and ecological information (coral cover, substrate availability).

+Synopsis · ADRIA.jl
GitHub

Synopsis

Climate change is transforming coral reefs. Continued climate change has scope to erode reef biodiversity, key ecosystem functions, and the ecosystem services they provide for people. Conventional management strategies remain essential but will not be sufficient on their own to sustain coral reefs in a warming and acidifying ocean. New interventions are increasingly being considered, including assisted gene flow, cooling and shading, and reef structures that provide reef habitats and substrates for enhanced recruitment.

Deciding where, when, and how to intervene – if at all - using new reef restoration and adaptation measures is challenging on at least three fronts.

  1. are new interventions likely to create more benefits than damage? And if so, whom do they benefit, or pose risks to, and at what spatial and temporal scales?
  2. which interventions, individually and in combination, represent solutions that provide the highest return on investment for reef, people, and industries?
  3. which R&D paths and deployment strategies represent optimal solutions given multiple key objectives, trade-offs, and limited time, resources, and logistical constraints?

To help reef modellers, decision-support teams and reef managers address these questions, AIMS has developed the Adaptive, Dynamic Reef Intervention Algorithm (ADRIA). In short, ADRIA simulates a reef decision maker operating inside the dynamic state space of a coral reef.

For reef managers, ADRIA help provide line of sight to conservation solutions in complex settings where multiple objectives need to be considered. For investors, ADRIA helps analysts identify which options (R&D and/or deployment solutions) might have the highest likelihood of providing ecological and social returns on investment across a range of considered environmental conditions. While ADRIA’s key function is as a decision-support tool for intervention deployment, it uses a simple proxy model for reef coral dynamics, consisting of vital rates parameterised in a set of linked differential equations for four coral groups. The growth, mortality and recruitment of those four coral groups are further parameterised by environmental drivers and by different restoration and adaptation interventions.

The primary purpose of ADRIA is to help guide intervention deployment such that net benefits are maximised against primary objectives and minimised against costs. Solutions can be tuned (eventually optimised) via heuristics that control the selection of sites and/or reefs and the prioritisation of species, ecosystem services or benefits that favour what people (society) want. The key benefits considered in ADRIA are consistent with a triple-bottom-line approach, i.e.

  1. ecological (e.g. biodiversity),
  2. economic (e.g. tourism and fisheries values) and
  3. social and cultural (e.g. recreation and supporting identities).

The guiding principles for decision support in ADRIA are currently a set of dynamic Multi-Criteria Decision Analyses (dMCDA) applied at each time step. Criteria in the model are a composite of spatial environmental variables (risk from wave damage, thermal stress, and water quality) and ecological information (coral cover, substrate availability).

diff --git a/dev/usage/analysis/index.html b/dev/usage/analysis/index.html index d7ac3b406..b2a72e989 100644 --- a/dev/usage/analysis/index.html +++ b/dev/usage/analysis/index.html @@ -173,22 +173,24 @@ # Save final figure save("tsc_map.png", tsc_map_fig)

Plots of Spatial Time Series Clusters

Rule Induction (using Series Clusters)

After clustering, it is possible to target some specific scenarios based on each cluster median outcome temporal variability:

# Find Time Series Clusters
 s_tac = ADRIA.metrics.scenario_total_cover(rs)
-num_clusters = 6
-clusters = ADRIA.analysis.cluster_scenarios(s_tac, num_clusters)
+n_clusters = 6
+clusters = ADRIA.analysis.cluster_scenarios(s_tac, n_clusters)
 
 # Target scenarios
-target_clusters = ADRIA.analysis.target_clusters(clusters, s_tac)

Using this vector if target clusters, together with the parameters used to generate each scenario, it is possible to use a Rule Induction algorithm (SIRUS) and plot each extracted rule as a scatter graph:

# Select only desired features
-fields_iv = ADRIA.component_params(rs, [Intervention, CriteriaWeights]).fieldname
-scenarios_iv = scens[:, fields_iv]
+target_clusters = ADRIA.analysis.target_clusters(clusters, s_tac)

Using this vector if target clusters, together with the parameters used to generate each scenario, it is possible to use a Rule Induction algorithm (SIRUS) and plot each extracted rule as a scatter graph:

# Select features of interest
+foi = ADRIA.component_params(rs, [Intervention, SeedCriteriaWeights]).fieldname
 
-# Use SIRUS algorithm to extract rules
+# Use SIRUS algorithm to extract rules.
 max_rules = 10
-rules_iv = ADRIA.analysis.cluster_rules(target_clusters, scenarios_iv, max_rules)
+rules_iv = ADRIA.analysis.cluster_rules(
+    rs, target_clusters, scens, foi, max_rules; remove_duplicates=true
+)
+
 
 # Plot scatters for each rule highlighting the area selected them
 rules_scatter_fig = ADRIA.viz.rules_scatter(
     rs,
-    scenarios_iv,
+    scens,
     target_clusters,
     rules_iv;
     fig_opts=fig_opts,
@@ -234,4 +236,4 @@
 ADRIA.viz.explore("path to Result Set")
 
 # or, if the result set is already loaded:
-# ADRIA.viz.explore(rs)

Standalone app for data exploration

+# ADRIA.viz.explore(rs)

Standalone app for data exploration

diff --git a/dev/usage/cookbook/index.html b/dev/usage/cookbook/index.html index 8af5a5b47..505484fbe 100644 --- a/dev/usage/cookbook/index.html +++ b/dev/usage/cookbook/index.html @@ -181,4 +181,4 @@ sel_score = selection_score(rs.ranks[intervention=1]) # Get selection score for locations over time -sel_score = selection_score(rs.ranks[intervention=1]; dims=[:scenarios]) +sel_score = selection_score(rs.ranks[intervention=1]; dims=[:scenarios]) diff --git a/dev/usage/domain/index.html b/dev/usage/domain/index.html index 09f4068ac..1085656a0 100644 --- a/dev/usage/domain/index.html +++ b/dev/usage/domain/index.html @@ -1,2 +1,2 @@ -Loading a Domain · ADRIA.jl
GitHub

Loading a Domain

ADRIA is designed to work with Domain data packages.

At their core, data packages are a directory containing a datapackage.json file, following the spec as outlined by Frictionless Data. In short, these are pre-packaged data sets that hold all the necessary data to run simulations for a given spatial domain.

See Architectural overview for more information.

A Domain may be loaded by calling the load_domain function with the path to the data package. Note that the data package is the directory.

By convention we assign the Domain to dom, although this variable can be named anything.

dom = ADRIA.load_domain("path to domain data package")

ReefMod Engine datasets can also be used to run ADRIAmod simulations for the Great Barrier Reef.

dom = ADRIA.load_domain(RMEDomain, "path to ReefModEngine dataset", "45")

Note that at the moment the target RCP has to be specified.

ReefMod Matlab datasets that have been converted to NetCDF files can also be used to run ADRIAmod simulation for the Great Barrier Reef.

dom = ADRIA.load_domain(ReefModDomain, "path to ReefMod dataset", "45")

The target RCP must also be specified.

+Loading a Domain · ADRIA.jl
GitHub

Loading a Domain

ADRIA is designed to work with Domain data packages.

At their core, data packages are a directory containing a datapackage.json file, following the spec as outlined by Frictionless Data. In short, these are pre-packaged data sets that hold all the necessary data to run simulations for a given spatial domain.

See Architectural overview for more information.

A Domain may be loaded by calling the load_domain function with the path to the data package. Note that the data package is the directory.

By convention we assign the Domain to dom, although this variable can be named anything.

dom = ADRIA.load_domain("path to domain data package")

ReefMod Engine datasets can also be used to run ADRIAmod simulations for the Great Barrier Reef.

dom = ADRIA.load_domain(RMEDomain, "path to ReefModEngine dataset", "45")

Note that at the moment the target RCP has to be specified.

ReefMod Matlab datasets that have been converted to NetCDF files can also be used to run ADRIAmod simulation for the Great Barrier Reef.

dom = ADRIA.load_domain(ReefModDomain, "path to ReefMod dataset", "45")

The target RCP must also be specified.

diff --git a/dev/usage/getting_started/index.html b/dev/usage/getting_started/index.html index f30129df3..d044f6afc 100644 --- a/dev/usage/getting_started/index.html +++ b/dev/usage/getting_started/index.html @@ -18,4 +18,4 @@ # Plot a quick scenario overview fig = ADRIA.viz.scenarios(rs, s_tc; axis_opts=Dict(:ylabel=>"Absolute Cover")) -save("path_to_save_figure", fig)

See Analysis for further examples of analysis and plots.

+save("path_to_save_figure", fig)

See Analysis for further examples of analysis and plots.

diff --git a/dev/usage/results/index.html b/dev/usage/results/index.html index 98bfdeabb..d850008a1 100644 --- a/dev/usage/results/index.html +++ b/dev/usage/results/index.html @@ -17,4 +17,4 @@ │ └───results results.nc - scenarios.csv

In order to reduce the duplication of geospatial and conectivity data, the data directory and results directory can be supplied seperately to avoid having copies for each resuilt set analysed.

rs = ADRIA.load_domain(RMEResultSet, "<path to data dir>", "<path to results dir>")
+ scenarios.csv

In order to reduce the duplication of geospatial and conectivity data, the data directory and results directory can be supplied seperately to avoid having copies for each resuilt set analysed.

rs = ADRIA.load_domain(RMEResultSet, "<path to data dir>", "<path to results dir>")
diff --git a/dev/usage/scenario_discovery/index.html b/dev/usage/scenario_discovery/index.html index bf96d64da..3d5c61332 100644 --- a/dev/usage/scenario_discovery/index.html +++ b/dev/usage/scenario_discovery/index.html @@ -39,4 +39,4 @@ behave[robust.RCP45] .= 1.0 # Next step is to test these for robustness across environmental conditions ... -# [TODO] +# [TODO] diff --git a/dev/usage/scenario_generation/index.html b/dev/usage/scenario_generation/index.html index 610a86775..b3a837d2c 100644 --- a/dev/usage/scenario_generation/index.html +++ b/dev/usage/scenario_generation/index.html @@ -51,4 +51,4 @@ dom = ADRIA.set_factor_bounds(dom; heat_stress=(0.3, 0.7), N_seed_TA=(500000.0, 1000000.0), - N_seed_CA=(500000.0, 1000000.0))

Sampling counterfactuals only

A convenience function to create scenarios with no interventions (counterfactuals).

cf_scens = ADRIA.sample_cf(dom, 1024)

References

  1. Sobol’, I. M. 1993. Sensitivity analysis for non-linear mathematical models. Mathematical Modelling and Computational Experiment 1:407–414. [Translated from Russian, accessible at: https://www.mathnet.ru/php/archive.phtml?wshow=paper&jrnid=mm&paperid=2320&option_lang=eng]
  2. Sobol′, I. M. 2001. Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation 55:271–280. https://doi.org/10.1016/S0378-4754(00)00270-6
  3. Pianosi, F., and T. Wagener. 2015. A simple and efficient method for global sensitivity analysis based on cumulative distribution functions. Environmental Modelling & Software 67:1–11. https://dx.doi.org/10.1016/j.envsoft.2015.01.004
  4. Pianosi, F., and T. Wagener. 2018. Distribution-based sensitivity analysis from a generic input-output sample. Environmental Modelling & Software 108:197–207. https://dx.doi.org/10.1016/j.envsoft.2018.07.019
+ N_seed_CA=(500000.0, 1000000.0))

Sampling counterfactuals only

A convenience function to create scenarios with no interventions (counterfactuals).

cf_scens = ADRIA.sample_cf(dom, 1024)

References

  1. Sobol’, I. M. 1993. Sensitivity analysis for non-linear mathematical models. Mathematical Modelling and Computational Experiment 1:407–414. [Translated from Russian, accessible at: https://www.mathnet.ru/php/archive.phtml?wshow=paper&jrnid=mm&paperid=2320&option_lang=eng]
  2. Sobol′, I. M. 2001. Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation 55:271–280. https://doi.org/10.1016/S0378-4754(00)00270-6
  3. Pianosi, F., and T. Wagener. 2015. A simple and efficient method for global sensitivity analysis based on cumulative distribution functions. Environmental Modelling & Software 67:1–11. https://dx.doi.org/10.1016/j.envsoft.2015.01.004
  4. Pianosi, F., and T. Wagener. 2018. Distribution-based sensitivity analysis from a generic input-output sample. Environmental Modelling & Software 108:197–207. https://dx.doi.org/10.1016/j.envsoft.2018.07.019
diff --git a/dev/usage/scenario_runs/index.html b/dev/usage/scenario_runs/index.html index 50eea5911..d4e778463 100644 --- a/dev/usage/scenario_runs/index.html +++ b/dev/usage/scenario_runs/index.html @@ -10,4 +10,4 @@ # "Example_domain__RCPs45__2022-10-19_12_01_26_965" @info ADRIA.result_location(rs) -# "[some location]/Example_domain__RCPs45__2022-10-19_12_01_26_965"

The rs variable is an ResultSet object which acts as an interface to the stored results.

The ResultSet provides:

  • An overview of scenarios run
  • Access to results from key ADRIA metrics
  • Seeding/Shading/Fogging logs
  • domain spatial data
print(rs)
on-disk data store

ADRIA uses an on-disk data store (in Zarr format) to reduce memory use. The primary location for these is defined in the project's config.toml file (see instructions in Getting Started).

Reloading results

Pre-existing results can also be reloaded by providing the path to the data store.

rs = ADRIA.load_results("path to result set")
+# "[some location]/Example_domain__RCPs45__2022-10-19_12_01_26_965"

The rs variable is an ResultSet object which acts as an interface to the stored results.

The ResultSet provides:

  • An overview of scenarios run
  • Access to results from key ADRIA metrics
  • Seeding/Shading/Fogging logs
  • domain spatial data
print(rs)
on-disk data store

ADRIA uses an on-disk data store (in Zarr format) to reduce memory use. The primary location for these is defined in the project's config.toml file (see instructions in Getting Started).

Reloading results

Pre-existing results can also be reloaded by providing the path to the data store.

rs = ADRIA.load_results("path to result set")