Utilities

echopop.utils.base.apply_filters(data: Series | DataFrame, include_filter: dict[str, Any] | None = None, exclude_filter: dict[str, Any] | None = None, replace_value: number | None = None) → DataFrame

Apply inclusion and exclusion filters to a DataFrame.

Filters rows and columns based on index/column values, supporting both inclusion and exclusion criteria with single values or lists of values. Handles interval-based filtering for categorical interval indices.

Parameters:

datapandas.DataFrame pr pandas.Series

Input DataFrame or Series to filter

include_filterDict[str, Any], optional

Dictionary of column/index:value(s) pairs. Rows/columns will be kept if they match. If value is a list, rows/columns matching any value in the list will be kept.

exclude_filterDict[str, Any], optional

Dictionary of column/index:value(s) pairs. Rows/columns will be excluded if they match. If value is a list, rows/columns matching any value in the list will be excluded.

replace_valuenumpy.number, optional

If provided, replaces values in excluded columns with this value instead of dropping them.

Returns:

pandas.DataFrame

Filtered DataFrame

Examples

>>> # Row filtering: Keep only females and males from sex column
>>> apply_filters(df, include_filter={"sex": ["female", "male"]})
>>> # Row filtering: Exclude unsexed specimens and small fish
>>> apply_filters(df, exclude_filter={"sex": "unsexed", "length": 10})
>>> # Index filtering: Keep rows where length_bin contains values 1-5
>>> apply_filters(df, include_filter={"length_bin": [1, 2, 3, 4, 5]})
>>> # Column filtering: Keep only female and male columns (wide format)
>>> apply_filters(df, include_filter={"sex": ["female", "male"]})
>>> # Multi-index filtering: Filter by age_bin, length_bin, and sex simultaneously
>>> apply_filters(df, include_filter={"age_bin": [1], "length_bin": [1, 2, 3], "sex": ["male"]})
>>> # Combined filtering: Include certain length bins but exclude unsexed
>>> apply_filters(df, include_filter={"length_bin": [1, 2, 3]},        exclude_filter={"sex": "unsexed"})

echopop.utils.base.binify(data: DataFrame | dict[str, DataFrame], bins: ndarray[number], bin_column: str) → None

Apply binning to biological data using predefined bin distributions.

This function bins continuous variables (like length or age) in biological datasets using bin edge arrays. It creates interval distributions internally and can handle single DataFrames or dictionaries of DataFrames, automatically skipping DataFrames that don’t contain the target column. The data is modified in place.

Parameters:

datapandas.DataFrame or Dict[str, pandas.DataFrame]

Target data to bin. Can be a single DataFrame or dictionary of DataFrames. Data are modified in place.

binsnp.ndarray[numpy.number]

Array of bin edge values. Must be 1-dimensional and contain at least 2 elements. Values should be in ascending order for proper binning behavior.

bin_columnstr

Name of the column in data to apply binning to (e.g., 'length', 'age').

Returns:

None

Data is modified in place, nothing is returned.

Examples

>>> import pandas as pd
>>> import numpy as np
>>> from echopop.nwfsc_feat.utils import binify
>>>
>>>
>>> # Create sample data
>>> bio_data = pd.DataFrame({
...     'length': [25.5, 30.2, 35.8, 40.1, 45.3],
...     'weight': [150, 220, 310, 420, 580]
... })
>>>
>>>
>>> # Create bin edges
>>> length_bins = np.array([20, 30, 40, 50])
>>>
>>>
>>> # Apply binning (modifies bio_data in place)
>>> binify(bio_data, length_bins, 'length')
>>> print('length_bin' in bio_data.columns)
True
>>>
>>>
>>> # Works with numpy linspace too
>>> age_bins = np.linspace(start=1., stop=22., num=22)
>>> bio_data['age'] = [5, 8, 12, 15, 18]
>>> binify(bio_data, age_bins, 'age')
>>> print('age_bin' in bio_data.columns)
True
>>>
>>>
>>> # Works with dictionary of DataFrames too
>>> data_dict = {'catch': bio_data.copy(), 'length': bio_data.copy()}
>>> binify(data_dict, length_bins, 'length')
>>> print('length_bin' in data_dict['catch'].columns)
True