MCDA documentation #289

Rosejoycrocker · 2023-02-08T03:45:17Z

Adds MCDA documentation including setting weightings examples, explanation of aggregation methods, how to set algorithm example and example using site selection separately from the ecological model.

Rosejoycrocker · 2023-02-08T03:46:22Z

Happy to adjust if there is too much mathematical detail for the MCDA aggregation method algorithms.

Rosejoycrocker · 2023-02-08T03:47:09Z

Can also add references if necessary

ConnectedSystems · 2023-02-10T05:28:52Z

docs/src/dMCDA.md

+At each time step where an intervention is performed at a site, the sites for intervention can be selected either randomly or by using a site selection algorithm. When an algorithm is used, site selection is performed by iteratively updating how each site/reef in the domain performs against a range of criteria. Currently, ADRIA allows the following criteria to be used in site selection:
+
+* Connectivity, calculated as ```centrality*(site coral cover)*(site area)```.


Is there a reason why triple backticks are needed here?

ConnectedSystems · 2023-02-10T05:31:46Z

docs/src/dMCDA.md

+* Wave damage probability.
+* Heat stress probability.
+* Priority predecessors, or sites with the strongest connectivity to "priority sites" (defined by the user in the ```prioritysites``` parameter).


defined by the user in the prioritysites parameter

Update variable name to snake_case

I would also prefer "defined with the priority_sites parameter" to avoid repeating "by the user"

The note here and the comment in the corresponding location in the code (~L36 in const_params.jl) should also indicate what the expected values are:

e.g., a vector of index locations? site ids?

Sould I add comments on all of these indicating expected values then?

The idea is that there should be enough information for someone to be able to use/understand it. Trawling through the code should be a last resort.

Is it documented anywhere else? If so, refer to it.
If not, then here seems like a good place to do so.

ALternatively I could add expected ranges to the parameter description table.

How about we sidestep this by using Literate.jl and auto-generate the table using the model spec (which now has names and descriptions)?

We'd need to rejig these markdown files to be inside .jl files but may be worth the effort.

Otherwise you'll be spending time updating the table to keep the documentation up to date

ConnectedSystems · 2023-02-10T05:37:00Z

docs/src/dMCDA.md

+
+## Site Selection in ADRIA
+At each time step where an intervention is performed at a site, the sites for intervention can be selected either randomly or by using a site selection algorithm. When an algorithm is used, site selection is performed by iteratively updating how each site/reef in the domain performs against a range of criteria. Currently, ADRIA allows the following criteria to be used in site selection:


Mention MCDA, and the methods that are applied, to select sites in this paragraph.

Currently each paragraph is all on one line. Please format so its well-formatted without word-wrapping turned on.

ConnectedSystems · 2023-02-10T05:52:29Z

docs/src/dMCDA.md

+In the case of site selection for seeding, the coral cover criterium is defined as the area not occupied by coral relative to the site carrying capacity. For shading, the coral cover criterium is defined as the area already covered with coral relative to the carrying capacity. All other criteria are identical for seeding and shading, so that sites selected for these two interventions tend to be similar. The priority predecessors and priority zones criteria allow the user to incorporate spatial objectives, such as through GBRMPA management zone layers or data layers from other spatial management software such as MARXAN.
+
+These criteria are used within methods based on multi-criteria decision analysis (MCDA) to rank sites from most to least suitable for intervention at each intervention time step when ADRIA is run. The criteria are weighted according to the user's preference and the weights can be defined in ADRIA through the input scenario parameters, or inline, as in the following example:


These criteria are used within methods based on multi-criteria decision analysis (MCDA) to rank sites

Too late in the document to introduce MCDA (which is why I ask for it to be introduced in the first paragraph).

Can also simplify: "These criteria are used to rank sites"

ConnectedSystems · 2023-02-10T05:56:05Z

docs/src/dMCDA.md

+* Site depth, for which median site depth is used.
+
+In the case of site selection for seeding, the coral cover criterium is defined as the area not occupied by coral relative to the site carrying capacity. For shading, the coral cover criterium is defined as the area already covered with coral relative to the carrying capacity. All other criteria are identical for seeding and shading, so that sites selected for these two interventions tend to be similar. The priority predecessors and priority zones criteria allow the user to incorporate spatial objectives, such as through GBRMPA management zone layers or data layers from other spatial management software such as MARXAN.


All other criteria are identical for seeding and shading, so that sites selected for these two interventions tend to be similar.

I'm not sure if this is clear.

Identical values?
Similar how?

Raises some questions too: Is this similarity desirable? If so, why? If this is due to an assumption, then it should be documented.

for seeding, the coral cover criterium is defined as the area not occupied by coral relative to the site carrying capacity
...
For shading, the coral cover criterium is defined as the area already covered with coral relative to the carrying capacity.

Reduce verbosity

"for seeding, the available space is used as the coral cover criterium."
"The inverse is used for shading".

