Create a new project

The easiest way to start working with litteR is to create an empty project directory. This directory can be filled with example and reference files by running:

create_litter_project("d:/work/litter-projects/beach-litter")

in the RStudio-console. For more information on how to obtain and use RStudio, consult its website or read our installation guide.

The argument of function create_litter_project (i.e., the quoted part in parentheses) is an existing work directory on your computer. This can be any valid directory name with sufficient user privileges. Note for MS-Windows users: R requires forward slashes!

It is also possible to run create_litter_project() without an argument. In that case, a simple graphical user interface pops up for interactive directory selection.

Perform litter analysis

litteR can be started typing litter() in the RStudio console (see the figure below).

After entering litter(), a simple graphical user interface pops up for file selection. An example of a file selection dialogue is given below.

Type file

The type file contains a list of all litter types that are allowed to use in the data file. It also indicates to which litter group each litter type belongs. Two example files, named ‘types-ospar-materials.csv’ and ‘types-ospar-sup-fish-other.csv’ are automatically generated when using the create_litter_project-function, a described earlier in this tutorial. A type file assigns each litter type (type_name) to one or more litter groups. The first 10 rows of ’types-ospar-sup-fish-other.csv are given in the table below.

Warning: The following named parsers don't match the column names: PLASTIC

The following columns are in this table:

• type_name. This column is required and gives all litter types that are allowed in the data file. Litter types given in this column need to be unique;
• included: This column indicates whether a type specified in column type_name will be used in the analysis or not. Only type_names that are included in the analysis will contribute to the total litter count (TC).
• SUP, FISH, PLASTIC, etc.: these columns give the definition of each litter group. In the example above three groups are given: ‘single use plastics’ (SUP), ‘fisheries related litter’ (FISH), and ‘plastics’ (PLASTIC). A cross (x) indicates that a litter type in type_name is a member of a litter group or not. A cross (x) means ‘a member’, an empty cell means ‘not a member’.

The user may use one of the provided type files as a template for his own type file. litteR will use the type file that has been specified in the settings-file.

litteR performs regional aggregation at the group level. In order to perform regional aggregation at the type level (the columns in the data file), a group with only one or a few litter types of interest can be constructed in the type file, and then regionally aggregated by running litteR.

Data file

litteR supports a simple and flexible data format. It is similar to the OSPAR-format. The data are stored in so called wide format: each row refers to a single survey, each column to a single litter type or metadata. The table below gives an example of a small part (i.e., the upper left corner) of a data file.

The columns location_code and date are always required and define unique records (rows) with litter survey data for a specific date and location (e.g., a specific beach, or a location along a river). litteR will use these data to estimate statistics (as the median and trend) for each location_code.

Column location_code may contain location codes (as in the example above), but also full names like ‘Bergen’, ‘Noordwijk’, and ‘La Grève des Courses’. Full names may be more clear when interpreting the results.

The date column gives the monitoring date in ISO format, i.e., YYYY-mm-dd (for example 2024-12-12, to indicate 12 December 2024). For convenience, the OSPAR-format (dd/mm/YYYY) is currently also supported (for example 12/12/2024, to indicate 12 December 2024).

Columns Plastic: Yokes [1], Plastic: Bags [2], … contain the counts for specific litter types. Each litter type (column name) should be listed in the litter type file. Only litter types in the litter type file are valid column names. All column names that are not valid litter types are considered as optional metadata. These columns are ignored by litteR and do not affect the results.

There is one exception: the column region_code is optional and should be available when the locations (in column location_code) also need to be spatially aggregated. Each region_code is related to one or more location_code(s) that are part of that region.

In the data file below, one region_code (NL) is provided for all locations in location_code. Therefore, litteR will spatially aggregate the results for all locations (NL001 … NL004) within the specified region (NL).

A data file can be constructed easily from existing litter files. As an example consider the OSPAR-format below:

One can simply rename existing columns to the names required by litteR. This can be done with a spreadsheet program or a text editor. For instance, renaming Beach ID, Country and Survey date to respectively location_code, region_code, and date gives the following valid litteR format:

Column Beach name is not recognized by litteR, and is therefore ignored.

As an alternative, one may also add new columns with valid litteR names to the data file and fill them with the contents of existing columns. See the example below:

This can be done quite easily with a spreadsheet program. The original columns of the OSPAR-format (Beach ID, Beach name, Country, and Survey date) are ignored by litteR.

It is advised to use region_codes and location_codes that are easily recognized by the user. For instance, in the example above, location_code ‘Bergen’ is easier to interpret than location_code ‘NL001’. Obviously, this choice does not affect the litteR-results.

Settings file

The settings file contains all settings needed to run litteR. An example of the contents of a settings file is given in the figure below:

# litteR settings file

# Period to analyse (YYYY-mm-dd)
date_min: 2012-01-01
date_max: 2017-12-31

# Percentage of total count to analyse (0 < percentage_total_count <= 100)
percentage_total_count: 80

# Data file.
# Note: the datafile must be in the same path as the settings file
# Note: the file extension should be .csv
file_data: beach-litter-nl-2012-2017.csv

