Quickstart

Installation

Python >= 3.12 is required to run seal. Python can be installed from the official source.

When Python is installed, run the following commands in the respective command line:

Linux

python -m venv ./venv
source ./venv/bin/activate
pip install seal-tool
seal --help

Windows (Powershell)

python -m venv ./venv
./venv/Scripts/Activate.ps1
pip install seal-tool
seal --help

For more detailed guide and additional ways to obtain seal see Installation.

Usage

First, ensure that the virtual environment in which seal was installed is activated, which is not necessarily immediately after the installation of seal. To activate the virtual environment run the following commands in the respective command line:

Linux:

source ./venv/bin/activate

`Windows PowerShell:

./venv/Scripts/activate.ps1

The virtual environment must be re-activated whenever a new terminal window is opened. After successful activation, (venv) should be displayed at the beginning of the command prompt. After the virtual environment is activated, run seal using:

seal --help

The --help argument can be used any time for quick help and an overview of the available commands and subcommands, e. g. seal analyse --help.

General workflow

Warning

Analysis specifications are defined in taskfile. Users are strongly encouraged to familiarize themselves with the provided example before configuring their own analyses.

The general workflow consists of the following commands: preprocess -> misc adjust-grid -> analyse -> plot:

seal preprocess --dataset ./datasets/my-data.csv --output ./datasets/my-data-fix.csv
seal misc adjust-grid --taskfile ./tasks/my-task.toml
seal analyse --taskfile ./tasks/my-task-adj.toml
seal plot --taskfile ./tasks/my-task-adj.toml

The first command, seal preprocess, is an optional preparatory step. It performs a couple of basic checks to reduce the likelihood of errors in the input data. E.g., multiple consecutive spaces creating non-existent species, invalid quadrat coordinates, or missing values. It is not able to evaluate correctness of proposed fixes (bar two) so cleaning input data falls to users.

Complete list of checks can be viewed upon calling seal preprocess --help.

The second command seal misc adjust-grid adjusts the study grid to fit spatial constraints of the selected transformation strategy. For further information, see the description of transformation strategies . After the adjustment, a new encounters dataset is saved in the same directory as the original dataset. If a quadrat list was provided in the taskfile, an adjusted quadrat list is saved alongside the original one as well. An updated taskfile is also saved either in the specified output directory or alongside the new encounters file, given no output directory was provided.

The command accepts one required argument, --taskfile, which specifies the task configuration file. Documentation on how to configure seal using a taskfile is available in the example taskfile or in the online documentation.

The next command, seal analyse performs the analyses specified in the taskfile. It also requires the --taskfile argument. Both numerical and graphical outputs are saved in the output directory specified in the taskfile. Numerical results are stored as CSV files and can be used in any external post-processing or visualization workflow. For some analyses, auxiliary output is also generated.

The final command, seal plot is also optional. It provides graphical summaries that are useful for an initial inspection of the analysis results. Plots provided directly by seal can be useful, but are not (and cannot be) optimized for all types of data. For publication-quality figures, users are encouraged to modify the plotting code, or process the resulting CSV files in their preferred visualization tool.

Development

For information on contributing to seal, see CONTRIBUTING.rst.

References

The complete bibliography used in the documentation is available in the bibliography.

Licenses

The seal source code—including the tests and documentation—is licensed under GPLv3.

./datasets/data-bmd-sl.csv is licensed under CC-BY-SA-4.0.

Acknowledgements

The initial seal prototype was developed with funding from the project Influence of sample grain and extent on coral reef fish richness (MUNI/IGA/1076/2021), funded by Masaryk University, Czech Republic. Further development of the program was supported by Masaryk University through projects MUNI/A/1489/2023, MUNI/A/1422/2022, and MUNI/A/1348/2022. Fieldwork in Sri Lanka was conducted under research permit no. WL/3/716/2022, issued by the Department of Wildlife Conservation of Sri Lanka. Data collection in Bermuda was conducted with the support of the Bermuda Aquarium, Museum & Zoo, with particular thanks to Dr. Robbie Smith.