API reference

API reference#

seal.check_encounters(enc: DataFrame, checks: list[PreprocessCheck] = ['nas', 'strs']) → dict[PreprocessCheck, pd.Index[int] | pd.DataFrame]#

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:

KeyError – 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 pd.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 pd.MultiIndex

  • 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:
class seal.AnalysisResult(res: Result, aux: Auxiliary)#

Result of an analysis.

aux: Auxiliary#

Optional auxiliary results of analysis

res: Result#

DataFrame with the main result 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': 'a1'}, {'type': 'a2', 'permutations': 50}])
[Analysis0(type_='a1'), Analysis2(type_='a2', 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.GridInfo(enc: Encounters, qlist: QList)#

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

enc: Encounters#

Information about encounters in the grid.

qlist: QList#

Information about quadrats in the grid.

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.

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.

species: set[str]#

A set() of species lost 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) → 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:

  • AttributeError – if one or more of expected columns is missing

  • KeyError – if one or more of expected columns is missing

seal.convert_biolib(biolib: DataFrame) → 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:

  • AttributeError – if one or more of expected columns is missing

  • KeyError – if one or more of expected columns is missing

  • ValueError – SUBSQ column has values other than a, b, c or d.

seal.sar_lvl_diff(a2_aux_data: DataFrame, *, is_rtm: bool = False) → A2DiffRes#

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

Parameters:

  • a2_aux_data – the auxiliary data from species-area relationship analysis (a2)

  • is_rtm – True to indicate that a2_aux_data was generated using repeated transect merging strategy

Returns:

Quantification result

Raises:
class seal.A2DiffRes(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: ~pathlib.Path | ~pandas.core.frame.DataFrame, quadrat_sides: ~seal.config.Sides, out_dir: ~pathlib.Path | None = None, levels: list[~typing.Annotated[int, ~annotated_types.Gt(gt=0)]] = [1, 2, 3], level_strategy: LevelStrategy = 'nested-quadrats', direction: SamplingDirection = 'any', include_tiny: bool = True, quadrat_types: list[QuadratType] | None = None, distance_type: Distance = 'euclid-diagonal', discard_zone_info: bool = False, discard_transect_info: bool = False, discard_indistinguishable: bool = True, exclude_families: list[str] = <factory>, include_families: list[str] = <factory>, exclude_phases: list[str] = <factory>, seed: int | None = None, use_morph: bool = False, locality_name: str | None = None, quadrat_list: ~pathlib.Path | ~pandas.core.frame.DataFrame | None = None, to: ~datetime.datetime | None = None, from_: ~datetime.datetime | None = None, categorical_col: str = 'species', quantity_col: str = 'individuals', analyses: list[Analysis] = <factory>, plot: ~seal.config.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

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: list[int] | None, axis: Axis, add_info: str | None)#

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

Contents