1.3.1 Incorporate core values and characteristics into the OHI assessment framework before gathering information

Begin your assessment by identifying local socio-cultural-economic characteristics and priorities related to ocean health, and how they would ideally be captured with the existing or modified OHI framework. This means understanding the rationale behind the components of the OHI framework and identifying what must be added or removed or redefined to ensure that it best represents the local context. Are all goals relevant to your study area? What should be added, removed, or redefined? In this process it is important to identify not only characteristics that could be included in goal models, but also the important stressors (pressures) and resilience elements within the study area. What are the key issues that should be included for your assessment to be credible, useful, and meaningful? How do people typically relate to the ocean in your area in terms of social and cultural patterns? These are the kinds of questions you should consider prior to assembling the available information.

The OHI framework should guide your assessment, but you should not be constrained by it. If a goal is not relevant, it should be removed. If there are elements important to your study area that are not present within the existing framework, how could they be included? Having a clear picture of how the framework should be restructured and what the assessment should include is very important before moving on to assemble information, because otherwise the assessment could be biased by what information is available instead of what is important to include. When specific information is limited there are ways to capture them with indirect measures.

1.3.2 Maintain core values and characteristics within the assessment framework regardless of limited information quality

The assessment framework can be implemented using the best freely-available existing information, even if the information available is ‘limited’ or not ‘ideal’. ‘Limited’ information may be of low quality, have gaps, or be indirectly obtained through modeling instead of being directly measured. Different methods can be used to work with limited data, such as gap filling, incorporating indirect (proxy) or place-holder information, or using intermediate models.

Remaining true to the conceptual framework by using those methods, hence developing less-than-ideal goal models, provides a fuller picture than redesigning it to only include characteristics where ideal information is available. This is because all key characteristics in the system should be represented somehow in a comprehensive assessment, even if assumptions must be made to compensate for missing information. If these methods, including assumptions and rationales, are clearly considered and explained, completed assessments will not only provide the best possible picture of the current system but will also identify information gaps and highlight areas for improvement. Such scrutiny of available knowledge could be lost if important elements were simply excluded from the assessment due to imperfect representation.

1.3.3 Strategically define spatial boundaries balance information availability and decision-making scales

Identifying the spatial boundaries of the Regions within the Assessment Area is extremely important because OHI scores are calculated for each unique Region, and the boundaries will be used to aggregate or disaggregate input information reported at different spatial scales. Spatial boundaries should be defined with geographic information system (GIS) mapping software, ideally per management jurisdiction (see Defining spatial boundaries section for technical guidance). Jurisdictional boundaries are optimal because it is often at these scales where management and policy decisions are made, cultural priorities and management targets are identified, and information is collected in standardized and therefore comparable ways.

Within the OHI framework, there is no limit to the number of Regions that can exist within the Assessment Area; the number is only constrained by data availability and the utility of having scores calculated for a particular Region. Although it is possible to assess only one region in the study area (i.e. the region is the assessment area), this might not be ideal because it eliminates the possibility of making comparisons or identifying geographic priorities within the study area.

1.3.4 Carefully document and share all decisions in writing and computational code

Documentation of all aspects of an assessment process is paramount to ensuring transparency of the decisions made, reproducibility and interpretation of results, repeatability to facilitate and compare future assessments, and the ease of communication throughout the process.

Detailed information about how the assessment is conducted will enhance its credibility and reproducibility. Decisions of why information was included and why models were developed in a certain manner are of great importance so that future assessments can incorporate the same logic and understanding of the system — or make improvements. Further, the type of workflow developed and software used to organize and process information will greatly affect the efficiency, transparency, and reproducibility of subsequent assessments. Providing public access to all such information, as well as input data and computational code is becoming the standard for scientific inquiry, so every effort should be made to achieve those aims.

This means documenting and sharing not only the tools and methods used but also the knowledge gained through the process based on decisions made, what was decided against (e.g. why information was included or excluded, and how it was processed), challenges encountered, and recommendations for improvement. Frank documentation about the successes and shortcomings makes for greater scientific credibility, enables others to replicate what was done, and allows for the most appropriate interpretations of the results, as well as the highest potential for future improvement of assessment approaches, and ultimately, management towards ocean health.

2.1.1 Why a Starter Repo?

The purpose of this repository is to help you learn the Github/RStudio workflow, and to organize and explore available data to help finalize the spatial boundaries you are considering. We highly encourage you to code this exploration in R.

Learn Github/RStudio and collaborate with your team

OHI promotes open science where detailed information about how the assessment is conducted is documented and shared. Providing public access to your input data, computational code, as well as rationales of each step of the assessment is becoming the standard for scientific inquiry, so every effort should be made to achieve those aims. Github/RStudio is a powerful combination that organizes and processes information for this purpose and greatly increases the efficiency of conducting repeated and reproducible assessments, and is the backbone of the OHI Toolbox.

The Starter Repo will get you familiar with this system, and help you develop an efficient workflow to script data exploration and document your decision-making process at once. Furthermore, the scripting language can be directly rendered as webpages, PDFs, presentations, or Word documents for internal and public communication!

Prepare and Organize Data

Data preparation (formatting, exploring, plotting data) takes the largest amount of time in all OHI assessments. An OHI assessment deploys from dozens to more than a hundred data layers coming from as many public data sources. Very rarely can raw data be used in the format you receive them; they require a significant amount of cleaning and formatting before they become usable OHI data layers. During that exploration process, you’ll likely need input from colleagues or outside experts and go through rounds of revisions. Instead of trying to track changes between dozens of data files and long email chains yourself, use Github’s version control system that saves each version automatically. You can document conversations and decisions alongside your R code.

Scripted data exploration (e.g. done in R) is useful whether you decide to use the data in your assessment or not. If you use the data, you have already begun preparing it for the Toolbox. And if you don’t use the data, it can be very important to be able to communicate why.

Finalize spatial boundaries

OHI scores are calculated for regions with clearly defined boundaries, and you will use your Starter Repo to finalize them. Spatial boundaries are often set based on jurisdictions (i.e. within which boundaries would OHI scores be of interest) and data availability (i.e. within which boundaries are data reported) See above section for more details. The Defining Spatial Boundaries section provides instructions of what you need to consider and the files you need to provide to the OHI Team. Once you provide final files, the OHI Team will be able to create your Full Repo.

You could also start exploring goal models, which will reduce the amount of work you will do when you receive the Full Repo for scores calculation.

2.1.2 What’s in the Starter Repo?

The Starter Repo simply contains a prep folder, which includes folders to organize, document, and explore data for:

• each goal or subgoal
• pressures
• resilience

Within each folder, it’s up to you how to populate and organize the contents. We recommend that within each folder you save the raw data files if possible, and create a data preparation script (eg. CW_data_prep.R or CW_data_prep.Rmd for Clean Water) to explore data and document decision making.

2.1.3 How to request a Starter Repo?

You can create a GitHub account at http://github.com with a username and password. To request a repo, email info @ohi-science.org with three things:

• your Github username
• the name of your assessment area (eg. the Gulf of Guayaquil)
• a shortened name for the repository (our convention is a 3-letter code). For example, the Gulf of Guayaquil assessment had gye as their code.

2.2.1 Why a Full Repo?

After you have explored your data and finalized spatial boundaries, the Full Repo offers the rest of the scripts and files you need to complete your OHI+ assessment.

The Full Repo is a repository pre-populated with R scripts and data layers disaggregated from the most recent global OHI assessment, structured in the same way as the global OHI assessments. This way you don’t need to start your assessment from scratch; you can explore a working repository and build from there. For example, instead of writing scripts for goal models from the beginning, you can modify existing scripts to suit your own needs. Data layers disaggregated from the global assessments are available to use, however, we do recommend that you replace as many global data with higher-resolution local data as possible.

2.2.2 What’s in the Full Repo?

The Full Repo contains all the files you need to calculate scores, and produce figures and reports:

• data layers are organized into one folder (layers), with a registry that lists attributes about them and what they are for (layers.csv)
• goal models are organized in one file (functions.r) in the configure (conf) folder
• pressures and resilience matrices that indicate which pressures/resilience apply to which goal, also in the configure (conf) folder
• scripts that use ohicore, an R package built by the OHI Team to calculate OHI scores, create visuals and other core operations.

You can see a full description of each file and script and how they are organized in the File System section.

2.2.3 How to request a Full Repo?

To request a Full Repository, you will need to email info @ohi-science.org with:

• shape files of your finalized spatial boundaries
• the name of your scenario, which is often the definition of your assessment region and the year (e.g. province2016, region2015)

We can then provide you with a Full Repo with the regions defined and pre-populated data layers extracted from the most recent global assessment according to your regional boundaries.

3.1.1 Thinking creatively

Humans interact with and depend upon the oceans in complex ways, some of which are easy to measure and others of which are harder to define. More familiar measurements include providing seafood, or disposing of waste. A less familiar measurement is how marine-related jobs affect coastal communities, or how different people receive or perceive benefits simply from living near the ocean. Thinking creatively and exploring the information available can make your assessment more representative of reality.

Data used in OHI assessments spans a wide array of disciplines beyond oceanography and marine ecology. It is important to think creatively and beyond the interests of a specific institution or one particular field of study. Therefore, it is necessary to look beyond the most known or obvious data sources to find data relevant for the goals in the study area. Discussions with colleagues, literature searches, emails to experts, and search engines are good ways to understand what kinds of data are collected and to hunt for appropriate data. Investigate what kinds of information are available from government and public records, scientific literature, academic studies, surveys and reports, etc.

3.1.2 Data sources

Existing data and indicators can be gathered from many sources across environmental, social, and economic disciplines. This includes government reports and project websites, peer-reviewed literature, masters and PhD theses, university websites, and information from non-profit organizations, among others.

All data must be rescaled to specific reference points (targets) before being combined with the Toolbox; therefore setting these reference points at the appropriate scale is a fundamental component of any OHI assessment. This requires your assessment team to capture the philosophy of each Index goal and sub-goal using the best available data and indicators. Indicators that are already scaled (e.g., from 0-1 or 0-10) can easily be incorporated into your assessment; they have already been scaled to some kind of identified target or reference point. Data that have not been scaled in most cases will need to be, whether this is by scaling to the maximum value in the range or to some other understood value. You should think about how you would rescale data during your search.

Because data and indicators will come from different sources, they will also have different formatting. To include these data and indicators in your assessment, you will need to process these files into the format required by the Toolbox, which is explained in the section Formatting Data for the Toolbox. When data have been prepared and formatted for the Toolbox, they are called layers. Because creating layers can be quite time-intensive, data should only be prepared for the Toolbox after final decisions have been made to include the data or indicator in your assessment, and after the appropriate goal model and reference points have been finalized.

3.1.3 Gathering responsibilities

Gathering appropriate data requires identifying and accessing existing data. It is important that team members responsible for data discovery make thoughtful decisions about whether data are appropriate for the assessment. Data discovery and acquisition are typically an iterative process, as there are both practical and philosophical reasons for including or excluding data.

3.1.4 Requirements for data and indicators

There are six requirements to remember when investigating (or ‘scoping’) potential data and indicators that are presented in this section. It is important that data satisfy as many of these requirements as possible. To meet these requirements, you may have use appropriate methods to fill gaps in the data set. Data sources may need to be excluded from the analyses if requirements are not met and gap-filling solutions are not possible. If data cannot be included, you may elect to use layers from the global assessment or identify other data or modeling approaches.

3.1.5 Relevance to ocean health

There must be a clear connection between the data and ocean health, and determining this will be closely linked to each goal model.

3.1.6 Accessibility

The two main points regarding accessibility are whether the source is open access and whether the data or indicators will be updated regularly.

The Index was created in the spirit of transparency and open-access, using open-source software and online platforms such as GitHub, is to ensure as much accessibility and open collaboration as possible. Data and indicators included should also follow these guidelines, so that anyone wishing to understand more about the Index may be able to see what data were used and how. For this reason we emphasize the importance of using data that may be made freely downloadable, as well as the importance of clearly documenting all decisions and reasons for the choices made in selecting data, indicators, and models.

Index scores can be recalculated annually as new data become available. This can establish a baseline of ocean health and serve as a monitoring mechanism to evaluate the effectiveness of actions and policies in improving the status of overall ocean health. This is good to keep in mind while looking for data: will it be available again in the future? It is also important to document the sources of all data so that it is both transparent where it came from and you will be able to find it in the future.

3.1.7 Quality

Understanding how the data or indicators were collected or created is important. Are they collected by a respected organization with quality control? Are there any protocol changes to be aware of? For instance, were there changes in the collection protocol to be aware of when interpreting temporal trends?

3.1.8 Reference point

Most data will need to be scaled to a reference point. As you consider different data sources it is important to think about or identify what a reasonable reference point may be. Ask the following types of questions as you explore data possibilities:

• Has past research identified potential targets for these data? For example, fisheries goal require a Maximum Sustainable Yield (MSY).
• Have policy targets been set regarding these data? For example, maximum levels of pollutants allowed in beaches.
• Would a historic reference point be an appropriate target? For example, the percent of habitat coverage before coastal development took place.
• Could a region within the study area be set as a spatial reference point? For example, a certain region is regarded as the leader in creating protected areas.

