API reference

API reference#

seal.check_encounters(enc: DataFrame, checks: list[PreprocessCheck] = ['null', 'strs']) → CheckResults#

Check encounters data for possible errors.

Parameters:

  • enc – encounters data to check

  • checks – list of checks to perform. Extra keywords will be ignored.

Returns:

A dictionary with keys from checks and results of checks as corresponding values

Raises:

pl.exceptions.ColumnNotFoundError – if check that requires missing column is requested

seal.analyse(cfg: Config, prefix: str = 'seal-') → AnalysisResults#

Perform requested analyses on specified encounters.

Parameters:

  • cfg – configuration with encounters and (optionally) quadrat_list having a pl.DataFrame assigned encounters must contain at least coord_x and coord_y integer columns and species string column quadrat_list must contain coord_x and coord_y integer columns.

  • prefix – string prepended to saved analysis results, ignored if cfg.out_dir is None

Returns:

dictionary of analysis names and results (dataframe, string, None) for requested analyses

Raises:

  • pl.exceptions.ColumnNotFoundError – if expected column is missing

  • UnsuitableGridError – if loaded grid is not suitable for requested levels or analyses

class seal.AnalysisResult(res: Result, aux: Auxiliary)#

Result of an analysis with main (res) and auxiliary (aux) component.

res: Result#

DataFrame with the main result of analysis

aux: Auxiliary#

Optional auxiliary results of analysis

seal.make_analyses(analyses: Sequence[dict[str, str | int]]) → list[Analysis]#

Return list of analysis classes as expected by Config.new().

Parameters:

analyses – a sequence of dicts matching {‘type’: ‘analysis_type’, ‘optional_key’: ‘analysis_specific_setting’}

>>> make_analyses([{'type': 'overview'}, {'type': 'sar', 'permutations': 50}])
[AGeneric(type_='overview'), ASar(type_='sar', permutations=50)]
seal.adjust_grid(levels: Iterable[int], strategy: LevelStrategy, grid: GridInfo) → tuple[GridInfo, Lost]#

Adjust grid in a way that loses minimum information.

class seal.Lost(encounters: int, species: set[str], individuals: int | None, quadrats: set[Coord])#

Represents data lost after grid adjustment.

encounters: int#

Total number of encounters (lines of input) lost from the input data.

species: set[str]#

A set() of species lost from the input data.

individuals: int | None#

Number of individuals lost during adjustment. None if input data does not contain column individuals.

quadrats: set[Coord]#

A set() of coordinates trimmed from the input data.

seal.check_quadrat_list(qlist: DataFrame) → QlistChecks#

Check quadrat lists for possibly erroneous values.

Parameters:

qlist – quadrat list to check

Returns:

A dictionary with performed checks as keys and erroneous values corresponding to check

class seal.QlistChecks#

Result of quadrat list checks. Keys correspond to check names.

seal.convert_aopk(aopk: DataFrame | LazyFrame) → DataFrame#

Convert dataset from https://portal.nature.cz/nd/ for preprocessing and analysis.

Parameters:

aopk – dataframe with columns DRUH, DATI_INSERT, SITMAP, POCET

Returns:

A dataframe with coord_x, coord_y, species, date, and individuals columns

Raises:

pl.exceptions.ColumnNotFoundError – if one or more expected columns is missing

seal.convert_biolib(biolib: DataFrame | LazyFrame) → DataFrame#

Convert dataset from https://www.biolib.cz/cz/speciesmappings for preprocessing and analysis.

Parameters:

biolib – dataframe with columns CREATED, DAY, LATIN, MONTH, SUBSQ, SQUARE, QUANTITY, YEAR

Returns:

A dataframe with date, coord_x, coord_y, species, date, and individuals columns

Raises:

  • pl.exceptions.ColumnNotFoundError – if one or more expected column is missing

  • pl.exceptions.InvalidOperationError – SUBSQ column has values other than a, b, c or d.

Note:

input dataframe columns are accepted in any combination of uppercase and lowercase letters

