concord-core

The contract layer — containers and interfaces that every other package depends on

Package Structure

concord-core/
  src/concord_core/
    __init__.py       exports all containers, ABCs, and configure_logging
    containers.py     Recording, MetricResult, ParameterVector, ModelOutput
    abc.py            Metric ABC, Model ABC, MetricRequirements
    logging.py        shared logging setup

Recording

Recording is the primary data container. It wraps a numpy array of EEG signal along with all the metadata needed to interpret it.

Properties

channel_metadata structure

When loaded from a BIDS dataset, channel_metadata is a dict like:

{
  "SEEG1": {
    "status": "good",            # "good" | "bad" | None
    "status_description": "soz", # "soz" | "resected" | None | other
    "x": 12.3,                   # MNI coordinate (float) or None
    "y": -24.1,
    "z": 8.5,
    "type": "SEEG",
    ...                          # any other columns from channels.tsv
  },
  "SEEG2": { ... },
  ...
}

MetricResult

MetricResult is the output of any metric computation. It stores the result array alongside enough metadata to fully interpret it.

Shape conventions

Metric ABC

Every metric in the system must subclass Metric and implement three things. See Abstract Base Classes for how this pattern works in Python.

Implementing a Metric

from concord_core import Recording, MetricResult
from concord_core.abc import Metric, MetricRequirements
import numpy as np

class MyMetric(Metric):
    def __init__(self, window_s: float = 1.0):
        self.window_s = window_s      # only config, no data

    @property
    def name(self) -> str:
        return "my_metric"

    @property
    def requires(self) -> MetricRequirements:
        return MetricRequirements(
            min_duration_s=self.window_s,
            min_fs_hz=10.0,
        )

    def compute(self, recording: Recording) -> MetricResult:
        result = np.mean(recording.data, axis=1)   # shape (n_channels,)
        return MetricResult(
            data=result,
            metric_name=self.name,
            params={"window_s": self.window_s},
            channel_labels=list(recording.channel_names),
            units="V",
        )

ParameterVector

ParameterVector carries model parameter values alongside their names and bounds. It is the input to Model.simulate() and the search space for optimization in concord-fit.

ModelOutput

ModelOutput is the output of a model simulation — the simulation-side analog of MetricResult. It contains the simulated signal plus all internal state variables.

Model ABC

Every neural mass model must subclass Model and implement three things. This mirrors the Metric ABC pattern — see Abstract Base Classes for the general concept and Neural Mass Models for the domain background.

Implementing a Model

from concord_core import Model, ModelOutput, ParameterVector
import numpy as np

class MyModel(Model):
    @property
    def name(self) -> str:
        return "my_model"

    def default_parameters(self) -> ParameterVector:
        return ParameterVector(
            names=["param_a", "param_b"],
            values=np.array([1.0, 2.0]),
            lower=np.array([0.0, 0.0]),
            upper=np.array([10.0, 10.0]),
        )

    def simulate(self, parameters, duration_s, fs, seed=None):
        # ... integrate ODEs, produce signal ...
        return ModelOutput(
            data=signal, fs=fs,
            state_variables={...},
            parameters=parameters,
            node_labels=["node_0"],
        )

Logging

logging.py configures the root logger named "Montage Concord". All packages use logging.getLogger("Montage Concord.{package_name}") to emit log messages that inherit this configuration.