-
Notifications
You must be signed in to change notification settings - Fork 6
/
calculations_advanced_workflow.Rmd
169 lines (104 loc) · 8.19 KB
/
calculations_advanced_workflow.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
# Calculations: advanced workflow {#calcs-advanced}
<!--- For reference:
- http://ohi-science.org/manual/#removing-goals-and-sub-goals
- Manual md (easier to search): https://github.com/OHI-Science/ohimanual/blob/gh-pages/3_conduct_manual/ohi-manual.md
--->
**In development.**
The purpose of Chapter \@ref(calcs-advanced) is to build off the basic workflow for calculating OHI scores and do a few more advanced things. This is a a 2-hour hands-on training: you will be following along on your own computer and working with a copy of the demonstration repository that is used throughout the this chapter.
## Overview
This chapter will show you how to add and remove goals from your assessment. You will be able to use these same principles to turn a subgoal into a goal, or rename goals altogether. The toolbox will calculate goal scores for each goal listed in `conf/goals.csv`, so investigating and modifying this file will be a big focus of this chapter.
As in Chapter \@ref(calcs-advanced), it is good practice to rerun `calculate_scores.Rmd` after modifying these files and and use Git tab in RStudio to check your work.
<!---TODO: add commits, sync to this. we'll also be reverting a lot as we test things. --->
### Prerequisites
Before the training, please make sure you have done the following:
1. Have up-to-date versions of `R` and RStudio and have RStudio configured with Git/GitHub <!--- TODO (Chapter \@ref(datascience))--->
- https://cloud.r-project.org
- http://www.rstudio.com/download
- http://happygitwithr.com/rstudio-git-github.html
1. Fork the **toolbox-demo** repository into your own GitHub account by going to https://github.com/OHI-Science/toolbox-demo, clicking "Fork" in the upper right corner, and selecting your account
1. Clone the **toolbox-demo** repo from your GitHub account into RStudio into a folder called "github" in your home directory (filepath "~/github")
1. Get comfortable: be set up with two screens if possible. You will be following along in RStudio on your own computer while also watching an instructor's screen or following this tutorial.
Additionally, this chapter assumes you are familiar with content from Chapter \@ref(calcs-basic), so review that first if needed.
----
## Explore goals.csv
`goals.csv` is the registry for the goals that will be included in OHI calculations. `ohicore` will use this list and make sure there are functions with the same names in `functions.R`. This is one of the things that the Toolbox does with the `Conf()` command, as we will see.
`goals.csv` is inside the `conf` folder. It is a .csv file has a lot of columns, so it is easier to open and inspect it in Excel or other spreadsheet software. Let's discuss a few of the columns here (see Chapter \@ref(toolbox-ecosystem) for descriptions of all of them):
`goals.csv` has information for how goal scores are calculated, and how information will be visualized and communicated. Let's focus on this now:
- Each goal or subgoal has its own row. the "goal" column lists them all
- If the "goal" column is really a subgoal, then the "parent" column lists the parent or supragoal of that sub-goal
<!---
This is where it happens:
```{r Conf, eval=FALSE}
conf = ohicore::Conf('conf')
```
TODO ohicore: Conf() should check that all entries in goals.csv are present in functions.r, but it doesn't.
--->
## Round 1: Poke at it to see how it works
The Toolbox won't always give errors when you start changing things (although we are improving that), so let's just see what some of these things look like. This is when using the Git tab to help you keep track of how things work REALLY helps.
We will make modifications in `goals.csv` and see how that affects the basic calculations workflow from Chapter \@ref(calcs-advanced), and then we will do the same with `functions.R`.
### Remove a goal (whole row) in goals.csv
For example, delete the entire "LSP" row in the .csv file, and save it. You should see the `goals.csv` show up in your Git tab in RStudio because the file has been modified.
Now, recalculate scores from `calculate_scores.Rmd` (remember to run Configure Toolbox first to rerun the `Conf()` function!)
What changed?
As we see from the Git tab, removing this goal affected scores for three things: "Index" and "SP" scores changed, and "LSP" scores were completely deleted.
<!---TODO: for both a goal and subgoal --->
## Round 2: Break it to see how it works
### Change `preindex_function` goals.csv
it's the preindex_function column that is critical for the functions.
Let's add a typo there.
```{r, eval=FALSE}
# Calculating Status and Trend for each region for HAB...
# Error in eval(expr, envir, enclos) : could not find function "HA"
```
### Add a new goal in goals.csv
Just copy-paste.
What do you think will happen? what's the most important column? That's right, `preindex_function`.
This will fail at the scores calculation.
```{r, eval=FALSE}
scores = ohicore::CalculateAll(conf, layers)
# Running Setup()...
# Calculating Status and Trend for each region for FIS...
# ...
# ...
# Calculating Status and Trend for each region for SPP...
# Calculating Status and Trend for each region for EX...
# Error in eval(expr, envir, enclos) : could not find function "EX"
write.csv(scores, 'scores.csv', na='', row.names=F)
# Error in is.data.frame(x) : object 'scores' not found
```
### Delete a goal model from `functions.r`
won't fail at Conf, but will at scores calc.
```{r, eval=FALSE}
# Calculating Status and Trend for each region for AO...
# Error in eval(expr, envir, enclos) : could not find function "AO"
# ...
write.csv(scores, 'scores.csv', na='', row.names=F)
# Error in is.data.frame(x) : object 'scores' not found
```
## Further operations
Please see the [OHI Manual](https://ohi-science.org/manual) to learn more about:
- [Modifying goal models](https://ohi-science.org/manual/#modifying-goal-models)
- [Modifying pressures and resilience](https://ohi-science.org/manual/#modifying-pressures-and-resilience)
- [Removing goals and sub-goals](https://ohi-science.org/manual/#removing-goals-and-sub-goals)
<br>
<!---TODISCUSS: maybe this detail should go somewhere else and then just referenced here? Because will also need this information referenced in the ## Removing Goals and ## Changing Subgoals sections --->
<!--- NOTE: this is where we'll talk about adding/removing goals/subgoals, and goals.csv. First will talk to Mel about goals.csv's future: maybe having them just written in functions.r, and have ohicore pull from that to make a full list --->
<!---
`goals.csv` in the `conf` folder provides input information for `functions.r`, particularly about function calls. These are indicated by two columns: *preindex_function* (functions for all goals that do not have sub-goals, and functions for all sub-goals) and *postindex_function* (functions for goals with sub-goals).
In the `preindex_fuction`, you could specify variables such as _status_year_ and _trend_year_, which you can call in your goal function. Note that it is not necessary to specify those variables. If you do not use them in your function as in the CS example, you could delete those variables in `preindex_function`.
_Changing goal weights will be done here by editing the value in the *weight* column. Weights do not need to be 0-1 or add up to 10; weights will be scaled as a proportion of the number of goals assessed. The ten goals are weighted equally by default._
Add sections or new chapter about
Pressures/Resil:
Testing a figure
To create a figure:
- [drawings folder](https://drive.google.com/drive/u/1/folders/0B9RHfIEZlRcaS1FXWW9EZVBDMHc?ogsrc=32), new drawing
- mac shortcut for screenshot to the clipboard!
- then Edit > Publish to the Web...
- Click publish, then OK
- paste that link into ![]()
--->