ConnectedSystems · 2023-02-10T06:35:34Z

docs/src/dMCDA.md

+# initial coral cover matching number of criteria samples (size = (no. criteria scens, no. of sites))
+sum_cover = fill(0.1, nrow(criteria_df), nrow(dom.site_data))
+ranks = run_site_selection(dom, criteria_df[criteria_df.guided.>0, :], sum_cover[criteria_df.guided.>0, :], area_to_seed, ts)


Minor comment: we import ADRIA anyway, so you could save a line and call ADRIA.run_site_selection instead

ConnectedSystems · 2023-02-10T06:36:09Z

docs/src/dMCDA.md

+using ADRIA
+using ADRIA: run_site_selection
+using DataFrames


Is DataFrames needed here

ConnectedSystems · 2023-02-10T06:39:21Z

docs/src/dMCDA.md

+3. VIKOR : ```guided = 3```
+
+The ```guided``` parameter can be set in the input parameter DataFrame or inline, as in the example below.


Use consistent terminology

"input parameter DataFrame" -> "criteria DataFrame"

What does "inline" mean here?

The guided parameter can be set

I would explain that the "criteria DataFrame" is just that - a DataFrame - and any modifications can be done in the usual manner. Followed by something like "To give an example, in the below we adjust the guided parameter which controls which MCDA methods are applied"

ConnectedSystems · 2023-02-10T06:43:34Z

docs/src/dMCDA.md

+$$S_i = \sum_{j=1}^M \frac{PIS_j-X_{i,j}}{PIS_j-NIS_j}$$
+
+I.e. this is the general performance of an alternative when considering all criteria, with possible trade-offs. The Chebyshev distance, $R$, is the maximum distance between the PIS and the value of a criteria for each alternative, giving a measure of the maximum deviance from the best solution for that alternative. 


"I.e." -> "i.e."

ConnectedSystems · 2023-02-10T06:44:56Z

docs/src/dMCDA.md

+
+
+TOPSIS, or Technique for Order of Preference by Similarity to Ideal Solution, ranks alternatives by comparing them to the ‘Positive Ideal Solution’ ($PIS$) and ‘Negative Ideal Solution’ ($NIS$). The $PIS$ is the value of the highest valued alternative for a criterium we want to maximise (or lowest if we want to minimise). The $NIS$ is the value of the lowest valued alternative for a criterium we want to maximise (or highest if we want to minimise). TOPSIS ranks alternatives according to a ratio calculated from the geometric distance of the alternative to the $PIS$ and $NIS$ in each of the criteria. 


Replace unicode characters with plain text please

ConnectedSystems · 2023-02-11T02:42:01Z

docs/src/dMCDA.md

+
+## Aggregation methods
+The simplest method available in ADRIA is referred to as ‘order ranking’, which simply sums the criteria values for each alternative. This additive score can then be ordered from highest to lowest, giving an order of preference for the alternatives considered in the decision. In this case, the rank $r_i$ of site $i$ is,


Are you duplicating detail when describing the different MCDA methods? It may be cleaner to instead cross-reference the function docstrings, and move the detail here to those docstrings (if needed).

Alternatively, I could reduce the docstrings. The mathematical detail here is better explained I think - when I wrote the doc-strings I had intended to later replace them with a better written explaination...

I would prefer the detail in docstrings as these can be viewed from the REPL / inside notebooks.

ConnectedSystems · 2023-02-12T03:43:42Z

docs/src/dMCDA.md

+scens.guided[3] = 1.0 # order ranking
+scens.guided[4] = 2.0 # TOPSIS
+scens.guided[5] = 3.0 # VIKOR


There is a "usage" sub-section in the docs - I suggest we move examples of use there.

- add description of MCDA methods and site selection in ADRIA - Add table describing MCDA weight meanings.

…c domain to examples

Rosejoycrocker requested a review from ConnectedSystems February 8, 2023 03:45

ConnectedSystems requested changes Feb 10, 2023

View reviewed changes

ConnectedSystems reviewed Feb 11, 2023

View reviewed changes

ConnectedSystems reviewed Feb 12, 2023

View reviewed changes

Rosejoycrocker added 12 commits February 13, 2023 07:02

Starting to populate MCDA documentation

a3b9a7c

- add description of MCDA methods and site selection in ADRIA - Add table describing MCDA weight meanings.

Add example for changing guided parameter.

bc97a1f

Add use of site_selection function example to docs

990491b

Corrections to md formatting and editing

82ffa2f

Starting to populate MCDA documentation

7ab75c4

- add description of MCDA methods and site selection in ADRIA - Add table describing MCDA weight meanings.

Add example for changing guided parameter.

0682db1

Add use of site_selection function example to docs

1f2b5b6

Corrections to md formatting and editing

fa8ede4

Mathematical details for aggregation methods added to docs.

727a8c6

Edits + adding distance sorting notes.

