Configuration

To tell seal what data it is supposed to analyse and how, it is necessary to desribe its tasks in a configuration file called taskfile in TOML format. A documented example is provided below.

example-taskfile.toml

## This file exists to demonstrate taskfile syntax and permissible values.
## It is not an overview of sane default for your analysis or any analysis.
## Prune and adjust as necessary.

# Path to dataset with encounters
# Expected columns in the dataset: coord_x, coord_y, species
# Optional columns:
	# locality: can be used to filter data based on locality, country, treatment, etc.
	# direction: if samples are collected as transects, you can mark down direction of collection and choose which to use
	# morph: contains name of morphospecies in case of cryptic species or species which cannot be told apart
	# individuals: number of individuals
	# date: in ISO 8601 format (yyyy-mm-dd)
# optional columns are only supported for filtering or preprocess checks
# Any other field will be ignored.
# Mandatory argument
encounters = "./datasets/data-bmd-sl.csv"

# List of quadrats present in given locality
# Must contain coord_x and coord_y columns with quadrat_type being optional
# This ensures even quadrats with no encountered species (and logically
# missing from the dataset with encounters) are included in analysis with 0 richness.
# Quadrat list will be inferred from supplied encounters dataset otherwise.
# Leaving this empty may negatively influence the accuracy of results.
# Optional
quadrat-list = "./datasets/qlists/kayankerni-20220605.csv"

# List of levels to analyse
# Used in every analysis
# options: 1-inf
# Mandatory
levels = [ 1, 2 ]

# How to create levels for analysis
# default: nested-transects
# options: nested-quadrats, contiguous-transects, nested-transects
# see https://mmatous.codeberg.page/seal-tool/methodology/strategies.html for more details
level-strategy = "nested-transects"

# Dimensions of a quadrat
# Used in overview, sar, turnover
# Mandatory
quadrat-sides = { x = 10, y = 10 }

# Categorical dataset column to analyse
# Used in every analysis
# default: species
categorical-col = "species"

# Quantitative dataset column to analyse
# Used in overview (optional), abundance (mandatory)
# default: individuals
quantity-col = "individuals"

# Which analyses to perform
# It is possible to specify an analysis multiple times with different parameters.
# see https://mmatous.codeberg.page/seal-tool/methodology/analyses.html for more details
# Mandatory
analyses = [
	{ type = "overview" },
	{ type = "sar", permutations = 200 },
	# an analysis may be specified multiple times with different parameters
	{ type = "sar", permutations = 2 },
	# difference (default): pairwise species difference
	# simpson: Simpson pairwise dissimilarity
	{ type = "turnover", interval = 10, formulas = ["difference", "simpson"] },
	{ type = "richness"},
	{ type = "spatial" },
	# braycurtis: Bray–Curtis dissimilarity, quantity-col must be present in dataset
	# jaccard (default): Jaccard's dissimilarity
	# sorensen: Sorensen's dissimilarity
	{ type = "dissimilarity", interval = 10, formulas = ["braycurtis", "jaccard", "sorensen"] },
	{ type = "abundance" },
]

# Directory to write results into
# Will be created if necessary and seal is used as CLI tool
# Must be created manually if seal is used as a library.
# default "./results"
out-dir = "./example-results"

# Distance function to use
# Used in turnover, richness, dissimilarity
# options:
#   chebyshev - chebyshev distance between two quadrat's farthest sides, used in the original P&W paper
#   euclid-centroid - euclidean distance between two quadrat's centroids
#   euclid-diagonal - euclidean distance between two quadrat's farthest corners
# default: euclid-diagonal
distance-type = "euclid-diagonal"

# Filter sampling direction
# Used in every analysis
# options any, forward, backward or richer (direction with more species encountered, per-quadrat)
# default: any
direction = "richer"

# Include only quadrats of given types in the analysis
# Quadrats not present in encounters dataset will have richness set to 0
# Used in every analysis
# default: do not filter anything
quadrat-types = [ "normal", "shallows", "no-reef" ]

# Disregard transect info (x coordinate) for analysis -> zones are ignored, transects merge into one quadrat
# Used in every analysis
# default: false for nested-quadrats strategy, forced true otherwise
discard-transect-info = false

# Disregard zone (y coordinate) for analysis -> zones across transect merge into one quadrat
# Used in every analysis
# default: false
discard-zone-info = false

# Drop all indistinguishable encounters from dataset (species ends with ' .sp')
# Used in every analysis
# default: false
discard-indistinguishable = true

# Replace species column with data from morph column
# Used in every analysis
# default: false
use-morph = false

# Seed RNG with specified value for reproducible output
# default: None
seed = 8001

# Analyse only encounters between from and to dates, bounds included.
# Must be in ISO 8601 format
# default: no filter
from = 2022-06-05
to = 2022-06-09

# Only include rows in "encounters" where given column has one of listed values
# Used in every analysis
# default: include everything
include-enc = [
	{"locality" = ["Kayankerni"]},
]

# Exclude rows in "encounters" where given column has one of listed values
# Takes precedence over "include" key
# Used in every analysis
# default: exclude nothing
exclude-enc = [
	{"family" = ["Caesionidae", "Gobiidae"]},
	{"phase" = ["juv"]},
]

# Configuration specific to plotting
[plot]
# Denote error using given type
# alt. ["type", width]
# Options (type): ci, pi, sd, se
# Options (width): ci, pi: 0.0-1.0; sd, se: 1-N
# default widths: ci, pi: 0.95; sd, se: 1
# default type: se
error-type = ["ci", 0.85]
# Select graph output format
# Options: png, svg
# default: svg
output_format = 'png'