3.1.9 Appropriate spatial scale

Data must be available for every region within the study area. It is not always possible to fully meet the spatial and temporal requirements with each source. In these cases, provided that the gaps are not extensive, it can still be possible to use these data if appropriate gap-filling techniques are used (See: Formatting Data for Toolbox section).

3.1.10 Appropriate temporal scale

Data must be available for ideally the five most-recent years to calculate the recent trend. For some goals, where temporal reference points are desirable, longer time series are preferable.

3.1.11 The process of information discovery

The most important thing to remember when gathering data and indicators is that they must contribute to measuring ocean health. Not all information that enhances our knowledge of marine processes directly convey information about ocean health and may not be appropriate within the OHI framework. Because of this, compiled indicators can sometimes be more suitable than raw data measuring single marine attributes.

Whether you are working goal-by-goal, or layer by layer, it is important to consider where you can find synergies in data discovery. For example, while you are looking for information for the fisheries goal, you may also find data layers for fishing pressures, such as metrics on bycatch or trawling intensity. This will save you time and allow you to start thinking about how to rank pressures and resilience weights on your goals as well. Conceptually, it will help your team build a picture of how your goals are interlocking in a way that is reflective of the actual linkages that exist in the connected systems you are studying. Some key examples are listed below, and are further explained in the following sections.

You should begin by understanding and comparing the best approaches used in assessments that have been completed, including the global assessments (Halpern et al, 2012; 2013), Brazil (Elfes et al. 2014), Fiji (Selig et al., 2014), and the U.S. West Coast Assessment (Halpern et al., 2014). For OHI+ assessments, if finer-resolution local data were available in the study area, these data were either incorporated into modified goal models that used locally appropriate and informed approaches or into the existing global goal model. When local data were not available, the global-scale data and global goal models were used, which is least desirable because it does not provide more information than the global study.

When looking for data, the following decision tree may be useful when going goal-by-goal for discovering data and developing models:

3.2.1 Uploading and formatting raw data files

Unformatted data files can be uploaded to the pre-proc folder in your github repository and processed with R. Saving raw data in the same repository helps to keep track of how the data has been treated.

Raw files can be uploaded as .csv or .xlsx. However, formatted data has to be saved as .csv in the layers folder.

In addition to pre-proc, a prep folder has been set up for data formatting. Inside the folder:

• several sub-folders exist to house formatted data files for each goal/sub-goal
• prep.r is where formatting occurs for each goal/sub-goal.
• README is where you can record information on raw data files and processing for future reference

Example of data in the appropriate format:

3.2.2 Gapfilling

It is important that data prepared for the Toolbox have no missing values or ‘gaps’. Data gaps can occur in two main ways: 1) temporal gaps: when several years in a time series in a single region have missing data, and 2) spatial gaps: when all years for a region have missing data (and therefore the whole region is ‘missing’ for that data layer).

How these gaps are filled will depend on the data and regions themselves, and requires thoughtful, logical decisions to most reasonably fill gaps. Each data layer can be gapfilled using different approaches. Some data layers will require both temporal and spatial gapfilling. The examples below highlight some example of temporal and spatial gapfilling.

All decisions of gapfilling should be documented to ensure transparency and reproducibility. The examples below are in Excel, but programming these changes in software like R is preferred because it promotes easy transparency and reproducibility.

3.2.2.1 Temporal gapfilling

Temporal gaps occur when a region is missing data for some years. The Toolbox requires data for each year for every region. It is important to make an informed decision about how to temporally gapfill data.

Often, regression models are the best way to estimate data and fill temporal gaps. Here we give an example that assumes a linear relationship between the year and value variables within a region. If data do not fit a linear framework, other models may be fit to help with gapfilling. Here we give an example assuming linearity.

Using a linear model can be done in most programming languages using specific functions, but here we show this step-by-step using functions in Excel for Region 1.

Temporal gapfilling example (assumes linearity: able to be represented by a straight line on a graph)):

There are four steps to temporally gapfill with a linear model, illustrated in the figures with four columns.

1. Calculate the slope for each region

The first step is to calculate the slope of the line that is fitted through the available data points. This can be done in Excel using the SLOPE(known_y’s,known_x’s) function as highlighted in the figure below. In this case, the x-axis is years (2005, 2006, etc…), the y-axis is count, and the Excel function automatically plots and fits a line through the known values (177.14 in 2005, 212.99 in 2008, and 228.81 in 2009), and subsequently calculates the slope (12.69).

2. Calculate the y-intercept for each region

The next step is to calculate the intercept of the line that is fitted through the available data points. This can be done in Excel similarly as for the slope calculation, using the the INTERCEPT(known_y’s,known_x’s) function that calculates the y-intercept (-25273.89) of the fitted line.

3. Calculate y for all years

The slope and y-intercept that were calculated in steps 1 and 2 can then be used along with the year (independent variable) to calculate the unknown ‘y-values’. To do so, simply replace the known three values into the y = mx + b equation (m=slope, x=year, b=intercept), to calculate the unknown ‘count’ for a given year (189.39 in 2006, and 202.08 in 2007).

4. Replace modeled values into original data where gaps had occurred

Substitute these modeled values that were previously gaps in the timeseries. The data layer is now ready for the Toolbox, gapfilled and in the appropriate format.

3.2.2.2 Spatial gapfilling

Spatial gaps are when no data are available for a particular region. The Toolbox requires data for each region. It is important to make an informed decision about how to spatially gapfilling data.

To fill gaps spatially, you must assume that one region is like another, and data from another region is adequate to be substituted in place of the missing data. This will depend on the type of data and the properties of the regions requiring gapfilling. For example, if a region is missing data but has similar properties to a different region that does have data, the missing data could be ‘borrowed’ from the region with information. Each data layer can be gapfilled using a different approach when necessary.

Characteristics of regions requiring gapfilling that can help determine which type of spatial gapfilling to use:

1. proximity: can it be assumed that nearby regions have similar properties?

2. study area: are data reported for the study area, and can those data be used for your regions?

3. demographic information: can it be assumed a region with a similar population size has similar data?

Spatial gapfilling example:

For a certain data layer, suppose the second region (rgn_id 2) has no data reported, as illustrated in the figure above. How to spatially gapfill rgn_id 2 requires thinking about the properties and characteristics of the region and the data, in this case, tourist count.

Here are properties that can be important for decision making:

rgn_id 2:

• is located between rgn_id 1 and 3
• is larger than rgn_id 1
• has similar population size/demographics to rgn_id 3
• has not been growing as quickly as rgn_id 4

There is no absolute answer of how to best gapfill rgn_id 2. Here are a few reasonable possibilities:

Assign rgn_id 2 values from:

• rgn_id 1 because it is in close proximity to rgn_id 2
• rgn_id 3 because it is in close proximity to rgn_id 2 and has similar population size/demographics
• rgn_id 1 and 3 averaged since they are in close proximity to rgn_id 2

Suppose the decision was made to gapfill rgn_id 2 using the mean of rgn_id 1 and 3 since this would use a combination of both of those regions. Again, other possibilities could be equally correct. But some form of spatial gapfilling is required so a decision must be made. The image below illustrates this in Excel.

The data layer is now ready for the Toolbox, gapfilled and in the appropriate format.

3.2.3 Long formatting

The Toolbox expects data to be in ‘long’ or ‘narrow’ format. Below are examples of correct and incorrect formatting, and tips on how to transform data into the appropriate format.

Example of data in an incorrect format:

With ‘wide’ format, data layers are more difficult to combine with others and more difficult to read and to analyze.

Transforming data into ‘narrow’ format:

Data are easily transformed in a programming language such as R.

In R, the tidyr package has the gather command, which will gather the data from a wide format into a narrow format. It also can spread the data back into a wide format if desired. R documentation:

• http://blog.rstudio.org/2014/07/22/introducing-tidyr/
• http://www.rstudio.com/resources/cheatsheets/

The final step is optional: ordering the data will make it easier for humans to read (R and the Toolbox can read these data without this final step):

Example of data in the appropriate (long) format:

3.2.4 Rescaling your data

An important consideration is how to rescale your data when preparing it for use in the Toolbox. Rescaling involves turning a distribution of data into a value from zero to one. This is based on finding a highest observed or theoretical point in the distribution of the data, and from there, the relative value of the data can be calculated.

3.2.5 Naming data layers

Please name each data layer with the following format so it is easy to keep all data organized:

prefix_layername_regionYEAR_suffix.extension

There cannot be any white spaces in any part of the filename: instead, use underscores (’_’).

The prefix will be the letters identifying each goal (two letters) or sub-goal (three letters):

The layername should be made of words or abbreviations to identify what the layer is (eg. unemployment)

The regionYEAR should identify the assessment scenario: chn2015. This will help separate updated data layers from global data layers (‘glYEAR’).

The suffix of the filename should identify who prepared the data so any questions can easily to sent to the correct person (eg. JL).

The extension identifies the filetype and is separated by a period (.). You must save your files as comma separated values (.csv) since this is the format used by the OHI Toolbox.

Here is an example of a properly named data layer for the tourism and recreation goal, where the data are the percent of unemployment prepared by Julia Lowndes.

tr_unemployment_chn2015_JL.csv

3.3.1 Balancing geopolitical boundaries and data limitation

The spatial boundaries of OHI regions are typically set based on:

• Management boundaries: geopolitical boundaries, where policy decisions are made (countries, provinces, etc)
• Biogeographic boundaries: based on natural geography (bay, seas, gulf, etc)
• Data: information availability (spatial scale where are data collected)

OHI utilizes data from dozens to >100 data layers collected by many agencies. Some data are collected within boundaries suitable for your desired geopolitical boundaries. Often they are not. For example, you may wish to assess ocean health for each of the ten states along the coast. However, some measurements are taken on the national level and it is difficult to disaggregate data to the state level, or some measurements might only make sense at the watershed level across a few states.

Data disaggregation and gap-filling are possible methods of dealing with missing data, but can dilute the information quality within your assessment. If many data layers don’t fit your desired boundaries, you may consider changing your boundaries. Exploring the data sources in the Starter Repo can help you balance jurisdictional boundaries and information availability, and finalize spatial boundaries that make the most sense for the purpose of your assessment.

Note that the OHI does not take a stance on disputed territories. The boundaries are defined by the original map data providers.

3.3.2 Drawing spatial boundaries

Regions must be unique (non-overlapping), and boundaries must be drawn offshore. Offshore boundaries should be made with spatial methods in order to extend boundaries from those designated on land.

Spatial boundaries must be drawn with geographic information system (GIS) mapping software such as ArcGIS, QGIS, or GRASS. You will need someone with GIS skills to create a shapefile that will be used by the Toolbox to display your information. The shapefile will also be used to extract information for each of your defined regions when data are reported in raster format for a different area. For more information see Wikipedia for Geographic information systems and Shapefiles.

Illustrated below are the conceptual steps required for creating a spatial file with your offshore boundaries. You will ultimately decide where to draw the offshore boundaries. The example below shows a simple example of extending the land boundaries in a straight line; you should consult with a GIS specialist to make sure any extensions make sense with the coastline and natural features, and also make sure they does not conflict with important jurisdictional boundaries.

Data for different goals often cover different spatial extents offshore. For example, Fisheries might use data from the entire EEZ, while Carbon Storage might only cover 3nm from shore. When mapped, OHI scores do not show different spatial extents, but instead show all to the greatest spatial extent. Exclusive Economic Zone (EEZ) boundaries are most often the greatest extent offshore that OHI scores will represent. These regional spatial boundaries do not affect data preparation and analyses, where you could use any spatial extent appropriate for each goal.

One possible method is to create boundaries with Thiessen Polygons, and we provide a Python script that can be used, but it requires ArcGIS. The Python script and further details can be found here.

To create a repository for your assessment, we just need the off-shore marine water boundaries. But you may also make inland buffers for your analyses. For example, do you want coastal population to include activities within 1km of the coast? Or 10km?

3.3.3 Request a Full Repository with offshore boundaries

In order to create a Full Repository for your assessment, we will need the shapefile for your offshore boundaries (and the name of your scenario, which is to the unit of your assessment and the year, for example, province2016). This will help us disaggregate global data to your local regions and populate usable data layers. Please send a .zip file of all files produced to info@ohi-science.org. Files with the following extensions are required (but you can send all files):

• .dbf
• .shp
• .shx
• .prj

The .dbf file needs the following in its attribute table:

• rgn_id (unique numeric region identifier)
• rgn_name (unique named region identifier)
• area_km2 or area_hectare (area in km2 or hectares)

3.4.1 Developing multiple goal models at the same time

Goals can be assessed independent of one another. As each goal model is developed and data gathered, it can be assessed without affecting other goals.

