Skip to content

Quick Start

Get up and running with CobraBox in 5 minutes.

1. Create Data

Start with a numpy array and wrap it in a Data container:

import cobrabox as cb
import numpy as np

# Create synthetic data: 100 timepoints, 4 channels
my_array = np.random.default_rng(seed=0).normal(size=(100, 4))

data = cb.from_numpy(
    arr=my_array,
    dims=["time", "space"],
    sampling_rate=100.0,  # Hz
    subjectID="sub-01",
    condition="baseline",
)

2. Apply a Feature

Call .apply(data) on any feature class:

feat = cb.LineLength().apply(data)

print(f"Shape: {feat.data.shape}")
print(f"History: {feat.history}")  # ['LineLength']

3. Chain Features with |

Use | to build a sequential Pipeline:

pipeline = cb.Min(dim="time") | cb.Max(dim="time")
result = pipeline.apply(data)
print(result.history)  # ['Min', 'Max']

4. Windowed Pipelines with Chord

Pipe a SplitterFeature into a pipeline and close it with an AggregatorFeature:

chord = cb.SlidingWindow(window_size=20, step_size=10) | cb.LineLength() | cb.MeanAggregate()
result = chord.apply(data)
print(result.history)  # ['SlidingWindow', 'LineLength', 'MeanAggregate', 'Chord']

A Chord is itself a BaseFeature, so it composes with | like any other step.

5. Apply to a Dataset

cb.load_dataset() returns a Dataset[SignalData] — an immutable, typed collection with helpers:

ds = cb.load_dataset("dummy_chain")
ds.describe()  # print shapes, metadata summary
ds.filter(groupID="A")  # subset by metadata
ds.groupby("condition")  # dict[str, Dataset]

pipeline = cb.SlidingWindow(window_size=20, step_size=10) | cb.LineLength() | cb.MeanAggregate()

results = cb.Dataset([pipeline.apply(d) for d in ds])

6. Access Data

# As numpy array
arr = result.to_numpy()

# Access underlying xarray.DataArray
xr_data = result.data

7. Save and Load Pipelines

Any feature, pipeline, or chord can be serialized to YAML or JSON and reloaded later:

# Save to file
cb.save(pipeline, "my_pipeline.yaml")

# Load from file
loaded = cb.load("my_pipeline.yaml")
result = loaded.apply(data)

# Or convert to a string (e.g. for storing in a database)
yaml_str = pipeline.to_yaml()
restored = cb.Pipeline.from_yaml(yaml_str)

See Pipelines — Serialization for the full reference.

What's Next?

  • Core Concepts — Immutability, metadata, history, and the feature system
  • Feature Guide — All feature types and how to create custom ones
  • Pipelines — | syntax, Chord, batch processing, and serialization
  • Data Containers — Deep dive into the Data class