seal.sar_lvl_diff(sar_aux_data: DataFrame, *, is_ct: bool = False) → SarDiffRes#

Quantify spp. difference between levels based on results from species-area relationship analysis.

Parameters:

  • sar_aux_data – the auxiliary data from species-area relationship analysis

  • is_ct – True to indicate that sar_aux_data was generated using contiguous transects strategy

Returns:

Quantification result

Raises:

pl.exceptions.ColumnNotFoundError – if one or more expected columns is missing

class seal.SarDiffRes(diff: DataFrame, ref_lvl: int)#

NamedTuple with diffs and ref_lvl attributes.

diff: DataFrame#

A DataFrame with the following columns: diff, area, pct_diff, level

ref_lvl: int#

A level that was chosen as reference for diff.

class seal.Config(encounters: Path | DataFrame, quadrat_sides: Sides, out_dir: Path | None = None, levels: set[~typing.Annotated[int, ~annotated_types.Gt(gt=0)]] = {1, 2, 3}, level_strategy: LevelStrategy = 'nested-quadrats', direction: SamplingDirection = 'any', quadrat_types: list[str] | None = None, distance_type: Distance = 'euclid-diagonal', discard_zone_info: bool = False, discard_transect_info: bool = False, discard_indistinguishable: bool = True, seed: int | None = None, use_morph: bool = False, quadrat_list: Path | DataFrame | None = None, to: date | None = None, from_: date | None = None, categorical_col: str = 'species', quantity_col: str = 'individuals', include_enc: list[dict[str, set[str | int | float]]]=<factory>, exclude_enc: list[dict[str, set[str | int | float]]]=<factory>, analyses: list[Analysis] = <factory>, plot: Plot = <factory>)#

Configuration necessary for analysis and plotting.

Meant to be constructed using from_dict() or from_taskfile().

Raises:

pydantic.ValidationError – if passed options that do not translate into valid taskfile

Seealso:

./tasks/example-task.toml for options explanation

classmethod from_dict(cfg_dict: dict[str, Any]) → Self#

Return Config with the provided parameters with remaining set to default.

Parameters:

  • encounters – path to encounters dataset in CSV format

  • sides – length of quadrat’s sides, any unit of length

Raises:

pydantic.ValidationError – if passed options do not translate into valid taskfile

Seealso:

./tasks/example-task.toml for options explanation

classmethod from_taskfile(taskfile: PathLike[str] | str) → Self#

Return Config initialized with settings from a taskfile.

Parameters:

taskfile – path to TOML taskfile

Raises:

  • OSError – if file could not be read

  • pydantic.ValidationError – if file is not a valid taskfile

Seealso:

./tasks/example-task.toml for documented example

dump(directory: PathLike[str], name: str) → None#

Write config data into a directory.

Will also write encounters and quadrat_list data if they are present in a DataFrame form. :param directory: directory to save data into :param name: name of saved taskfile, optionally also the prefix of saved encounters and qlist data :raises ModuleNotFoundError: if tomli-w optional dependency is not available

class seal.Sides(x: Annotated[float, Gt(gt=0)], y: Annotated[float, Gt(gt=0)])#

Represents side lengths of quadrats.

exception seal.MissingColumnError(field: str, action: str, input_type: InputType)#

Raised when action on absent column is requested.

exception seal.UnsuitableGridError(operation: str, levels: Sequence[int] | None, axis: Axis, add_info: str | None)#

Raised when grid dimensions are not suitable for analysis with chosen level(s) and/or strategy.

class seal.GridInfo(enc: DataFrame, qlist: DataFrame)#

Contains information about spp. encounters and layout of the study grid.

enc: DataFrame#

Information about encounters in the grid. Mandatory columns: coord_x, coord_y, species. Optional: individuals.

qlist: DataFrame#

Information about quadrats in the grid. Mandatory columns: coord_x, coord_y. Optional: quadrat_type.

seal.enc_dtypes() → dict[str, DataTypeClass | DataType]#

Predefined schema of expected encounters columns with special handling.