However, you can develop some goal models simultaneously and streamline the data search. For example, the habitat-based goals Carbon Storage, Coastal Protection, and the Habitats sub-goal of Biodiversity all rely on the same underlying data, and their models can be developed together. A spatial analyst can create the spatial layers used for these goals with the same source material. This will greatly expedite your data layer preparation. Species data for Iconic Species sub-goal of Sense of Place is often a subset of data from Species sub-goal of Biodiversity. Data for non-food marine products for Natural Products and food products for Fisheries sub-goal of Food Provision are often recored in similar data sources and may need partitioning.

If you wish to further coordinate these activities on a higher level, you could have the same team member coordinate activities for the development of certain goals. That is a consideration when assembling your team and planning your workflow. For more details, please see the goal-specific sections.

3.4.2 Keeping Reference Points in Mind

Setting a reference point is required for every goal model you develop. It is an “ideal” condition, or target, where the goal is considered to be achieved to its full potential. Achieving or exceeding the reference point will result in a score of 100. The choice of a reference point will thus affect how the final scores are calculated, and must be balanced between knowledge of the system, expert judgment, and limitations of the data. You may set an universal reference point for all regions in your study area, or you may set a unique reference point for each region.

Generally there are four types of reference points: + Functional: Scientifically sound target set based on the known responses of variables measured, such as Maximum Sustainable Yield. + Temporal: A historical benchmark is used as a the “ideal” point in the past, such as mangrove coverage in the 1980’s. + Spatial: A region within the study area with the highest input values, and all others are scaled to it. + Established target: Such as a sustainable catch yield by a certain year, or the number of people employed in a marine sector by a certain year.

Which type of reference point to use depends on the goal and available data. How many years of data are available? Can you set a temporal reference point with these data, or do you have to find another dataset or other source of information? In any case, you must balance being realistic with being ambitious. We suggest following the S.M.A.R.T. criteria when choosing a reference point: “Specific,” “Measurable,” “Ambitious,” “Realistic,” and “Time-bound.”

You will learn more, and think more critically about reference points, as you develop the data layers for your assessment.

How to use the reference point in a model

It’s best to explicitly include the reference point in the model equation whenever possible. For example, the Carbon Storage goal model in the global assessment is written like this:

,

where C_r is the reference condition of each habitat. See goal-specific sections for more examples.

3.4.3 Identifying pressures and resilience

While you are developing goal models, you should note the links between your goals and pressures and resilience: both the pressures and resilience that affect them and whether the goal acts as pressure or resilience on other goals. It is recommended to begin gathering data of pressure and resilience from the start of the assessment. The team members who are developing specific goals should think about the pressures that act upon those goals as they are data-gathering, and they should think about the data sources that could provide pressures information. However, it may be most useful when one team member gathers all of the data for pressures, since the same pressures often affect multiple goals. See Pressure and Resilience section of this chapter for more information.

Some pressure data are the same or closely-related to data for goals. For example, the Wild-Caught Fisheries goal model requires catch data, which may be the same data source for information on commercial high- and low-bycatch data, which are used as pressures layers that affect Livelhoods and Economies and Biodiversity. In global assessments, the Clean Waters goal is very much linked to pressures layers because the input layers for its status are used as pressure layers. Trash pollution is a pressure that affects Tourism and Reacreation, Lasting Special Places, Livelihoods and Economies, and Species. It is important to remember these linkages as you go through the data discovery process.

You should also start searching for pressures data independent from data for goals. An example would be how climate change impacts will appear in various places in your assessment. Climate change pressures layers can include UV radiation, sea surface temperature (SST), sea-level rise (SLR), and ocean acidification, and these impacts might affect such goals as Natural Products, Carbon Storage, Coastal Protection, Sense of Place, Livelihoods and Economies, and Biodiversity. These linkages will become more clear as you go through the OHI+ assessment process.

4.1.1 Main folders within your Full Repo

The scenario folder is the most important folder within the repository; by default it is named regionYEAR (eg. cnc2016 for New Caledonia 2016) to indicate that the assessment is conducted at the region scale (province, state, district, etc.), based on input layers and goal models used in the most recent global assessment. It contains all of the inputs needed to calculate OHI scores, and you will modify these inputs when conducting your assessment. The scenario folder is explained in detail in this section.

Navigating the assessment repository. The figure shows Mac folder navigation above and Windows navigation below.

When conducting your assessment, you can rename your scenario folder to reflect the subcountry regions in your study area and year the assessment was completed. For example, province2015 would indicate the assessment was conducted for coastal provinces in the year 2015.

Once you complete your assessment with the regionYEAR (or equivalent) scenario, further assessments can be done simply by copying the regionYEAR folder and renaming it. This can be done for future assessments, for example assessment2016 or assessment2018, which eventually would enable you to track changes in ocean health over time. You can also copy scenario folders to explore different policy and management scenarios, for example regionYEAR_policy1.

This figure illustrates the files contained within the assessment repository’s regionYEAR scenario folder, and in which step of the Toolbox workflow they are associated with. Important files are either .csv text files or .R script files. Files are organized into different folders within the regionYEAR folder, and you will modify some of these files while leaving others as they are.

The conf folder within the regionYEAR scenario folder, the conf folder includes important configuration files required to calculate OHI scores. Most of the maneuvering in this phase is done within this folder. There are both .R scripts (config.R and functions.R) and .csv files (goals.csv, pressures_matrix.csv, resilience_matrix.csv, and resilience_weights.csv), which will be introduced individually in the next section.

The conf folder contains important R functions and .csv files.

The prep folder is important in the beginning of your assessment, as it is where you will store and manipulate raw data to get them ready for calculations.

Over all, all the main files you will encounter are either of the two file types:

• ** .csv files** contain data inputs or configuration information.
• ** .R scripts** are written in the programming language R and use data inputs for processing and calculations.

We will introduce those files below roughly in the order and the frequency of use:

4.1.2 Data layers

• raw data files in prep folder
• layers folder
• layers.csv
• goals.csv
• layers-empty_swampping-global-mean.csv
• pressures_categories.csv
• pressures_matrix.csv
• resilience_categories.csv
• resilience_matrix.csv
• scores.csv

raw data layers in “prep” folder

This is where you will store (and manipulate) raw data files before modifying goal models. We recommend separating data layers into different folders by goal.

layers folder

This folder contains all layers required to calculate goal scores, and each layer is an individual .csv file. The names of the .csv files within the layers folder correspond to those listed in the filename column of the layers.csv. All .csv files can be read in R, or with text editors or spreadsheet editors like Microsoft Excel.

The layers folder contains every data layer as an individual .csv file. Mac navigation is shown on the left and Windows navigation is shown on the right.

Note that each .csv file within the layers folder has been formatted consistently. The Toolbox expects all data layers to be in the correct ‘long format’ and in separate files. Each file also has a column with unique region identifier (rgn_id). These numeric region identifiers have region names associated with them, that are set in rgn_labels.csv and can be modified.

TIP: You can check your region identifiers (rgn_id) in the rgn_labels.csv file in the layers folder.

/glYEAR and /scYEAR suffixes

In your repository, layers are provided for your country based on input information from the YEAR global assessment. The global assessment had information for your country at the the spatial scale of the entire country, whereas your assessment has information for each subcountry region within your country. In most cases, layers from the global assessment was allocated equally to all regions in your study area (country). When this occurred, the layer was given a suffix of _glYEAR to indicate that information is equal across all regions in the study area. While these layers may not provide much useful information to your assessment, the proper input structure is provided in these layers. Some layers contain information such as km2 of habitat that could not be equally allocated across all regions since this would provide a sum much greater than reality. In these cases, layers were down-weighted based on the proportion of offshore area or coastal population density. These layers have the suffix _scYEAR with an indication of what was used to downweight. While this method removes any error of inflated sums and provides the Toolbox with functioning layers, the allocation of these values may not be sensical to your study (i.e. if corals are only present in some regions of your study area but they are allocated to all).

Differences in input layers with equal information for each region (suffixed with _glYEAR) and weighted information for each region (suffixed with _scYEAR).

layers.csv

The layers.csv file is the registry and directory that manages all data required for you assessment. All relevant input information is prepared as individual data layers and then registered in this file. layers.csv is vital to organizing all the data to calculate scores and for visualizations

layers.csv is easiest to view in spreadsheet software (i.e. Microsoft Excel). When you open it, you will see that each row of information represents an individual input layer that has been prepared for the Toolbox. The first columns contain information that will be updated by your team as you incorporate modified or new layers: targets, layer, name, description, fld_value, units, filename.; all other columns are generated later by the Toolbox as it confirms data formatting and content and alerts you of any formatting inconsistencies.

• targets indicates which goal or dimension uses the layer. Goals are indicated with two-letter codes and sub-goals are indicated with three-letter codes (see the table just below). Pressures, resilience, and spatial layers indicated separately.
• layer is the identifying name of the input layer that will be used in R scripts like functions.R and .csv files like pressures_matrix.csv and resilience_matrix.csv.
• name is a longer title of the input layer.
• description is further description of the input layer, including the source of the original data.
• fld_value the values’ units in the input layer. The information in this column must match the column header in the input layer.
• units the values’ units in the input layer. This differs from fld_value above as the units column and has more descriptive naming.
• filename is the input layer itself. This file has input information for each region within the study area, and is located in the regionYEAR/layers folder.

goals.csv

goals.csv is a table with information about goals and sub-goals, including:

• order_color & order_hierarchy: the order to display in flower plots
• order_calculate: the order in which the goals and sub-goals are calculated for the overall index scores
• goal & parent: indicates the relationship between sub-goals and supra-goals (i.e. goals with sub-goals)
• weight: how each goal is weighted to calculate the final Index scores
• preindex_function: indicate what parameters are called to calculate scores for goals and sub-goals in functions.r
• postindex_function: indicate what parameters are called to calculate scores for supra-goals in functions.r

pressures_categories.csv

This is a table to record the name of each pressures data layer, its category, and sub-category. Each data layer name is the same name that’s saved in the layers folder and is registered in layers.csv. Each layer falls under one of two categories - ecological or social pressures, and one of several sub-categories to further represent the origin of the pressure (e.g. climate change, fishing, etc), which is also indicated by a prefix of each data layer name (for example: po_ for the pollution sub-category). For more information, see how to modify pressures layers.

pressures_matrix.csv

It is a table that indicates which individual pressures (stressors) affect which goal, sub-goals, or components, and weights them from 1-3 (a weight of 0 is shown as a blank). A higher weight indicates more negative impacts on that goal or component of the goal. These weights are relative to each row of the matrix (goal, sub-goal, or component). These weights are used in global assessments based on scientific literature and expert opinion, and you can modify the weightings if necessary for your assessment. The pressures matrix is the same as Table S25 in the Supplementary Information for Halpern et al. 2012.

Each pressure (column) of the pressures matrix is the layer name of the pressures layer file that is saved in the layers folder and is registered in layers.csv, matching what’s recorded in the pressures_categories.csv. For more information, see how to modify pressures layers.

resilience_categories.csv

Similar to pressures_categories.csv, this file contains information on each resilience data layer, including its name, category, and sub-category. Each resilience layer’s name is the same as the data layer to be saved in the layers folder and is registered in layers.csv. In addition, it also includes information on category type - ecosystem, regulatory, or social, indicating the origin of the resilience layer.

Each resilience layer is also assigned a weight of 0-1, representing the level of resilience against pressures. Different from the values used in pressures matrix, the resilience weights depend on the level of information available. For more information, read how to modify resilience layers.

resilience_matrix.csv

It is a table that indicates which individual resilience measures affect which goal, sub-goals, or components. These weights are stored in a separate file in the conf folder: resilience_weights.csv. The resilience matrix is the same as Table S26 in the Supplementary Information for Halpern et al. 2012. For more information, read how to modify resilience layers.

scores.csv

scores.csv is a text file containing the calculated scores for each dimension (future, pressures, resilience, score, status, trend) for each region in the study area. Regions have the numeric identifiers set in regionYEAR/layers/rgn_labels.csv and the study area has the numeric identifier of 0. Scores are calculated with registered layers in layers.csv: when you begin an assessment this will be information for your country from the global YEAR assessment and goal models from the global YEAR assessment.

layers-empty_swapping-global-mean.csv layers-empty_swapping-global-mean.csv contains a list of layers where information for your country was not available for the global assessment. For the Toolbox to be able to run, these layers were filled with averages from all other countries included in the global assessment. This file is not used anywhere by the Toolbox but is a registry of layers that should prioritized to be replaced with your own local layers if you require these layers for the models you develop.

4.1.3 R scripts

• install_ohicore.R
• configure_toolbox.R
• calculate_scores.R
• data_prep.R in prep folders
• functions.R
• config.R
• launch_app_code.R

install_ohicore.R

This script installs ohicore, which is the second repository required for the Toolbox and is the engine behind all OHI calculations. You will need to run this script only once when you first install the toolbox.

configure_toolbox.R

This script does the pre-checks before running goal models and calculate dimension scores. It loads “ohicore”, calls all goal functions and data layers in the “conf” folder, and check that all data layers are registered properly. You are encouraged to use this script when you’re working on individual goal models. After you register data layers for a goal, or make any changes to the data layers, source this script before running model-specific functions in functions.R.

