Python library

Python library#

seal can also be used as a Python library.

Install it onto your system as described here.

Seal does not use the underscore convention to denote internal methods. Anything that is exported in init.py or described in this document is considered part of its official API.

Preprocess#

import seal

enc = ...  # obtain dataframe with encounters from somewhere
errors = seal.check_encounters(enc)  # perform default checks for encounters
print(errors['nas'])  # print indices of rows with missing values
print(errors['strs'])  # print dataframe containing likely erroneous strings

checks = ['nas', 'strs', 'individuals']  # specify custom list of checks
errors = seal.check_encounters(enc, checks)
print(errors['individuals'])  # print indices of rows with invalid individuals column

Analysis#

import seal
cfg = seal.Config.from_dict({  # setup configuration
    'analyses': [
        {'type': 'a1'},
        {'type': 'a2', 'permutations': 50},
    ],
    'encounters': './enc.csv',
    'locality': {
        'sides:': {'x': 10, 'y': 11}, # config up until here is mandatory
        'name': 'Plastic Beach',  # this is optional and used for filtering
    },
    'level_strategy': 'nested-quadrats',
    'levels': [1, 3],  # also optional
    'out-dir': './results',  # path to write results to, must exist beforehand
})
seal.analyse(cfg) # analyse results
# results will be in out-dir

# it is possible to reuse and modify configs
# helper to create a list of analyses
cfg.analyses = seal.make_analyses([{'type': 'a1'}, {'type': 'a2', 'permutations': 100}])
cfg.encounters = my_dataframe  # and to specify encounters as a dataframe directly
cfg.out_dir = None  # set to None to return results in memory
res = seal.analyse(cfg)  # results are returned in res

cfg = seal.Config.from_taskfile('./tasks/mytask.toml')  # config can be read from files
seal.analyse_file(cfg)  # more typing-friendly analysis method, guaranteed to return None
cfg.encounters = my_dataframe
res = seal.analyse_df(cfg)  # guaranteed to return a dict

Configuration options and their default values are documented in the example taskfile.

Misc#

Subcommands from seal misc are also available as library functions.

Adjust grid#

cfg = seal.Config.from_taskfile('./tasks/mytask.toml')
adj = seal.adjust_grid(cfg)  # perform adjustment for specified levels and strategy
adj_grid = adj[0]  # new grid is available as GridInfo NamedTuple at pos. 0
lost = adj[1]  # information about data lost due to adjustment, Lost NamedTuple

Check quadrat list#

errs = seal.check_quadrat_list(quadrat_list)  # perform checks
if 'dups' in errs:  # check whether any duplicate coordinates were found
    print(errs['dups'])

Convert AOPK#

conv = seal.convert_aopk(aopk_enc)  # perform conversion
print(errs[['coord_x', 'coord_y', 'species']])  # converted dataset contains quadrat coordinates
cfg.encounters = conv
res = seal.analyse_df(cfg)  # and is prepared for analysis

Convert Biolib#

conv = seal.convert_aopk(biolib_enc)  # perform conversion
print(errs[['coord_x', 'coord_y', 'species']])  # converted dataset contains quadrat coordinates
cfg.encounters = conv
res = seal.analyse_df(cfg)  # and is prepared for analysis

Species-area relationship level difference#

pd.read_csv('./seal-a2-aux.csv')  # obtain auxiliary data from a2
lvl_diffs, ref_lvl = seal.sar_lvl_diff(a2_aux)
print(f'Differences with reference to level {ref_lvl}:\n{lvl_diffs}')
Contents