`alp_data.datasets` module

What are ALP Datasets?

The datasets module provides a collection of datasets validated by ESP's engineering team and almost entirely sourced from public sources with permissive licenses (for provenance refer to dataset descriptions in Available Datasets). This is the module to use to download, load and manipulate official ALP datasets.

More technically an ALP Dataset is defined as such:

Inherits from the base Dataset class
Has a defined DatasetInfo containing metadata
Provides methods for loading and accessing data and splits
Can be configured through a DatasetConfig

How to Load Datasets

Datasets can be loaded following two different approaches:

Direct instantiation:

from alp_data.datasets import AnimalSpeak

# Create a dataset instance
dataset = AnimalSpeak(
    split="validation"
)

# Access data
sample = dataset[0]  # Get first sample
print(len(dataset))  # Get dataset size

Using configuration:

from alp_data import DatasetConfig
from alp_data.datasets import AnimalSpeak

# Create a configuration
config = DatasetConfig(
    dataset_name="animalspeak",
    split="validation",
)

# Create dataset from config
# This returns a tuple, the dataset and a dictionary of metadata
# The metadata is generated by any transforms in the config which
# are applied to the dataset
dataset, _ = AnimalSpeak.from_config(config)

From a config yaml file:

Your yaml config file should look like this for a single dataset (see Concatenate Datasets for multiple datasets): Note the dataset key at the top level is required.

dataset:
  dataset_name: AnimalSpeak
  split: validation
  output_take_and_give:
    labels: label
  data_root: null
  transformations:
    - type: deduplicate
      subset: null

    - type: label_from_feature
      feature: species_common
      output_feature: label
      override: true

from alp_data import dataset_from_config

ds, transform_metadata = dataset_from_config("path/to/config.yaml")

print(len(ds))

Dataset Configuration

Deeper levels of configurations can be achieved by using specific parameters which are either common to all datasets or specific to a single dataset. Common arguments are:

split: The data split to use (e.g., "train", "validation").
output_take_and_give: Column picker and name mappings. This is used to:
- Pick the columns you want in the output dictionary returned when __getitem__ is called via x = sample[0].
- Rename the columns in the output dictionary. For example, if you want to rename the "audio" column to "raw_wav", you can specify {"audio": "raw_wav"}.
sample_rate: Target audio sample rate (for audio datasets, it will resample to this rate).
data_root: Custom root directory for data files. If not specified, the data_root is set as the parent directory of the path to the split. The idea is that the data may be copied from its original location (usually a bucket) to a local disk or a folder on the shared nfs.

Using Transforms with Datasets

Datasets can be combined with Transforms to modify or enhance the data during loading. Transforms modify the data in place, so the returned dataset will effectively be a different version of the original data.

Basic Usage with Transforms

Transforms can be used in a sequential way, as in: first, get the original dataset, then apply a transform:

Remark

The order of the transforms is important. If you have multiple transforms, they will be applied in the order they are defined in the configuration. For example, if you change the name of a column with LabelFromFeatureTransform, it will effect the Filter Transform

from alp_data.datasets import AnimalSpeak
from alp_data.transforms import FilterConfig, LabelFromFeatureConfig

# Create a dataset
aspeak_output_map = {
    "audio": "raw_wav"  # maps  the "audio" column to "raw_wav" in output
}
dataset = AnimalSpeak(split="validation", output_take_and_give=aspeak_output_map)

# Create transform configurations
filter_config = FilterConfig(
    type="filter",
    property="source",
    values=["xeno-canto", "iNaturalist"],
    mode="include"
)

label_from_feature_config = LabelFromFeatureConfig(
    type="label_from_feature",
    feature="canonical_name",
    output_feature="label"
)

dataset.apply_transformations([filter_config, label_from_feature_config])

Using Transforms in Dataset Configuration

Transforms can also be specified in the dataset configuration to be automatically applied when the dataset is instantiated.

from alp_data import DatasetConfig
from alp_data.transforms import FilterConfig, LabelFromFeatureConfig

# Create transform configurations
filter_config = FilterConfig(
    type="filter",
    property="source",
    values=["xeno-canto", "iNaturalist"],
    mode="include"
)
label_config = LabelFromFeatureConfig(
    type="label_from_feature",
    feature="canonical_name",
    output_feature="label"
)

# Create dataset configuration with transforms
config = DatasetConfig(
    dataset_name="animalspeak",
    split="validation",
    transformations=[filter_config, label_config]
)

# Create dataset with transforms
dataset, metadata = AnimalSpeak.from_config(config)

print(metadata.keys())
# dict_keys(['filter', 'label_from_feature'])
print(metadata["label_from_feature"].keys())
# dict_keys(['label_feature', 'label_map', 'num_classes'])

alp_data.datasets module