Metadata-Version: 2.4
Name: seal-tool
Version: 0.12.1.post1
Summary: A tool to perform richness-extent-grain analyses
Author-email: Martin Matouš <m@matous.dev>, Barbora Winterová <winterova@mail.muni.cz>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://codeberg.org/mmatous/seal-tool
Project-URL: Documentation, https://mmatous.codeberg.page/seal-tool/
Project-URL: Changelog, https://mmatous.codeberg.page/seal-tool/changelog.html
Project-URL: Bug Tracker, https://codeberg.org/mmatous/seal-tool/issues
Keywords: area,distance decay,ecology,extent,grain,richness,SAR,scale,species,species-area
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: alive-progress~=3.3
Requires-Dist: plotnine~=0.15.7
Requires-Dist: polars~=1.43.1
Requires-Dist: polars-strsim~=0.2.5
Requires-Dist: pyarrow~=24.0
Requires-Dist: pydantic~=2.12
Requires-Dist: tomli-w~=1.2
Dynamic: license-file

seal
====

* ... is a tool to explore the scale dependence of ecological data, inspired by `Palmer & White <https://mmatous.codeberg.page/seal-tool/bibliography.html>`_.
* ... helps reveal whether and how observational data is affected by spatial scale—*grain* and *extent*.
* ... shows whether properties of a researched community (e.g., turnover, dissimilarity) vary when sampled at different spatial scales.
* ... provides results as raw CSV files, with optional graphical outputs.
  However, plots are not the main outcome and users are encouraged to use their favourite plotting tool.
* ... can explore the influence of spatial scale on virtually any phenomenon,
  since it necessitates only a column containing object identity (e.g., species, element, category),
  and optionally a quantitative value (e.g., units, individuals, count, concentration).
  However, to keep the documentation concise, we will focus on the analysis of a community of species.

|

* ... is **not** a statistical testing tool. Most outputs are descriptive, not inferential. This is a limitation of spatially point-based
  studies as sampling units are not independent. Moreover, data present in one observational scale contribute to data of higher scales, making
  inferential statistics biased.
* ... does **not** separate the effect of spatial scale from other potential drivers of community structure. It indicates whether spatial scale matters but does not rule out alternative explanations.


Installation
------------

Python >= 3.12 is required to run ``seal``.
Python can be installed from the official `source <https://www.python.org/downloads/>`_.

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

Linux (bash)

.. code:: console

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

Windows (Powershell)

.. code:: console

   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 <https://mmatous.codeberg.page/seal-tool/installation.html>`_.


Usage
-----

First, ensure that the virtual environment ``seal`` is installed in is activated, which is not necessarily immediately after installation.
``(venv)`` should be displayed before the prompt to run ``seal``. To activate the virtual environment and run ``seal``
run the following commands in the respective command line:

Linux:

.. code:: console

   source ./venv/bin/activate
   seal --help

Windows PowerShell:

.. code:: console

   ./venv/Scripts/activate.ps1
   seal --help


General workflow
----------------

The general workflow is as follows:

.. code:: console

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

The first command, :code:`seal preprocess`, is supplemental. It performs a couple of basic checks to reduce likelihood of incorrect data.
E.g., multiple consecutive spaces skewing the results, invalid quadrat coordinates, or missing values.

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

The second command, :code:`seal analyse` performs the actual analysis and accepts only one argument, ``--taskfile``.
Documentation on how to configure ``seal`` using a taskfile is available in the example taskfile
or in the `online documentation <https://mmatous.codeberg.page/seal-tool/cli/config.html>`_.

The last command, :code:`seal plot` is also supplemental. Plots provided directly by ``seal`` can be useful for initial
evaluation of the results, but are not (and can not be) optimized for all types of data. The preferred way
is to use own post-processing or presentation solution e.g., loading the resulting CSV into R and examining it that way.


Development
-----------

See `CONTRIBUTING.rst <https://codeberg.org/mmatous/seal-tool/src/branch/main/CONTRIBUTING.rst>`_.


References
----------

See `bibliography <https://mmatous.codeberg.page/seal-tool/bibliography.html>`_.


Licenses
--------

The source code—including the tests and documentation—is licensed under
`GPLv3 <https://codeberg.org/mmatous/seal-tool/src/branch/main/LICENSE>`_.

``./datasets/data-bmd-sl.csv`` is licensed under
`CC-BY-SA-4.0 <https://codeberg.org/mmatous/seal-tool/src/branch/main/datasets/LICENSE>`_.


Acknowledgements
----------------

Initial seal protype was funded as part of Influence of sample grain and
extent on coral reef fish richness, MUNI/IGA/1076/2021.