2f9d3fc

Corrections to mathematical formulation syntax.

c7ff597

Move first section for better flow.

308843b

Rosejoycrocker force-pushed the MCDA-docs branch from 8a8683b to 308843b Compare February 12, 2023 22:52

Add newlines manually, merge parameter description tables, add generi…

0e8bc1a

…c domain to examples

Zapiano assigned Rosejoycrocker Nov 9, 2023

Zapiano added the documentation Improvements or additions to documentation label Nov 9, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MCDA documentation #289

MCDA documentation #289

Rosejoycrocker commented Feb 8, 2023

Rosejoycrocker commented Feb 8, 2023

Rosejoycrocker commented Feb 8, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

Rosejoycrocker Feb 12, 2023

ConnectedSystems Feb 12, 2023

Rosejoycrocker Feb 12, 2023

ConnectedSystems Feb 13, 2023 •

edited

Loading

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023 •

edited

Loading

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 10, 2023

ConnectedSystems Feb 11, 2023

Rosejoycrocker Feb 12, 2023

ConnectedSystems Feb 13, 2023

ConnectedSystems Feb 12, 2023

		At each time step where an intervention is performed at a site, the sites for intervention can be selected either randomly or by using a site selection algorithm. When an algorithm is used, site selection is performed by iteratively updating how each site/reef in the domain performs against a range of criteria. Currently, ADRIA allows the following criteria to be used in site selection:

		* Connectivity, calculated as ```centrality(site coral cover)(site area)```.


		## Site Selection in ADRIA
		At each time step where an intervention is performed at a site, the sites for intervention can be selected either randomly or by using a site selection algorithm. When an algorithm is used, site selection is performed by iteratively updating how each site/reef in the domain performs against a range of criteria. Currently, ADRIA allows the following criteria to be used in site selection:

		In the case of site selection for seeding, the coral cover criterium is defined as the area not occupied by coral relative to the site carrying capacity. For shading, the coral cover criterium is defined as the area already covered with coral relative to the carrying capacity. All other criteria are identical for seeding and shading, so that sites selected for these two interventions tend to be similar. The priority predecessors and priority zones criteria allow the user to incorporate spatial objectives, such as through GBRMPA management zone layers or data layers from other spatial management software such as MARXAN.

		These criteria are used within methods based on multi-criteria decision analysis (MCDA) to rank sites from most to least suitable for intervention at each intervention time step when ADRIA is run. The criteria are weighted according to the user's preference and the weights can be defined in ADRIA through the input scenario parameters, or inline, as in the following example:

		* Site depth, for which median site depth is used.

		In the case of site selection for seeding, the coral cover criterium is defined as the area not occupied by coral relative to the site carrying capacity. For shading, the coral cover criterium is defined as the area already covered with coral relative to the carrying capacity. All other criteria are identical for seeding and shading, so that sites selected for these two interventions tend to be similar. The priority predecessors and priority zones criteria allow the user to incorporate spatial objectives, such as through GBRMPA management zone layers or data layers from other spatial management software such as MARXAN.

		3. VIKOR : ```guided = 3```

		The ```guided``` parameter can be set in the input parameter DataFrame or inline, as in the example below.

		$$S_i = \sum_{j=1}^M \frac{PIS_j-X_{i,j}}{PIS_j-NIS_j}$$

		I.e. this is the general performance of an alternative when considering all criteria, with possible trade-offs. The Chebyshev distance, $R$, is the maximum distance between the PIS and the value of a criteria for each alternative, giving a measure of the maximum deviance from the best solution for that alternative.



		TOPSIS, or Technique for Order of Preference by Similarity to Ideal Solution, ranks alternatives by comparing them to the ‘Positive Ideal Solution’ ($PIS$) and ‘Negative Ideal Solution’ ($NIS$). The $PIS$ is the value of the highest valued alternative for a criterium we want to maximise (or lowest if we want to minimise). The $NIS$ is the value of the lowest valued alternative for a criterium we want to maximise (or highest if we want to minimise). TOPSIS ranks alternatives according to a ratio calculated from the geometric distance of the alternative to the $PIS$ and $NIS$ in each of the criteria.


		## Aggregation methods
		The simplest method available in ADRIA is referred to as ‘order ranking’, which simply sums the criteria values for each alternative. This additive score can then be ordered from highest to lowest, giving an order of preference for the alternatives considered in the decision. In this case, the rank $r_i$ of site $i$ is,

MCDA documentation #289

Are you sure you want to change the base?

MCDA documentation #289

Conversation

Rosejoycrocker commented Feb 8, 2023

Rosejoycrocker commented Feb 8, 2023

Rosejoycrocker commented Feb 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ConnectedSystems Feb 13, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ConnectedSystems Feb 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ConnectedSystems Feb 13, 2023 •

edited

Loading

ConnectedSystems Feb 10, 2023 •

edited

Loading