-
Notifications
You must be signed in to change notification settings - Fork 6
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
MCDA documentation #289
base: main
Are you sure you want to change the base?
MCDA documentation #289
Conversation
Happy to adjust if there is too much mathematical detail for the MCDA aggregation method algorithms. |
Can also add references if necessary |
docs/src/dMCDA.md
Outdated
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)```. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a reason why triple backticks are needed here?
docs/src/dMCDA.md
Outdated
* 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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sould I add comments on all of these indicating expected values then?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ALternatively I could add expected ranges to the parameter description table.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
docs/src/dMCDA.md
Outdated
|
||
## 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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
docs/src/dMCDA.md
Outdated
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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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"
docs/src/dMCDA.md
Outdated
* 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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".
docs/src/dMCDA.md
Outdated
# 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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor comment: we import ADRIA anyway, so you could save a line and call ADRIA.run_site_selection
instead
docs/src/dMCDA.md
Outdated
using ADRIA | ||
using ADRIA: run_site_selection | ||
using DataFrames |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is DataFrames
needed here
docs/src/dMCDA.md
Outdated
3. VIKOR : ```guided = 3``` | ||
|
||
The ```guided``` parameter can be set in the input parameter DataFrame or inline, as in the example below. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use consistent terminology
"input parameter DataFrame" -> "criteria DataFrame"
What does "inline" mean here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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"
docs/src/dMCDA.md
Outdated
$$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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"I.e." -> "i.e."
docs/src/dMCDA.md
Outdated
|
||
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Replace unicode characters with plain text please
docs/src/dMCDA.md
Outdated
|
||
## 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, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would prefer the detail in docstrings as these can be viewed from the REPL / inside notebooks.
scens.guided[3] = 1.0 # order ranking | ||
scens.guided[4] = 2.0 # TOPSIS | ||
scens.guided[5] = 3.0 # VIKOR |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
- add description of MCDA methods and site selection in ADRIA - Add table describing MCDA weight meanings.
8a8683b
to
308843b
Compare
…c domain to examples
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.