flowchart TB
PREP["Data Preparation:<br/>importing, joining, filtering, modifying datasets "]:::Mixed
VALID{"Data<br/>Validation"}:::InPkg
EXP[Exploration:<br/> Interpreters, rounds, membership values]:::InPkg
NINT{"No. interpreters<br/> and rounds"}:::InPkg
ELI1[Within rounds<br/>agreemnet]:::InPkg
ELI2[Between rounds<br/>entropy metrics]:::InPkg
FILTER["Between rounds<br/>entropy metrics"]:::InPkg
SYNT[Synthesis]:::InPkg
OUTP[Outputs]:::Mixed
subgraph FIRST["Data preparation and exploration"]
direction LR
PREP --> VALID
VALID -->|no| PREP
VALID -->|yes| EXP -.->|review data if necessary| PREP
end
FIRST:::Steps --> SECOND:::Steps
subgraph SECOND["Analysis"]
direction LR
NINT -->|"1 interpreter <br> round"| THIRD;
NINT -->|"1 interpreter <br> >1 round"| FILTER -->|Filtering| THIRD ;
NINT -->|">1 interpreter"| FOURTH:::Mixed -->|Filtering| THIRD:::Steps;
end
subgraph THIRD["Synthesis"]
direction TB
SYNT --> OUTP;
end
subgraph FOURTH["Expert elicitation"]
direction TB
ELI1 --> ELI2
end
classDef Data fill:#f8f9fa,stroke:#1A1A1A,color:#1A1A1A,stroke-width:2px
classDef InPkg fill:#dfd,stroke:#040,color:#040,stroke-width:2px
classDef Mixed fill:#fff,stroke:#853E90,color:#853E90,stroke-width:2px,stroke-dasharray:5 5
classDef Steps fill:#fff,stroke:#853E90,color:#853E90,stroke-width:1px
Work in Progress
This package is still work in progress, but it is ready for testing! Please provide feedback on any issues, and check back regularly for updates.
Here we want to summarise discussions about the structure of the package, design decisions around functions, and their relationship with the cross-referencing process.
User journey
For the package design we distinguish two main stages of the cross-referencing process. The first is dedicated to data preparation, validation and exploration. The second is dedicated to analysis and synthesis. See Figure 1 for an overview.
The ecoSynthesis package aims to facilitate the tasks related to these stages of the cross-referencing process. While some task could be completed with the functions, classes and methods defined in this package, there are some task that will require interaction with additional R packages, other tools, and the real world.
Functions, classes and methods
This package includes functions, classes and methods. Some functionality has been proposed and tested outside the package development process. Some of these proposals are integrated in development branches before they are implemented in the main branch.
We use a consistent key to refer to these in all figures Figure 2.
Core functions
Two core functions (lookup_tbl() and membership_tbl()) create the main classes used in the package. All other functions will work with these two main classes.
Warning
Documentation of the classes is missing in the R files!
Data preparation
We propose a couple of simple functions to facilitate the most common data import nad data cleaning steps.
TO DO
Two proposed functions membership_clean() and read_membership().
However, in many cases data preparation will require wrangling with data formats (e.g. combining or joining data, filtering, modifying records). This can be done effectively inside R (for example with packages from the tidyverse collection), or outside R with other tools of preference.
Validation pipeline
Data validation allows the user to check if the data is valid for further processing. The validation functions are intended to catch common problems and pitfalls that could invalidate the final results. Validation should be completed before moving to data exploration and analysis.
Positive results of validation means that the process can move to the step of data exploration, negative results indicate that further steps of data preparation are required.
Exploration
Data exploration includes calculating basic statistics to understand the shape of the data, for example the No. of interpreters and rounds, or the distribution of membership values.
TO DO
Plot classes, summaries and other tools for exploration.
Add figure with existing and proposed functions
Data exploration could lead to identifying gaps or other shortfalls in the data. In such cases, an additional step of data preparation (and validation) might be useful before proceeding with next steps.
Data exploration will provide the basic data to inform decisions about the analysis and synthesis steps.
Analysis
Analysis steps will depend on the number of interpreters and rounds.
With one interpreter and one round, proceed directly to synthesis and outputs.
With one interpreter and multiple rounds, it is possible to analyse how uncertainty (measured as entropy) changes between rounds.
With multiple interpreters it is possible to analyse agreement and disagreement between experts in a single round, and analyse changes in uncertainty and disagreement between rounds. We refer to this process in general as expert elicitation, although the specific methods used for the consultation of interpreters can be different in different contexts.
Within rounds
TO DO
Discuss functions and their relationship
Between rounds
TO DO
Discuss functions and their relationship
Synthesis & outputs
For each unit in the source classification, what is the support for candidates in the target classification? The number of interpreters supporting a relationship, and the proportion of all membership values.
TO DO
Discuss functions and their relationship
For some outputs the main functions will be related to external packages:
- Writing synthesis membership table to a file (CSV or EXCEL format)
- Outputs to GIS data: vectors or raster attribute tables.