calculate_scores.R

It runs everything required to calculate OHI scores using the prepared layers the layers folder that are registered in layers.csv. Scores will be saved in scores.csv.

functions.R`

This script contains the equations for each goal and sub-goal model. Each goal and sub-goal equation is stored as a separate function within the script. These functions calculate the status and trend using prepared layers saved in the ‘layers’ folder and registered in layers.csv. You will need to code in R to modify or develop new models, and it is best to work on one goal at a time.

config.R in “conf” folder

It configures labeling and constants appropriately. You will only need to modify this file when working with goals that have categories (example: habitat types or economy sectors) that are affected differently by pressures and resilience measures.

launch_app_code.R

It will launch a version of the App on your computer so that you can visualize any edits you make before syncing to github.com.

4.1.4 Other

• reports
• session.txt
• spatial
• temp

reports folder

The reports folder contains flower plots and tables for every region in the study area and for the study area itself, which by convention is called ‘GLOBAL’ in these files.

session.txt

session.txt is not used in OHI calculations but stores information about how the Toolbox was installed which may be useful for debugging purposes.

spatial folder The spatial folder contains two spatial files: regions_gcs.geojson and regions_gcs.js. These files spatially identifies the study area and regions for the assessment and are stored in the JSON and GeoJSON formats that can be displayed by the App. If you plan to redefine the spatial boundaries for your assessment, you will need to provide a shapefile to the OHI+ development team and we will create the proper regions_gcs.geojson and regions_gcs.js files for you. You will need a spatial analyst to do this: see the Defining spatial boundaries section for instruction.

temp or tmp folders

Contents within the temp or tmp folders are not used to calculate scores but can be used for temporary organization for your assessment.

4.2.1 Install ohicore

ohicore is a R package containing all the essential functions you will use to calculate the final OHI scores, and you can call the functions contained in ohicore from your Full Repo.

To install, find the script install_ohicore.r in your scenario folder (ie. your regionYEAR folder). Run the entire script, and now your Toolbox is all set up and ready to go!

This only needs to be done once at the beginning of your assessment, and you do not need to rerun it again during an assessment.

Although ohicore is a package you would not normally interact with, it can be useful to have the folder cloned to your computer for debugging, particularly with pressures and resilience calculations for goals that have components in the matrix. To do so, you will clone the repository (https://github.com/OHI-Science/ohicore) as you would your assessment repository.

4.2.2 Check pre-loaded, template data and models

As a starting point, your Full Repo is populated with data and functions from the most recent global OHI study, which you can then modify directly. To check that your repository is set up properly and the pre-loaded scripts and data are functional, you can run regionYEAR/configure_toolbox.R. It will produce scores for each dimension in regionYEAR/scores.csv. When it’s all set up, you can begin adding your own data and goal models.

configure_toolbox.R should be run each time you change or add a new data layer to make sure it is properly formatted and registered.*

Now you have set up your Full Repo, the following “How To” sections will show you how to finish OHI score calculations in the Full Repo, including how to save data layers, modify goal models, pressures and resilience, etc.

7.1.1 How to identify and quantify pressures

The Toolbox calculates pressures in five ecological pressure categories (e.g., pollution, habitat destruction, fishing pressure, species pollution, and climate change) and one social pressure category (e.g. strength of governance). Under each category, there can be multiple pressure data layers. For example, the “pollution” category could include pathogen, nutrients, and chemical pollution.

The reason behind the ecological categories is to avoid hidden weighting (e.g., overrepresentation of pressures for which there are more data). For example, in the global assessment there were many pollution datasets available, but few distinct habitat destruction datasets. If we simply averaged the scores of each individual stressor, pollution scores would have a greater influence on the results (stronger weight) due to the relative higher availability of measurements of various pollutants. Instead, aggregating by pressure categories ensures that different stressor types influence the score explicitly. Nonetheless, the scores are combined in a cumulative way within each category to account for the fact that multiple stressors within a category have a cumulative impact that is greater than if only one of the stressors were present. The resulting scores for the five ecological categories are averaged to produce a single ecological pressures score. This score is then averaged with the social pressures score to produce the final overall pressure score.

There are two types of pressures data you need to provide for the toolbox: data layers for each pressure and the pressure matrix.

7.1.1.2 Pressures matrix

Independent from the pressures data layers, you will modify the Pressures Matrix table that establishes the relationships between stressors and goals, i.e. how each pressure measure affects each goal, or distinct components of a goal (e.g. an individual habitat type or natural product). It uses a rank from 1-3 to weight how strongly a given pressure affects a goal or sub-goal relative to all the other pressures affecting it.

It is easy to confuse the weights with pressure data layers. But pressure weights assigned in the pressures matrix are based on how strongly those pressures affect each goal; the weights are not different across regions (region-specific data are stored in the data layers). Read on for further explanation.

The rank weights used in the pressures matrix were determined by Halpern et al. 2012 (Nature) based on scientific literature and expert opinion (see Supplemental Table S28 of Halpern et al. 2012). For example, commercial high and low bycatch are categorical values that were set based on fishing gear type. This began as a list of gear types used, producing a range of potential bycatch frequencies (from local reports when possible), which can be rescaled. In the pressures matrix ranks are categorized as follows:

• 3 = high pressure
• 2 = medium pressure
• 1 = low pressure

Scores from 1-3 are given to rank the importance of each pressure. Only values of 2 or 3 require that a resilience layer be activated when calculating the goal scores.

Stressors that have no impact are left blank in the matrix rather than being assigned a rank of zero, which would affect the average score. Pressures are ranked rather than being represented as a binary (yes/no) measure because the range of consequence of different pressures on each goal can be quite large, and to classify all those pressures as a simple ‘yes’ would give too much influence to the weakest stressors. For example, food provision could be most heavily impacted by unsustainable, high-bycatch fishing, but pollution does have some impact on fish populations. Without a weighting system, these stressors would be treated equally in their impact on the food provision goal. In the figure above, a climate change pressure is the strongest variable acting on the Fisheries sub-goal.

How are Pressures calculated in the Toolbox?

Conceptually, pressures in OHI can be represented by three-dimensional matrix by combining the pressures matrix with each associated data layer. The Toolbox will: 1. For each stressor, multiply the local data for each region (between 0 and 1) by the weight (NA, 1, 2, or 3) assigned to that pressure for a specific goal and subgoal 2. Within each category, combine all stressor data from step 1 to get a category score 3. Average scores of all categories to get an overall pressures score for that goal or sub-goal

The pressures matrix is three-dimensional: each pressure layer has data per region, which is multiplied by the ranking weights of the pressures matrix.

7.1.2 How to modify Pressures Matrix and Categories in the Toolbox

Your team will identify if any pressures layers should be added to the pressures matrix, and if so, which goals the pressure affects and what weight they should have. You can transfer this information in pressures_matrix.csv (located in the [assessment]/[region_year]/conf folder). It is important to note that the matrix identifies the pressures relevant to each goal, and which weight will be applied in the calculation. Each pressure is a data layer, located in the [assessment]/[region_year]/layers folder. This means that pressure layers need information for each region in the study area, and some layers will need to be updated with local data. In modifying pressures, you will need to consider whether data layers can be updated or added, and whether data layers map onto goals appropriately in the local context.

Adding a new pressure to the pressures matrix requires the following steps:

1. Create new pressure layer(s) and save in the layers folder
2. Register pressure layer(s) in layers.csv
3. Register in pressures_categories.csv
4. Register in pressures_matrix.csv, identify the goals affected and set the weights
5. Modify config.R for goals that have elements

7.1.2.2 Register the new pressure layers in layers.csv

Let’s say you were adding two new pressures layers to the pressures matrix. You would then add two new rows in layers.csv, and register the new pressure layers by filling out the first eight columns for po_desal_in, and po_desal_out.

7.1.2.3 Register in pressures_categories.csv

This is a table to record the name of each pressures data layer, its category, and subcategory. Each data layer name is the same name that is saved in the layers folder and is registered in layers.csv. Each layer falls under one of two categories - ecological or social pressures, and one of several subcategories to further represent the origin of the pressure (e.g. climate change, fishing, etc), which is also indicated by a prefix of each data layer name.

Each pressure category is calculated separately before being combined with the others, so it is important to register the new pressure with the appropriate category prefix decided by your regional assessment team.

7.1.2.6 Modify config.R for goals with multiple elements

If a goal has multiple elements (eg. CS has multiple habitats), as reflected in pressures_matrix.csv where the columns element (and element_name) are filled, you need to update config.R in conf folder, as shown below:

The highlighted files are data layers necessary to calculate pressures for each of the goals with components. They contain weights, or relative contribution from each element to the total pressures of the goal. These weights are calculated separately in the data prep folder for each goal, and saved and registered as you would for any data layer. How to calculate these data layers can be found in the description column of layers.csv.

7.2.1 How to identify and quantify resilience

Resilience is included in OHI as the sum of the ecological factors and social initiatives (policies, laws, etc.) that can positively affect goal scores by reducing or eliminating pressures. The addition of new pressure layers may therefore warrant the addition of new resilience layers that were not previously relevant. Similarly, the removal of pressure layers may warrant the removal of now irrelevant resilience layers. You can then transfer this information into resilience_matrix.csvand resilience_categories.csv (located in the [assessment]/[region_year]/conf folder).

Ideally, each pressure included in the pressures matrix should have a corresponding resilience measure, which is meant to ‘balance’ the pressures that negatively effects on ocean health. The OHi considers resilience in two categories: ecological resilience to address ecological pressures, and social resilience to estimate how a region may be able to respond to or prevent environmental challenges. Additionally, goal-specific regulations are intended to address ecological pressures, and are measured as laws, regulations, and other institutional measures related to a specific goal. Ideally, for any resilience measure, you would have three tiers of information:

• Existence of regulations: Are regulations in place to appropriately address the ecological pressure?
• Implementation and enforcement: Have these regulations been appropriately implemented and are there enforcement mechanisms in place?
• Effectiveness and compliance: How effective have the regulations been at mitigating these pressures and is there compliance with these regulations?

Ideally, information would exist for these three tiers, and you would be able to weight the resilience measure based on the quality of the information as 1 (existence of regulation), 2 (implementation and enforcement), or 3 (effectiveness and compliance). This approach is different from the way ranks are assigned in pressures, which is based on impact. However, in most cases, information is not available for these three tiers: often, the existence of regulations is all that is available, and this does not always vary by region. In some cases, you may want to consider building your own set of indicators to determine implementation and enforcement and effectiveness and compliance.

7.2.2 How to modify Resilience Matrix and Categories in the Toolbox

Adding a new resilience layer to the resilience matrix requires the following steps:

1. Create new resilience layer(s) and save in the layers folder
2. Register resilience layer(s) in layers.csv
3. Register resilience layer(s) in resiliences_categories.csv

• Set the resilience category
  
• Set the weights

4. Register resilience layer(s) in resiliences_matrix.csv

• Identify the goals affected

5. Modify config.R for goals that have elements

7.2.2.2 Register in Resilience Categories

resilience_categories.csv records general information on each resilience data layer. The full list of layers included in the global resilience matrix are shown in the resilience_matrix.csv:

Each resilience layer indicated in the table is a data layer just like all the other data layers you have formatted, saved in the layers folder, and registered on layers.csv. Each layer falls under a category of resilience - ecological or social, and one of three category_type - ecosystem, regulatory, or social, representing the origin of each resilience layer. The subcategory column indicates what specific pressure each layer of resilience is targeted at. The prefix of each data layer corresponds to its subcategory (eg. po, li, g, etc).

In addition, the weight column represents level of institutional governance. Governance is a function of 1) institutional structures that address the intended objective (eg. whether appropriate laws/regulations exist, etc), 2) a clear process for implementing the institution is in place, and 3) whether the institution has been effective at meeting stated objectives. At global scales it is very difficult to assess these three elements; we usually only had information on whether institutions exist. However, in some cases we had detailed information on institutions that enabled us to assess whether they would contribute to effective management, and thus, increased ocean health. In those latter cases, we gave more weight to those measures. In the resilience_categories.csv pre-loaded from OHI-Global 2016 to your repository, there are two weights assigned to each layer:

• 0.5 means that a law or regulation exists, or a country has signed an appropriate treaty
• 1 means that there are evidence of implementation of the laws and regulations.

However, you can redefine how the weights are set to available information in your regions.

7.2.2.3 Register in Resilience Matrix

resilience_matrix.csv maps the different types of resilience (columns) with the goals that they affect (rows). Whether a resilience layer has any influence on a goal, or an element of the goal, is represented by an x, or its absence. For example, po_water layer is relevant to the salt marsh element of CP goal, as shown by the x in the cell. On the other hand, that data layer does not apply to the mangrove element of the same goal, hence the absence of an x.

New resilience layers may be added to resilience_matrix.csv based on finer-scale local information either in response to a new pressures layer, or as a new independent measure. Any added layer must be associated with a pressures layer that has a weight of 2 or 3 in the OHI framework so that resilience measures can mitigate pressures in each region.

7.2.2.4 How to modify config.r for goals with multiple elements

If a goal has multiple elements, as shown in pressures_matrix.csv, you need to update config.r in conf folder, as shown below:

8.2.1 Remove subgoals from goals.csv

goals.csv is a table with information about the relationship between goals and sub-goals. Description of what each column means can be read in the data layers section, under goals.csv.

As illustrated in the graph below, removing the subgoals involves simplifying how BD and its subgoals are registered in the columns:

• change the order and order_hierarchy to 10
• remove BD from the postindex_function column & add to the preindex_function column
• change the function call from BD(scores) to BD(layers)

8.2.2 Remove subgoals from functions.r

functions.rcontains the R codes to calculate status and trend for each goal and sub-goal, contained within individual functions. Calculations are done using prepared layers saved in the layers folder and registered in layers.csv. As shown below, HAB and SPP each has its own function, calling data layers from layers. The BD function combines HAB and SPP scores, calling scores.

To remove the subgoals, you can delete functions for HAB and SPP completely, and write a function for BD as you would for any goal, calling layers.

Remember that subgoal functions read in data layers and calculated sub-goal scores; supra-goal reads in those sub-goal scores to calculate scores for that supra-goal.

8.2.3 Remove subgoals from pressures_matrix.csv

This table indicates which individual pressures (stressors) affect which goal, sub-goals, or elements, and weights them from 1-3 based on the degree of impacts. To remove subgoals from this matrix, you can simply delete the rows for each subgoal (HAB and SPP), and add a new row for BD, and treat BD as you would an individual goal with no subgoals.

8.2.4 Remove subgoals from resilience_matrix.csv

This table records information on which individual resilience measures affect which goal, sub-goals, or elements. Similar to what you would do with ‘pressures_matrix.csv’, you can delete the rows for HAB and SPP, and add a new row for BD.

10.1.1 rpostback-askpass error

Sometimes when RStudio won’t push committed changes to GitHub, RStudio displays an rpostback-askpass error:

error: unable to read askpass response from 'rpostback-askpass'
fatal: could not read Username for 'https://github.com': Device not configured

Error screen window: ‘error: unable to read askpass response’.

To fix it, open the shell: Tools > Shell.

git push -u origin master

10.1.2 Git not detected on system path

After downloading and installing git, sometimes RStudio is unable to locate git and will show the following error:

Error screen window:‘Git was not detected on the system path’

It is important to make sure you do in fact have git installed on your computer first. You can do this by opening up terminal (Mac OSX) or the cmd line (Windows) and typing:

• $ which git for Mac/Linux,
• $ where git for Windows

These commands will tell you where the git.exe file is located. Typically it will look something like this: /usr/local/git/bin/git or /usr/bin/git or some variation of those.

Once confirming the location of git.exe you need to tell RStudio where it is. Open up RStudio, got to Preferences and select the Git/SVN option:

In the Git executable area, fill in the path to your git.exe. If RStudio does not let you manually enter your path, select Browse… and navigate to the git.exe file. If you are not able to navigate to the file it is likely a hidden file.

On a Mac, to make hidden files visible, close RStudio and do the following:

• Open Terminal found in Finder > Applications > Utilities.
• In Terminal, paste the following: defaults write com.apple.finder AppleShowAllFiles YES.
• Press return.
• Hold the ‘Option/alt’ key, then right click on the Finder icon in the dock and click Relaunch.

And then reopen RStudio, go to Preferences -> Git/SVN -> Browse… and you should be able to navigate to the git.exe

You will then need to create an RSA Key. You can do this by clicking on ‘Create RSA Key…’ at the bottom of the Git/SVN panel, then ‘View public key’. Copy the key you see, and add it to your GitHub account by using the instructions provided here.

10.1.3 Loading RWorkspace on Restart

When you restart your R Session (Session > Restart R on a Mac), if you see that it is trying to load ohicore, it may give you an error:

You do not want it to load ohicore or to save anything in your workspace. You will need to change the default setting from you .Rproj file. Steps to do this:

1. Go to Project Options, either in the pull-down menu or by double-clicking the .Rproj file:

2. Change all options to No:

10.2.1 Useful Errors when Calculating Scores

TIP: You can use the layers function in calculate_scores.R to error-check whether you have registered your files in layers.csv correctly or not. If you haven’t, you will get an error message regarding ‘missing files’.

10.2.2 CheckLayers() error due to ‘Rows Duplicated…’

After registering and uploading data layers, you would run CheckLayers in calculate_score.R to make sure there is no errors with the data files. For example, this error appeared after uploading SPP species data

image

You can use the duplicated function to check which rows in that file is duplicated. Here we checked the first two columns in that file, rgn_id and sciname:

````r d[duplicated(d[c(‘rgn_id’, ‘sciname’)]),]

 rgn_id                sciname CHN_class IUCN_class value       layer

29 2 Chlidonias niger 1 0.46 spp_species 270 10 Stenella longirostris 2 DD 0.17 spp_species

````

10.2.3 Layers() error due to ‘row.names: duplicate ’row.names’ are not allowed’

The following error means that within layers.csv, there are duplicate rows with the same layernames.

The warning message identifies several layer names to investigate…

Error in `row.names<-.data.frame`(`*tmp*`, value = c(2L, 1L, 7L, 14L,  :
  duplicate 'row.names' are not allowed
In addition: Warning message:
non-unique values when setting 'row.names': ‘cw_con_dioxin_status’, ‘cw_con_dioxin_trend’, ‘cw_con_ices6_status’, ‘cw_con_ices6_trend’, ‘cw_con_pfos_status’, ‘cw_con_pfos_trend’, ‘cw_nu_status’, ‘cw_nu_trend’, ‘fis_bbmsy’, ‘fis_ffmsy’, ‘fis_landings’, ‘ico_status’, ‘le_gdp_region’

…and when inspecting layers.csv, there are indeed duplicate entries for the same layernames.

To fix these errors, ensure there are only single entries for each layer name; delete any duplicated rows.

10.2.4 Calculating Pressures…

10.2.4.3 Error in ... length of 'dimnames' [2] not equal to array extent

If you get the following error message when running calculate_scores.r:

scores = CalculateAll(conf, layers, debug=F)
Calculating Status and Trend for FIS...
Calculating Status and Trend for MAR...
reference point for MAR is: 1.16739059262319 (region 8)
Calculating Status and Trend for AO...
Calculating Status and Trend for NP...
Calculating Status and Trend for CS...
Calculating Status and Trend for CP...
Calculating Status and Trend for TR...
Calculating Status and Trend for LIV...
Calculating Status and Trend for ECO...
Calculating Status and Trend for ICO...
Calculating Status and Trend for LSP...
Calculating Status and Trend for CW...
Calculating Status and Trend for HAB...
Calculating Status and Trend for SPP...
Calculating Pressures...

Error in matrix(as.matrix(d.p[, -1]), nrow = nr, ncol = np, dimnames = list(region_id = d.p[[1]],  :
  length of 'dimnames' [2] not equal to array extent

It is because not all the pressures layers listed in pressures_matrix.csv are layers listed in layers.csv.

We troubleshooted this by putting a browser() in ohicore::CalculatePressuresAll.r on L35 (after searching in that file for ‘dimnames’ to try to triangulate to the problem. Then, when rerunning calculate_scores.r with the browser, we looked at the following variables and found the mismatch between the list of layers in pressures_matrix.csv (the p.layers variable, top) and the list of available layers (bottom) which EXCLUDES po_pathogens.

Browse[1]> p.layers
 [1] "cc_acid"             "cc_slr"              "cc_sst"              "cc_uv"               "fp_art_hb"           "fp_art_lb"           "fp_com_hb"           "fp_com_lb"          
 [9] "fp_targetharvest"    "hd_destruction_rate" "hd_intertidal"       "hd_subtidal_hb"      "hd_subtidal_sb"      "po_chemicals"        "po_nutrients"        "po_pathogens"       
[17] "po_sedimentation"    "po_trash"            "sp_alien"            "sp_genetic"          "ss_wgi"      

list(region_id=d.p[[1]], pressure=names(d.p)[-1]
+ )
$region_id
 [1]  1  2  3  4  5  6  7  8  9 10 11

$pressure
 [1] "cc_acid"             "cc_slr"              "cc_sst"              "cc_uv"               "fp_art_hb"           "fp_art_lb"           "fp_com_hb"           "fp_com_lb"          
 [9] "fp_targetharvest"    "hd_destruction_rate" "hd_intertidal"       "hd_subtidal_hb"      "hd_subtidal_sb"      "po_chemicals"        "po_nutrients"        "po_sedimentation"   
[17] "po_trash"            "sp_alien"            "sp_genetic"          "ss_wgi"             

image

Double-checking pressures_matrix.csv showed that po_pathogens was indeed there, but on layers.csv, there was a typo and it was entered as po_pathoges. So it was registered properly as a layer but never used–so passed through ohicore::CheckLayers original checking

Also: capital Q quits you from the browser()

10.2.5 Calculating Resilience …

Calculating Resilience...
Note: each goal in resilience_matrix.csv must have at least one resilience field
 Show Traceback

 Rerun with Debug
 Error: all(t %in% resilience_categories) is not TRUE

10.2.6 Working with Rmarkdown files

processing file: eco_prep.rmd
Error in parse_block(g[-1], g[1], params.src) : 
  duplicate label 'extract eco most recent year status'
Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block
Execution halted

11.1.1 GitHub and git

GitHub has an online interface and a desktop application for the version-control software called ** git**, where your project repository and any changes done to it are kept and recorded. It is an open-source development platform that enables easy collaboration and versioning, which means that all saved versions are archived and attributed to each user. It can be accessed remotely by all members of your team and enables team members to synchronize their work together. Because all versions are saved, you can return to previous work and also compare different points in history to track how changes you make affect the output scores.

To allow multiple users to work on the same repository at the same time, there are steps involved to ‘commit’ your modifications so they can merge with the work of others without problems. GitHub has specific words for each of these steps.

GitHub Vocabulary:

• clone ~ download an online repository to your computer to your local machine with syncing capabilities enabled
• commit ~ message associated with your changes at a point in time, before being able to sync back to the online repository
• pull ~ pull changes from an online repository to your computer
• push ~ push committed changes back to the online repository with your version, only possible after committing
• sync = pull + commit + push

TIP: While you can edit files in the online GitHub repository, we do not recommend this. It is good practice to track changes through commits and syncing.

The example below illustrates GitHub’s collaborative workflow:

There are also many great resources available online with more in-depth information:

• Git and GitHub by Hadley Wickham: r-pkgs.had.co.nz/git.html
• Collaboration and Time Travel: Version Control with Git, GitHub and RStudio video tutorial by Hadley Wickham: www.rstudio.com/resources/webinars
• Good Resources for Learning Git and GitHub by GitHub: help.github.com/articles/good-resources-for-learning-git-and-github/

11.1.2 R and RStudio

R and RStudio allow you to work locally on your own computer, modifying the files in the repository to reflect the desired modifications your team has identified for your assessment. All changes within your local repository will be tracked by GitHub regardless of the software you use to make the changes. This means that you can delete or paste files in the Mac Finder or Windows Explorer and edit .csv files in Excel or a text editor, and still sync these changes with the online repository. We recommend doing as much data manipulation as possible in a programming language like R, to maximize transparency and reproducibility.

• R is a free computing and graphical software where all the modifications to your OHI repository are done.

• RStudio is a user-friendly R interface that can be used to synchronize any modifications you make to files in your assessment’s repository. It is where model modifications and calculations occur.

Through RStudio, you can perform all the steps mentioned before (clone, commit, push, and pull) and sync with the online Github repository.

11.1.3 Syncing Github and RStudio

RStudio can sync files with Github directly. It will capture the changes made to any files within the repository, no matter which software was used to modify them. In RStudio, you sync by first pulling and then pushing (separately).

Launch your project in RStudio by double-clicking the .Rproj file in the assessment folder on your local hard drive.

When you modify or add a file, the file will appear in the ‘Git’ window once it has been saved. In the example below, the file test.R was created.

1. Clicking the ‘Staged’ (checked) box and the ‘Commit’ button opens a new window where you can review changes.
2. Type a commit message that is informative to the changes you’ve made.

• Note 1: there will often be multiple files ‘staged’ at the same time, and so the same commit message will be associated with all of the updated files. It is best to commit changes often with informative commit messages.
• Note 2: clicking on a staged file will identify additions and deletions within that file for your review

3. Click ‘Commit’ to commit the changes and the commit message.
4. “Pull” any changes that have been made to the online repository. This is important to ensure there are no conflicts with updating the online repository, especially if you are working with collaborators who might be working on the same files as you are.
5. “Push” your committed changes to the online repository. Your changes are now visible online.

TIP: If you aren’t seeing your changes in the ‘Git’ window, try saving the file again.

Figure showing RStudio when syncing. After first staging your changes, click the ‘commit’ button to open a new window where you can enter a ‘commit message’ and then pull and push new changes.

Note: Another option to syncing your edits on a repo with the online version is to use Command Lines, if you are familiar with it. There are resources available online on how to do so.

11.2.1 Set up a Github Account and git

You can create a GitHub account at http://github.com. Choose a username and password. You will use this username and password when you install and set up git on your computer.

11.2.1.1 Install git software

git is available for download at https://git-scm.com/downloads. How you install git will depend on whether you are working on a Windows or Mac computer. It will also depend on your operating system version. If you have problems following these instructions, it is likely because your operating system requires a previous version of git. Previous versions are available from http://www.wandisco.com/git/download (you will need to provide your email address).

For Windows:

• Download git at http://git-scm.com/downloads and follow the install instructions.

• When running the Windows installer, use all default options except “Adjusting your PATH environment”: instead, select “Run Git from the Windows Command Prompt”. This will allow later compatibility with RStudio.

For Mac:

• Download git at http://git-scm.com/downloads and follow the install instructions.
• Apple’s Xcode has a command line tools option during install which can override the preferred git command line tools. To ensure you are using the latest preferred version of git, you will need to launch Terminal and type the following few lines of code:
• Access Terminal from the Applications folder: Applications > Utilities > Terminal. When you launch Terminal a window will appear with your computer’s name followed by a $. When you type, your commands will appear after the $.

Add access your ‘bash profile’ by typing:

pico ~/.bash_profile

You are now able to edit your ‘bash profile’ and your screen will change; it will look like this:

Now type:

export PATH=/usr/local/git/bin:$PATH

Exit pico by entering:

control-X
y
return/enter

Exit Terminal by typing:

exit

Finally, quit Terminal.

git config --global user.name jdoe

git config --global user.email johndoe@example.com

git config --list

exit

11.2.2 Download R and RStudio

You can download R, and RStudio for free from their perspective websites and install the latest versions allowed by your operating system on your computer:

R: http://cran.r-project.org/

RStudio: https://www.rstudio.com/

R and RStudio update frequently. If you already have those software installed, check on the websites for the most recent version. In general, it’s good practice to check periodically for updates. When you run into unexplained errors while modifying contents in RStudio, check first if your versions of R or RStudio are out-of-date. For R, you can see what you already have on your computer by typing “sessionInfo( )” into your R console.

If you are working on a Mac, you will need to tell RStudio to use the proper version of Git by doing the updating the preferences for ‘Git executable’:

RStudio > Preferences… > Git/SVN > Git executable: /usr/local/git/bin/git

TIP: if you are working on a Mac, the git file is hidden. To find it easily, hold shift+command+g and paste /usr/local/git/bin/git in the pop-up window. Select git (which should be already preselected) and select Open, then Ok.

12.0.1.1 sub-goal: Fisheries

The Fisheries sub-goal describes the amount of wild-caught seafood harvested and its sustainability for human consumption. The model generally compares landings with Maximum Sustainable Yield. A score of 100 means the country or region is harvesting seafood to the ecosystem’s production potential in an sustainable manner.

Practical Guidance

Fisheries science is a discipline that in part aims to estimate the amount of fish that can sustainably be extracted from the sea. For this reason, it is important to consult with fisheries experts in your study area. Fisheries experts will be able to advise how to best estimate the maximum amount of catch that can be sustainably fished, and the information available will determine what type of modeling to take. There are many different modeling approaches, and most are based on either catch alone, or catch-per-unit-effort.

The Ocean Health Index relies on freely accessible, open-source data that is consistently updated over time. Here are two datasets used in the OHI-Global assessments, which could be also be useful for OHI+ assessments: Fisheries catch over time from the Sea Around Us Project (seaaroundus.org) and Global fisheries landings over time from FAO (fao.org/fishery/statistics/en).

If only catch data are available, it is highly recommended to follow the approach in the 2013 global assessment (Halpern et al. 2015) rather than the 2012 global assessment (Halpern et al. 2012). All global assessments use national fisheries catches reported to the Food and Agricultural Organization (FAO), and the 2013 global assessment used the fisheries modeling method for data-poor sources developed by Martell & Froese (2013). With this method, fisheries catch information would be used to calculate the population biomass (B), and its maximum sustainable yield (B_MSY). The reference functional relationship between fisheries catch and effort information would be used to calculate the present biomass against B_MSY would be used to set the reference point. The current status would be calculated using the present state of every individual species and combining each species together as the weighted proportion of the total catch.

You can find data for catch-per-unit effort data, and then create a functional relationship to determine the reference point.

At a global scale, catch, effort, and MSY estimates are not available for either commercial, artisanal or recreational fishing: only landings data for commercial fisheries are available through the United Nations Food and Agriculture program (UN FAO). You will hopefully be able to find more localized data when conducting your assessment.

When collecting data on fish landings, it’s important to consider how you will divide the data among regions. You should try to assess each fish species by its entire population across all regions in your study area. The status in the global assessment model (2013) was calculated based on estimating population biomass relative to the biomass that can deliver maximum sustainable yield for each landed stock (B/B_MSY). This ratio is conventionally used to inform fisheries management. This approach adopts the population biomass at MSY (B_MSY) as a single-species reference point.

If you are replicating models from the global assessment (2013-2015), do not split the catch among regions; instead, you want to sum catch across all regions so you can calculate B/B_MSY for the whole population.

The principle of the reference point should not change. You should be creating models that penalize scores for harvesting above the maximum sustainable yield, as defined in your assessment, and scores that penalize for harvesting below the sustainable yield. The penalties vary for models developed in the global assessments, where overfished species negatively influence scores more than under-fished species do.

It is important to also consider buffering around the reference point (eg. 75% of B_MSY) because of imperfect knowledge about the data. Part of this depends on the type of assumptions you want to make about the ecology of fish species in your area and the impacts upon them from fishing practices. For instance, when all species are exploited simultaneously, fishing pressure on each population might be lower due to changes in interactions between species that occur when a predator population is reduced.

12.0.1.2 Examples of the Approach

12.0.1.3 sub-goal: Mariculture

Mariculture measures the ability to reach the highest levels of seafood gained from farm-raised facilities without damaging the ocean’s ability to provide fish sustainably now and in the future.

Higher scores reflect high food provisioning in a sustainable manner, while not compromising the water quality in the farmed area and not relying on wild populations to feed or replenish the cultivated species. A score of 100 means that a region is sustainably harvesting the greatest amount of farmed seafood possible based on its own potential (where its maximum potential is estimated in different ways depending on the assessment).

Ideal Approach

Ideally, you would find information about the harvest and practices, on the total area available for mariculture. This could be in terms of s physical area or area based on siting priorities. You would also find information on the sustainability of the mariculture practices. This is important because mariculture competes for space with many other ocean uses, including fishing, tourism, and other activities.

This approach would not penalize regions that have less geographic area available for mariculture, though places with fewer sheltered bays or lower primary production could be at a disadvantage.

Culture of marine fish in closed pools on-shore should not be included because onshore aquaculture does not require a marine environment. However, if the aquaculture farms receive seawater supply and return seawater back to the sea, they should be included in the Mariculture sub-goal. Finer-scale, environmental damages due to the intake pipes and the processed brine back into the marine system could be incorporated as a pressure layer as well.

Fish that are used as feed for other fish (e.g., sprat) would be more appropriate to include in Natural Products. This is because they are not being consumed directly. Fish such as sprat, for example, may be used to feed pigs in addition to other fish, and therefore you would need to know how much (tonnage) is being produced, and where it is going to be able to accurately distinguish these categories to avoid double-counting.

Practical Guidance

Besides harvest information, either by species or total amount, this goal requires spatial information. You would have to find maps determining where coastal activities are allowed, or find other kind of data that tells you the usage restrictions for activities in your waters. For example, you can look for assessments that have been made to identify the coastal and offshore habitats that are appropriate for each intended type of mariculture species.

The 2012 Global Assessment included the entire area of the coastline assuming that mariculture could be developed everywhere. This was done because there was no information about limitations for how much coastal area could be allotted to mariculture.

The reference point will depend on your context. You should try to account for the full potential extent of mariculture in your marine areas. This could be based on a number of variables such as the habitat suitability for each cultured species, the distance from the coast, information on how local preferences favor the allotment of marine space to mariculture versus sports, hotels, beaches, tourism, or other uses. This definition of mariculture potential therefore can be physical or social. Keep in mind that in the Global approach, a low score can indicate one of two things – that species are being farmed in an unsustainable manner or that regions are not maximizing the potential to farm in their marine territorial waters.

It is important to think about the meaning of your reference point. The spatial reference point in the Global approach assumes that because one country is able to produce such a high proportion of mariculture to its coastal area, all regions should be able to as well, given current ecological and technological conditions. This also assumes that it is socially desirable for all regions to produce farmed species at this level, which is likely not true for all regions. The Global approach compared observed production density of all areas to the highest observed production density after the sustainability coefficient was applied.

There was a significant change between Global 2012 and Global 2013 to improve the reference point for this sub-goal. The coastal population was factored in to the reference point in 2013, where the harvested tonnes per inhabitants within 25 km of the shore was considered. This change was done under the assumption that production depends on the presence of coastal communities who can provide the labor force, infrastructures, and economic demand to support the development and economic viability of mariculture facilities. Thus, two regions with an equal number of coastal inhabitants harvesting an equal tonnage of cultured seafood should score the same, even if one is larger than the other, as the productivity is commensurate to each region’s socio-economic potential to develop mariculture. This is an example of how improvements in methods occur over time.

12.0.6.1 Sub-goal: Iconic Species

Iconic species are those that are relevant to local cultural identity through a species’ relationship to one or more of the following: 1) traditional activities such as fishing, hunting or commerce; 2) local ethnic or religious practices; 3) existence value; and 4) locally-recognized aesthetic value (e.g., touristic attractions/common subjects for art such as whales). Habitat-forming species are not included in this definition of iconic species, nor are species that are harvested solely for economic or utilitarian purposes (even though they may be iconic to a sector or individual). This sub-goal assesses how well those species are conserved.

Data for this goal will likely have considerable overlap with Biodiversity sub-goal: Species. It will be effective for the goal keepers of Biodiversity and Sense of Place to share the data searching efforts.

Ideal Approach

Ideally, you would have a list of species that are valued as iconic and information on their habitat ranges along with scientific studies that speak to the health of their populations. A reference point is where all iconic species are at a healthy level of existence.

Practical Guidance

First you need to identify the Iconic Species. In practice, Iconic Species are usually a subset of the broader list of species in an area, and so you should be able to find Iconic Species after having found assessed species data for the Species sub-goal of the Biodiversity goal. (See Biodiversity for more detailed instructions.) Once you have the full list of assessed species, you can determine a subset for Iconic Species. For instance, are there known “indicator species” in your area? Are there species that are culturally held as valuable? Do any species appear on the currency or postage stamps?

Since different species are be iconic to different groups, defining which species are iconic can be challenging when it’s a cultural question. You might have to find information from experts on local customs and tradition.

The choice of inclusion of iconic species in your list can be subjective. You could also come up with specific inclusion criteria, for instance, that would filter a list of species or filter a subset of the gathered data for Biodiversity. This would be a more rigorous approach because then it could be documented and you could replicate the study in future assessments.

Ultimately, almost any species can be iconic to someone, and so the intent with this goal was to focus on those species widely seen as iconic within a country, and iconic from a cultural or existence value (rather than for a livelihoods or extractive reason). Many lists exist for globally important, threatened, endemic, etc. species, but in all cases it is not clear if or to what extent these species represent culturally iconic species. In the global assessment, species were drawn from the World Wildlife Fund’s global and regional lists for Priority Species (especially important to people for their health, livelihoods, and/or culture) and Flagship Species (‘charismatic’ and/or well-known). These lists are note the only source that included cultural reasons for listing iconic species and you should try to acquire more information on locally relevant species.

After identifying the list of iconic species, you need to find a matrix to reflect the health of their population. In the global study, we used IUCN threat categories and weights. The reference point is to have the risk status of all assessed species as Least Concern. Alternatively, you can use a different kind of assessment approach to see if the populations are healthy, which could be indicated, for instance, by the stability of their populations.

Examples of the Approach

12.0.6.2 Sub-goal: Lasting Special Places

This sub-goal focuses on those geographic locations that hold particular value for aesthetic, spiritual, cultural, recreational or existence reasons, and assesses how well they are protected.

This sub-goal makes use of protected areas, and some of the same information gathered on projected areas can be used to create resilience data layers like Marine Protected Areas.

Ideal Approach

Ideally, you would be able to survey everyone in your region and produce a list of all the places they consider special, and then assess how well they are protected relative to a desired state. How well they are protected could be the percentage of area protected, and you could also find how well they are protected using other data. This sub-goal could also be based on the extent to which people participate in spiritual or religious activities in an area.

Practical Guidance

The ideal list of special places don’t exist in practice, and this is a difficult goal to express accurately, since it attempts to capture how people interact culturally with their coastal places. You can define “special” with specific criteria. A good example to look at is the U.S. West Coast assessment (2014) and Brazil Assessment (2014).

More likely, you would follow the global assessment and use lists of protected areas as catalogues of special places, and the area of designated protected places relative to a reference point (eg. of thirty percent coastal area protected) is used as a measure. Coastal area could be based off a 1 square km buffer inland, as in the Global Assessment, or it could be based on what is reasonable to your area. In any case, you would want to consider how far out from shore you should include as well; would it be 3 nautical miles, or as far as your territorial waters up to 12 nautical miles?

Data sources should be specific to your region. International databases, like the World Database of Protected Areas (www.protectedplanet.net/), offer rich information, but they may not be as up-to-date as the list of national parks in your area, and may not have as much information on the quality of protection. If you have more information on quality, you could think about another approach than the thirty percent reference point target.

Global assessment incorporated both marine and terrestrial protected areas. However, if only data on marine protected areas is available, you can calculate only the marine component of the goal. This is not ideal but OHI is flexible to work with the data available.

If you assessment involves multiple categories (e.g., antiquities, MPAs, beaches of special interest), whether you group them together or calculate each category separately depends on reference points. Maybe you want 10% of offshore water to be in MPAs, but only 5% of coastlines to be beaches and 3% Antiquities, for example; in this case, you would calculate them separately and then add them together. But if you want 10% of your country’s coast to have any combination of these things, you would keep them together.

In the Global Assessment framework, the Sense of Place sub-goals were weighted equally and combined in an average to create a single goal score. The two sub-goals are averaged currently in the framework. But these could be combined with a weighted average.

Examples of the Approach

12.0.7.1 Sub-goal: Livelihoods

This sub-goal describes livelihood quantity and quality for people living on the coast. Livelihoods includes two equally important sub-components, the number of jobs, which is a proxy for livelihood quantity, and the per capita average annual wages, which is a proxy for job quality.

Ideal Approach

Ideally, this sub-goal would speak to the quality and quantity of marine jobs in an area. It would encompass all the marine sectors that supply jobs and wages to coastal communities, incorporating information on the sustainability of different sectors while also telling about the working conditions and job satisfaction. The jobs and revenue produced from marine-related industries directly benefit those who are employed, and also those who gain indirect value from related economic and social impacts of a stable coastal economy, such as community identity and tax revenue. You should capture the indirect as well as direct benefits from jobs, wages and revenue from coastal communities.

In your assessment, there is the opportunity to study the behavior of economic trends in your area. You can examine time-series with greater detail and, for example, establish a different time-periods that reflect economic cycles in your area, or even process the data to eliminate the “noise” from fluctuations and capture more persistent trends.

You will most likely simplify the models from the global assessments. Models in the global assessments adjust for currency differences using the the Consumer Price Index and Purchasing Power Parity, which you likely will not need to do.

Practical Guidance

The first step of this goal is to identify the marine-related sectors in your area. These sectors are important because the Livelihoods goal includes information about jobs and wages for those sectors. There are jobs that are directly connected to the marine environment, such as shipping, fishing, longshore workers, but also some that are connected indirectly, such as suppliers and supporting industries. For example, the sectors for which data were found in global assessments included tourism, commercial fishing, marine mammal watching, aquarium fishing, water and tidal energy jobs, mariculture, transportation and shipping, ports and harbors, ship and boatbuilding.

After you have identified which jobs are in your area, you will want to find some measure of their direct and indirect benefits. Direct benefits of jobs include the number of jobs in each area, and the wages or income for such jobs. You could find such information from you local national statistical office, or economics bureaus, for example. Indirect benefits of these jobs to the local communities are calculated through the use of economic multipliers, with which you can attempt to estimate the revenue generated by jobs more broadly associated with marine sectors. It’s encouraged to use economic multipliers from the literature.

One example to use economic multipliers is to multiply the number of fishermen by a multiplier to estimate larger economic effects, ranging from gear manufacturing companies to restaurants and movie theaters where the fishermen spend their income.

Next you must think about how to use the data to infer quality and quantity of jobs. Do you have data through time so that you can see how the number of jobs or the wages per sector have changed over time? If all of the sectors change in the same way, for instance, this might show broader economic trends that you should account for.

It is highly recommended that you set the reference point for jobs as a temporal comparison (eg. the number of jobs five years before), and for for wages as a spatial comparison (eg. highest observed value across reporting units). Comparing the number of jobs across different places, for instance, would require at the very least adjusting values by the size of the workforce in each location.

Examples of the Approaches

12.0.7.2 Sub-goal: Economies

Economies captures the economic value associated with marine industries using revenue from marine sectors. It is composed of a single component, revenue.

Ideal Approach

Ideally, revenue data would be collected for all coastal regions, and traced from sectors both directly and indirectly related to marine industries. When these data are not available it is possible to use revenue data at a larger scale and adapt them to a coastal area based on the population distribution. The reference point in this sub-goal will likely be set with a moving-window temporal approach.

Practical Guidance

A number of sectors were not included in the Global Assessments because sufficient data did not exist. However, it might be desirable to include sectors such as ecotourism, sailing, kayaking, surfing, and offshore wind energy production, and scientific research, among others. It may be practical to include the same sectors in the Livelihoods and the Economies subgoals.

The quantity of Wild-caught fisheries, Mariculture, and participation of Tourism & Recreation are considered separately in specific goals, whereas the monetary component is captured in L&E.

In the global assessment, revenue has a moving-target temporal reference point by comparing the value in the current year to values in previous years. Global assessments used a five-year moving-window because it is intended to capture short-term changes in the trajectory. But then you must consider if that amount of time would represent economic trends. If there is a not economic downturn, do you want to reward an increasing number of jobs, or reward maintaining the same number of jobs?

We highly recommend that this remains a temporal comparison so that a specific place is compared to its performance in the past and not to anywhere else.

You may find resilience metrics that can be used throughout your assessment. There are many economic indices and some might be appropriate for your area. For example, the Global Competitiveness Index was used in global assessments as a resilience for this goal because it means that marine jobs are more likely to be maintained if an area gets a good score on the Competitiveness Index.

Examples of the Approaches

12.0.10.1 Sub-goal: Species

This sub-goal assesses the health of all marine species present in a region, including endangered species and species in relatively good conditions. The presence of higher-risk species leads to a higher score.

Data for this goal are also used in Sense of Places sub-goal: Iconic Species. It will be effective for goal keepers of Biodiversity and Sense of Place to work together on data gathering.

Ideal Approach

Ideally, you would find data for all species present in your region including information on their habitat ranges along with scientific studies that speak to the health of their populations.

Practical Guidance

You should start by trying to find spatial information for species that occur in your area and determine whether or not they have been scientifically assessed and given a conservation status. It is best if you only use species for which there are both spatial data and an assessment. In the global assessment, we combined data from recent assessment the International Union for the Conservation of Nature (IUCN) (www.iucnredlist.org/technical-documents/spatial-data) and AquaMaps (aquamaps.org). These data sets provide a geographic snapshot of how total marine biodiversity is faring, even though it is a very small sub-sample of overall species diversity.

IUCN provides global species assessments that indicate the distribution and the conservation status of species, ranging from Least Concern to Critically Endangered to Extinct. These risk categories were turned into these into weights (between 0 and 1) for calculations. AquaMaps offers additional spatial data for species not covered by the IUCN distribution maps. Both evaluations chooses a taxon (e.g. sharks) and a group of world experts assess it comprehensively. Locally identified species identified in a regional assessment may not be in the global database because they do not belong to one of the taxa that have been selected for assessment, or because the experts that did the assessment did not know that information existed. In either case, there is no connection between what IUCN or AquaMaps report and what assessments are done locally. Therefore, it might not be fair to penalize a study area for missing species. For biodiversity, it is unrealistic to expect that all species are assessed, so it seems unfair to penalize for un-assessed species. In the fisheries goal, there are penalties for species that are exploited but not assessed, because if there are landings data, it means they are somewhat measurable, and so it is reasonable to expect they should be at least monitored.

For regional assessments, local studies of marine species status and local datasets are best here. The spatial information can be a range map with simple presence or absence information, or it can have more detailed data. You can complement the species list search with a scientific literature search to see if anyone has scored the species status in a way that you can use. One thing to keep in mind when using local data sets is that local lists might focus on endangered species and leave species in relatively good conditions un-assessed. This could result in poorer scores.

If spatial distribution information for individual species is not available, the goal model could be simplified to be based on threat-status-weighted average in your region.

You should also think about the reference point for scores that signal poor Biodiversity status. You can use the same threshold as the Global Assessments which say that places with extinction risk scores greater than seventy-five percent will get scores of zero. This is an estimation based on the literature of mass extinctions (e.g., Barnosky et al., 2011) and could be applied across scales. You don’t need all species extinct for there to be a zero, so you will have to choose how to rescale it, and whether the risk effects are linear or nonlinear.

Additional Note: Defining spatial regions and map considerations

Once you have gathered the data, the treatment of it will matter for the model and goal score calculation. Do you know how the data were collected? Do you have information on sampling effort? If you don’t know, you may not be sure whether changes in condition are due to monitoring efforts or biodiversity change, and you therefore may want to consider the uncertainty of your model.

In any case, the original logic of the Species sub-goal of the Biodiversity goal is to represent the species present relative to the proportion of their range within a given region. The goal is to summarize extinction risk for an area across assessed species, and assign it appropriately so that the loss of species scores poorly. You should consider whether the impacts to local species status are linear or non-linear. Will drawing borders affect how your scores are assigned?

When considering how to change the model, you should think about the outcome of the score on your decisions. For instance, will weighting a “Critically Endangered” species higher on the scale result in the inclusion or exclusion of more rare species? Will the way you aggregate spatial data to summarize extinction risk for your area take into account the influence of species with smaller ranges size, or will that information be lost in the averaging process? An inherent disadvantage for conservation may occur when rare species get rarer in the future, and will therefore have a relatively small influence on the score while common species drive the results.

Range size has an impact on score results. For example, if you use the current model, none of the cone snail species listed below will have a big impact on the Species sub-goal score because to their small range size that covers one cell of map area. However, the 0.8 score for Conus roeckeli shows that it is a rare species as assessed by the IUCN. On the other hand, the coral Acropora palmata is also rare and yet covers a large range.

Examples of the Approach

12.0.10.2 Sub-goal: Habitats

The Habitats sub-goal includes all habitats in the study area, and assess their health condition and coverage area.

Habitat is included in the Biodiversity goal to provide a more complete picture of diversity in the system. This is because in global assessments assessed species data were limited and the diversity of habitats can be included with the assumption that healthier habitats mean healthier species. Therefore if you have comprehensive species assessments in your area you may not need to include all habitats as a sub-goal, instead only including living habitats (algae, corals) along with species in the Species sub-goal.

Ideal Approach

Ideally, information on the area extent (square kilometers) and condition of every habitat type would be available over a long period of time.

Practical Guidance

You will first find what habitats are in your study area, both in the coastal regions and offshore. In the global assessments, data were available for mangroves, coral reefs, seagrass beds, salt marshes, sea ice, or subtidal soft-bottom habitats, but there are likely other important habitats in your region.

Once you determine what habitats are in your area, you will need information about the area extent of each habitat within each region of your study area. You should consider whether and how far they go offshore and inland. Spatial data are preferred: you will be able to calculate the total square kilometers of each habitat within each region. For example, in global assessments mangrove area within 1 kilometer of the coastline were included, but this distance could change in OHI+ assessments.

You will need to include area and condition data specific to your study area and not rely on the global data provided. This is because the habitat data provided for your assessment are either over-representative by allocating the study area’s data equally to each subcountry region, or can be misrepresentative by allocating a proportion of those data to each subcountry region (based on the offshore area of each region to the total area). Either case assumes that if a habitat was present in the country, it could be found anywhere (which is not the case with study areas that span many degrees of latitude), and the first case inflates the habitat coverage in the study area.

TIP 1: Do you have maps that show current habitat distributions and maps that show historical habitat distributions? If so, you could extract that data for each of your regions to get a current and reference area. In the U.S. West Coast assessment (2014), researchers went to the local public library to find hand-drawn maps of historical salt marsh and sand dune extents in California. You could also use summarized habitat data that exists in tables or are already compiled in another source.

TIP 2: If local data is not available, you obtain certain habitat extent data from the global assessment, which used high resolution spatial extend data from this study: Hamilton, S. & Casey, D. (2014). Creation of a high spatiotemporal resolution global database of continuous mangrove forest cover for the 21st Century (CGMFC-21): a big-data fusion approach. arXiv:1412.0722. Good data to obtain from this study include shoreline, mangrove, soft bottom, and sea ice.

The condition of the habitats can be measured in different ways, depending on the data available. Indicators of condition could include habitat density, susceptibility to pathogens, or change in species composition or growth rates from impacts such as overgrazing. Look for studies assessing habitat integrity or condition specifically in your area.

In global assessments, direct information about coral condition was not available so it was based on the percentage of “living cover” on a coral reef relative to the potential range of the reef. In other words, estimates of coral cover within transects of certain sites were repeated in time and we used that rate of change in time as an indication of health of the reefs in the whole region. The difficulty lies in 1) having enough different locations sampled that you can say something about the whole region and 2) finding studies that did repeated measures in time, in the same location, over at least 20 years. In the Global 2013 assessment, there were so few datasets that satisfied this condition that we had to pool observations from different locations. Mean predicted values for each region from 1985-1987 were set as reference points.

If possible, you will want to gather habitat area and condition data through time so that you can calculate the trend. Ideally, there will be enough years of data to directly calculate the recent change in habitat condition as the trend. This isn’t always the case, and proxies or estimates might need to be used. For example, due to spotty salt marsh data we created trend categories of increasing (0.5), stable (0), and decreasing (-0.5) based on available data.

The reference point will likely be based on historic habitat area coverage and condition, with the assumption that habitat destruction has been and still is occurring and the target is to return to some point in the past. You will need historical data for this, from satellites, published papers, or even hand-drawn maps. The challenge is to find a reference point that is both ambitious and realistic (based on the S.M.A.R.T. principles: see Conceptual Guide), using the data available. If data allow, it will be possible to set a reference point that is more ambitious than that used in global assessments.

Alternatively, the reference point could be guided by a policy target. For example, are there any climate change policies in your area, with defined targets and objectives? Are there any restoration or carbon storage projects in your area? Do any organizations offer guidance on the amount of carbon storage your management policies should be aiming for?

Examples of the Approaches

13.0.2.1 tidyr::gather()

Description

gather() takes data organized in rows and collapses them into a column format (a key column and a value column), duplicating all other columns as needed. Use gather() when your data is organized in “wide” format, in which some of your variables are in row form, rather than column form. Another tidyr function, spread(), is more or less the reverse of gather(), to reformat long data into wide data. It is more difficult to work with wide data, but may be more convenient for examining data in a table format.

Note: gather() essentially replaces melt() in plyr package.

Example

The sample data set (see intro) contains harvest data of a number of marine commodities, separated by country, commodity, and year. In its original form, the harvest data (in tonnes) is spread across five different harvest years. * Counter to ‘tidy data’ principles, we have multiple columns (X2007:X2011) representing a single variable (year), and multiple observations of harvest tonnage in each row. * To transform this into ‘tidy data’ we will gather the five annual harvests into a single column called ‘tonnes’ and note the year of harvest in a new column called ‘year’.

The example in the figure below shows how the original wide data is transformed into long data using the command gather. Here are two ways of acheiving this:

1. Here, information from columns X2007 through X2011 are gathered into a single column called year, and the information in each column are put into a new column called tonnes.

data_long <- data_wide %>% gather(year, tonnes, X2007:X2011)

2. Here, the - unselects the named columns, so they will not be gathered; all other columns are gathered into columns named year and tonnes. This approach will yield the same result.

data_long <- data_wide %>% gather(year, tonnes, -Country, -Commodity, -Trade)

wide data to long data using gather() and spread()

13.0.3.1 %>% operator

Description

The %>% operator allows you to ‘pipe’ or ‘chain’ a number of function calls, in which the output dataframe of one function is fed directly into the next function as the input dataframe. This lets you avoid creating temporary variables to store intermediate values, and lets you avoid nesting multiple functions. Using %>% makes your code more elegant, streamlined, and easy to read since you are able to write your code on multiple indented lines. From dplyr and pipes: the basics:

OK, here’s where it gets cool. We can chain dplyr functions in succession. This lets us write data manipulation steps in the order we think of them and avoid creating temporary variables in the middle to capture the output. This works because the output from every dplyr function is a data frame and the first argument of every dplyr function is a data frame.

Usage

data_out <- f(data_in, args)
  # standard function call

data_out <- data_in %>% f(args)
  # function call using %>% operator. data_in is passed as first argument
  # of function().

data_out <- data_in %>%
  f1(args1) %>%
  f2(args2) %>%
  f3(args3) %>% ...
  # Output of function can be passed to another function immediately,
  # without need for temporary storage. Indented format for legibility,
  # see how pretty it looks?

Example

### Bad!  Nested functions: read from inside out - hard to decipher
  h_recent_totals1 <- arrange(mutate(filter(group_by(harvest, country, commodity),
    year >= 2009), harvest_tot = sum(tonnes, na.rm = TRUE)), country, commodity)

### Better: Line by line. Easier to read, but have to wait for the end to see
### what it does.  Temp variables add more places for errors and bugs.
  h_temp <- group_by(harvest, country, commodity)
  h_temp <- filter(h_temp, year >= 2009)
  h_temp <- mutate(h_temp, harvest_tot = sum(tonnes, na.rm = TRUE))
  h_recent_totals2 <- arrange(h_temp, country, commodity)

### Best!  Chained format intuitively links together the functions. Saves
### typing, fewer opportunities for errors, easier to debug. The %>% operator
### automatically indents each following line for easy reading.
  h_recent_totals3 <- harvest %>%
    group_by(country, commodity) %>%
    filter(year >= 2009) %>%
    mutate(harvest_tot = sum(tonnes, na.rm = TRUE)) %>%
    arrange(country, commodity)

13.0.3.2 dplyr::select()

Description

select() allows you to choose specific columns/variables from your dataset, and drop all others. Alternately, you can select specific variables to drop, leaving others in place. rename() is a relative of select() that allows you to rename variables, while leaving all variables in place.

Examples

The sample dataset includes the annual harvest, in tonnes, of a number of commodities exported by two countries. Type of trade provides no information (it is all Export), so that variable can be dropped. The names of all the variables should be converted to lower-case, to match the OHI style guide. See the figure below.

### Example 1:
harvest <- harvest %>%
  select(Country, Commodity, year, tonnes)
  ### Selects the named variables, and drops all others.  Useful to choose a
  ### subset of key variables from a complicated data set.

### Example 2 (same result as example 1):
harvest <- harvest %>%
  select(-Trade)
  ### Using the '-' drops 'Trade' column and leaves other variables intact.
  ### Useful if you would like to clear out temporary variables.

harvest <- harvest %>%
  rename(country = Country, commodity = Commodity)
  ### Drops no variables. Syntax: rename(new_var_name = old_var_name) w/o quotes.

Using the chain operator, we can string these two functions into one smooth, easy-to-read flow:

harvest1 <- harvest %>%
  select(-Trade) %>%
  rename(country = Country, commodity = Commodity)

The harvest data is fed into select(), and the output is fed into rename(). The final output of this complete flow is assigned to the new variable harvest1.

13.0.3.3 dplyr::filter()

Description

filter() allows you to select observations (rows) that match search criteria, using values in specified variables (columns). Drops all observations that do not match the criteria. * Use logical operators & and | to filter on multiple criteria simultaneously

Example

harvest_vnm  <- harvest %>%
  filter(country == 'Vietnam')
  ### Single criterion filter: keeps only data with country matching 'Vietnam'.

h_vnm_recent <- harvest %>%
  filter(country == 'Vietnam' & year >= 2009)
  ### filter with multiple criteria: selects 'Vietnam' data from 2009 or later.

13.0.3.4 dplyr::arrange()

Description

arrange() sorts observations (rows) based upon a specified variable or list of variables. Does not actually change the data in any way, only the appearance. Useful for inspecting your data after each processing step.

Example

harvest_sorted <- harvest %>%
  arrange(country, commodity, year)
  ### Sorts commodity harvest values for each country, chronologically

harvest_sorted <- harvest %>%
  arrange(country, commodity, desc(year))
  ### Sorts harvest values by most recent year (descending order)

13.0.3.5 dplyr::mutate()

Description

mutate() is a powerful and useful tool for processing data. You can add new variables or modify existing variables, using all variety of functions to perform operations on the dataset. mutate() works well with group_by() to perform calculations and analysis at a group level rather than dataset level.

Example

From the sample data set (see figure below), we would like to:

• Remove the ‘X’ from the ‘year’ values.
• Translate the text codes in ‘tonnes’ into numbers and NAs. These codes are specific to FAO’s data reporting format: ... is the same as NA, and 0 0 means greater than zero, but less than half a tonne.
• Convert these text fields into numeric fields so they can be analyzed properly.

Using mutate to alter data in a dataframe

library(stringr)   ### to access 'str_replace()' string functions

harvest1 <- harvest %>%
  mutate(  
    year   = str_replace(year,   fixed('X'),    ''),  # remove the 'X'
    tonnes = str_replace(tonnes, fixed('...'),  NA),  # replace '...' with 'NA'
    tonnes = str_replace(tonnes, fixed('0 0'), 0.1),  # replace '0 0' with '0.1'
    tonnes = ifelse(tonnes =='', NA, tonnes)) %>%
  mutate(
    tonnes = as.numeric(as.character(tonnes)),
    year   = as.integer(as.character(year)))

Notes: * In this example, no new variables were added. Multiple variables can be changed with one call to mutate(). Multiple modifications to ‘tonnes’ happen sequentially, so order is important. * The as.numeric(as.character(...)) gets around the fact that these text variables are stored as ‘factor’ class, rather than ‘character’ class. as.character() forces them into character class, and then the as.numeric() can convert the character strings to numeric where applicable. Similar for as.integer(...)

13.0.3.6 dplyr::summarize() ( or summarise() )

Description

summarize() combines multiple values of a variable into a single summary value. summarize() works well with group_by() - for grouped data, each group will be summarized and reported separately. For ungrouped data, the summary covers the entire dataset.

• summarize() compresses the dataset and drops individual observations. To maintain individual observations, consider creating a summary variable using mutate() instead.
• NA values can be problematic - use na.rm=TRUE or similar methods.

Example

To determine the total harvest of each country, for each commodity:

h_summary <- harvest %>%
  group_by(country, commodity) %>%
  summarize(harvest_tot = sum(tonnes, na.rm = TRUE)) %>%
  ungroup()

13.0.3.7 dplyr::group_by()

Description

group_by() allows you to easily group a dataset by one or more variables/columns.
By itself, it does nothing to change your data. But once your dataset has been sorted into useful groups, other dplyr functions will operate on each group separately, rather than operating on the entire dataset. * The function groups(data) reports back the current grouping status of dataframe data.

• group_by() alters the grouping, but does not alter the sort order.
  arrange() does not alter the current grouping - it will sort by groups first, then sorts within each group.
• Multiple calls to group_by() will reset the groupings each time (by default), rather than adding additional layers of groups.
• Once you have finished with your operation at the group level, it is a good practice to use the ungroup() function to remove the groupings, to avoid unintended consequences due to forgotten group_by() calls.

Example

If you want to find the total tonnage harvested for each commodity for each country, you would want to group by country and by commodity, and then perform a sum() function on the grouped data. Two options presented here: summarize() to collapse data to just the summary, and mutate() to add a new column that includes the summary values.

h_tot_sum <- harvest %>%
  group_by(country, commodity) %>%
  summarize(harvest_tot = sum(tonnes, na.rm = TRUE))
    ### Summarize information by collapsing each group to a single summary value
    ### (total tonnage by commodity by country). Note ungroup() at end.

h_tot_mut <- harvest %>%
  group_by(country, commodity) %>%
  mutate(harvest_tot = sum(tonnes, na.rm = TRUE)) %>%
  arrange(country, commodity) %>%
  ungroup()
    ### Summarize information by creating a new variable to contain summary
    ### value; report value for every observation. Note ungroup() at end.

group_by to find group-level information

13.0.4.1 Best practices for coding in OHI assessments:

• use a consistent format for variable names, filenames, function names, etc.
  • lower_case_with_underscores (preferred) or camelCase (ok I suppose)
    • not periods.in.between
  • use names that are brief but intuitive
• Comment clearly for your own purposes, and for others.
  • Comment on the purpose of each important block of code.
  • Comment on the reasoning behind any unusual lines of code, for example an odd function call that gets around a problem.
• Take advantage of R Studio section labels functionality:
  • If a comment line ends with four or more -, =, or # signs, R Studio recognizes it as a new section.
  • Text within the comment becomes the section name, accessible in the drop-down menu in the bottom left of the RStudio script window.
• use <- to assign values to variables (not necessary, but preferred)
• use %>% to create intuitive chains of related functions
  • one function per line
  • break long function calls into separate lines (e.g. multiple mutated variables)
• use proper spacing and formatting for legibility
  • don’t crowd the code - use spaces between math operators and after commas
  • use indents to indicate nested or sequential/chained code
  • break sequences or long function calls into separate lines logically - e.g. one function call per line
• use functions to add intuitive names to chunks of code
• Use ‘tidy data’ practices - take advantage of tidyr, dplyr
  • clean up unused columns using select(-colname)
• if you are working on an older script, spend a few extra minutes to update it according to these best practices
  • technical debt - you can do it quickly or you can do it right. Time saved now may cost you or someone else more time later.

13.0.4.2 Writing functions

http://nicercode.github.io/guides/functions/ Why write functions? * name a chunk of code for easier reading * easily reuse a chunk of code

What makes a good function: * It’s short * Performs a single operation * Uses intuitive names

13.0.4.3 Directories and files

* Store files in a folder called 'github' in your home directory; access it with `~/github` so that users with different operating systems can work smoothly with your files