# Type file. Defines the types and their groups
file_types: types-ospar-materials.csv

# Select trend figures to plot in the report
# Note: this can be zero, one, or more than one location_code, region_code,
# group_code, and/or type_name
location_code: ["NL001", "NL004"]
region_code: ["NL"]
group_code: ["TC", "SUP", "FISH"]
type_name: ["Plastic: Bags [2]"]

# figure quality (high or low)
figure_quality: high

# cutoff value vertical axis with litter counts (percentage)
cutoff_count_axis: 100

The settings-file contains the following entries:

• date_min and date_max, the first and final date of the period to analyze. Dates should be given in ISO format, i.e., YYYY-mm-dd (for example 2024-12-12, to indicate 12 December 2024);
• percentage_total_count: the percentage of the total count used to estimate statistics. See the section on descriptive statistics for more information;
• file_data: name of the data file (including its path, e.g., c:/my-litter-directory/my-litter-data.csv);
• file_types: name of the type file (including its path, e.g., c:/my-litter-directory/types-ospar-materials.csv);
• location_code: name(s) of the location(s) to plot. These should exist in column location_code in the data file. As mentioned in the previous section,location_codes should be readily interpretable for the user, as these codes are also used in the litteR-results (tables and plots);
• region_code: name(s) of the region(s) to plot. These should exist in column region_code in the data file;
• group_code: name(s) of group(s) to plot. Litter groups should be available as column names in the type file;
• type_name: name(s) of type(s) to plot; Type names should be available in the type file and data file;
• figure_quality: quality of the plots in the report, either high or low.
• cutoff_count_axis: optional cutoff value as a percentage of the vertical count axis in trend plots. A cutoff value is useful to improve the readability of a plot in case of a few very high litter counts.

Data Quality Control

All input files are validated by litteR. The following validation rules apply:

1. all required columns (see above) should be available;
2. the date format should be valid, i.e. preferably YYYY-mm-dd (ISO). For convenience, the OSPAR-date format (dd/mm/YYYY) is currently also supported;
3. litter type names should be specified in the type file;
4. litter counts in the data file are natural numbers (ISO 80000-2). However, in some cases data files contain real numbers due to preprocessing. Think about normalizing survey lengths to a common length. Although litteR prefers natural numbers, real numbers are also allowed for convenience. In case non-natural numbers are found, litteR will give a warning but will continue the analysis.;
5. all records should be unique, duplicated records will be removed with a warning;
6. all cells should be filled with the appropriate data type (numbers, text or dates).
7. the data file should be a comma-separated values file (CSV), i.e., a text file where the columns are separated by commas (,) and not by spaces, semicolons (;) or tabs.

Report

litteR produces an HTML-report that can best be viewed with modern web browsers like Mozilla FireFox, Google Chrome, or Safari. These browsers are freely available from the internet.

The filename of each report starts with ‘litter-results’, followed by a timestamp: YYYYmmddTHHMMSS and the extension html. For example: litteR-results-20210904T221809.html

This section briefly describes each section in the HTML-report

Statistical summary file

In addition to a report, a results file (CSV-format) with descriptive statistics and the main trend results for each location_code is produced. An example of such a table is given below. See Section descriptive statistics for more details.

Log-file

litteR’s log-file is very helpful to understand warnings and error messages. The log-file stores the description of all data analysis steps in chronological order. Part of a log-file is given below. The complete log-file is given in the appendix.

2021-09-04 22:18:09 [INFO] Starting a new litteR session
2021-09-04 22:18:09 [INFO] litteR version: 0.9.0
2021-09-04 22:18:09 [INFO] litteR release date: 2021-08-20
2021-09-04 22:18:09 [INFO] Reading settings file ‘settings.yaml’
2021-09-04 22:18:09 [INFO] Check optional settings...
2021-09-04 22:18:09 [INFO] Check existence of required settings...
2021-09-04 22:18:09 [INFO] All required settings are available
2021-09-04 22:18:09 [INFO] Checking settings 'date_min' and 'date_max'
2021-09-04 22:18:09 [INFO] Settings 'date_min' and 'date_max' are valid
2021-09-04 22:18:09 [INFO] Checking setting 'percentage_total_count'
2021-09-04 22:18:09 [INFO] Setting 'percentage_total_count' is valid
2021-09-04 22:18:09 [INFO] Checking setting 'figure_quality'
2021-09-04 22:18:09 [INFO] Setting 'figure_quality' is valid
2021-09-04 22:18:09 [INFO] Settings file has been read
2021-09-04 22:18:09 [INFO] Constructing filename for report
2021-09-04 22:18:09 [INFO] Filename ‘litteR-results-20210904T221809.html’ created
2021-09-04 22:18:09 [INFO] Construct filename for storing statistics
2021-09-04 22:18:09 [INFO] Filename ‘litteR-results-20210904T221809.csv’ created
2021-09-04 22:18:09 [INFO] Starting litter analysis
2021-09-04 22:18:10 [INFO] Checking parameters in settings file 

Each line contains a single log-event and always has the following format:

1. timestamp;
2. type of log event: INFO for informative messages, WARN for warnings, ERROR for errors;
3. a log message.