Support EEG data and metadata (EEG electrodes)

[alessandratrapani]

Support EEG data and metadata (EEG electrodes)

I'm from CatalystNeuro, converting data to NWB for the Gonzalez-Sulser Lab as part of the SFARI ARC project. We're working with chronic EEG recordings, and want to discuss how to support this in Spyglass (similar to the photometry discussion in #1284).

Other SFARI ARC labs with similar chronic-EEG setups are also planning to convert to NWB and adopt Spyglass, so we'd like a reusable ingestion pattern.

We're finalizing the NWB conversion now, so early input here would help us land on a structure that maps cleanly onto Spyglass.

Why EEG doesn't fit cleanly today

• EEG electrodes are single-channel skull screws or subdural contacts, not shank/probe-grouped like ElectrodeGroup/Probe in common_ephys.py assume.
• Relevant metadata doesn't map onto Probe-centric fields.
• EEG is typically already low-pass filtered/downsampled at acquisition, so forcing it through the LFP filter/banding pipeline (LFPV1) doesn't make sense.

What we'd like to discuss

• New common_eeg-type schema vs. extending common_ephys/lfp
• EEG electrode metadata table (placement, reference scheme, impedance)
• Ingestion for EEG ElectricalSeries dedicated ImportedEEG table, or generalize LFP ingestion to skip re-filtering
• populate_all_common support for the above

Happy to share example NWB files if useful.

[samuelbray32]

Hi @alessandratrapani. There is an ImportedLFP table that loads in data from pynwb.ecephys.LFP objects. This would require creating an electrodes table entry in the nwb file for the eeg screw.

Is this close to what you're looking for, or is there a feature that could be added to that table which would make it compatible?

[alessandratrapani]

I think there's a structural mismatch, though: our EEG ElectricalSeries lives in nwbfile.acquisition, not in a pynwb.ecephys.LFP object inside a processing module. From what I can tell, ImportedLFP expects the latter (i.e., data that's already been marked as "processed" and wrapped in an LFP container), whereas our EEG is the raw, as-acquired signal for those channels, nothing's been derived from a separate underlying recording, so wrapping it as LFP would misrepresent it.

[edeno]

Thanks @alessandratrapani — I pulled your draft from DANDI:001888 and looked at the structure of sub-GRIN2B-129_ses-BL2 directly. A few conclusions:

Agree that ImportedLFP is the wrong home. Your EEG is a raw ElectricalSeries in nwbfile.acquisition (ElectricalSeries_BL2, shape (21634560, 16), volts, 250.4 Hz), not a pynwb.ecephys.LFP container. ImportedLFP.make only scans pynwb.ecephys.LFP objects, so it would never see this, and wrapping raw acquisition as "LFP" would misrepresent it. So this wants its own ingestion path.

Good news on the metadata — you've already modeled it the standard way. The series carries a real .electrodes region into a normal electrodes DynamicTable (16 rows), grouped into probe-less ElectrodeGroups (EEGArray, EMGArray, device TainiTecWirelessEEG). Spyglass's existing ElectrodeGroup/Electrode tables are built to ingest exactly this — the Probe FKs are already nullable, and location/group/filtering map straight across. So we likely don't need a new EEG-electrode schema; reusing common_ephys covers most of "placement, reference scheme, impedance." Two gaps to confirm:

• You store positions as rel_x/rel_y (currently NaN); our per-session Electrode table reads x/y/z. (Only Probe.Electrode, fed by ndx-franklab-novela ShanksElectrode, reads rel_* — and there's no Probe here since the device is a plain Device.) If you want coordinates captured, either populate x/y/z, or we add a rel_* fallback on our side — a small, general improvement that would help any non-probe NWB file.
• No imp column yet — add one if impedance should be queryable.

The one real gap is signal ingestion. A raw acquisition ElectricalSeries that isn't the main wideband ephys is currently ingested by nothing: our Raw table matches series against an exact (case/space-insensitive) name allowlist, which ElectricalSeries_BL2 doesn't hit — so no collision, but also no ingestion. I'd add a small ImportedEEG table (a raw-acquisition analog of ImportedLFP) that references the series by object_id, records a valid-times IntervalList, links each column to the existing Electrode rows, keeps the trace in the NWB file, and applies no filtering — then register it in populate_all_common. Concrete sketch below.

Two things worth deciding together, since you're still finalizing the conversion:

1. Series selection. There's no NWB-native "this is EEG" marker, so ingestion has to pick these series somehow. A stable naming convention (e.g. series named EEG/EMG, or a consistent prefix) or a per-file config would be far more robust than us guessing — right now the only clean signal in the file is the group names (EEGArray/EMGArray).
2. EEG + EMG share one 16-channel series (14 EEG + 2 EMG, split only by ElectrodeGroup). Fine to keep bundled — the group split carries the distinction downstream — but worth confirming that's intended vs. separate series.

If this direction sounds right, I can put up a draft common_eeg module to test against your files. And please do share any additional example files (multi-subject / different montages) so the selection logic generalizes beyond this one.

@samuelbray32 thoughts on this direction?

Sketch: ImportedEEG (design proposal, not yet tested against a DB)

New module src/spyglass/common/common_eeg.py, modeled on ImportedLFP + the fiber-photometry response-series ingestion. Annotated at the two decisions that actually matter.

import datajoint as dj
import numpy as np
import pynwb

from spyglass.common.common_ephys import Electrode, ElectrodeGroup  # noqa: F401
from spyglass.common.common_interval import IntervalList
from spyglass.common.common_nwbfile import Nwbfile
from spyglass.common.common_session import Session  # noqa: F401
from spyglass.utils import SpyglassIngestion, logger
from spyglass.utils.nwb_helper_fn import estimate_sampling_rate, get_nwb_file

schema = dj.schema("common_eeg")


@schema
class ImportedEEG(SpyglassIngestion, dj.Imported):
    definition = """
    # Reference to a raw EEG/telemetry ElectricalSeries in nwbfile.acquisition.
    # The trace stays in the NWB file; this row indexes it (no filtering applied,
    # unlike LFPV1) so it can be time-restricted against the rest of Spyglass.
    -> Session
    eeg_object_id: varchar(40)          # NWB ElectricalSeries object_id
    ---
    -> IntervalList                     # the series' valid (recorded) times
    eeg_sampling_rate: float            # samples/sec
    name: varchar(80)
    description: varchar(2000)
    num_samples: bigint
    unit: varchar(16)
    """

    # FKs -> Session (not Nwbfile), so point fetch_nwb() at the file explicitly,
    # exactly as Raw does.
    _nwb_table = Nwbfile
    _source_nwb_object_type = pynwb.ecephys.ElectricalSeries

    class Electrode(SpyglassIngestion, dj.Part):
        definition = """
        # One column of the series -> the Electrode (channel) it records.
        # Reuses the already-ingested common_ephys.Electrode rows, so the
        # EEG/EMG group split, region, and hemisphere ride along for free
        # (no duplicated electrode metadata).
        -> master
        region_index: int               # 0-based column within the series
        ---
        -> Electrode
        """

    def make(self, key):
        # Mirror Raw: populate() and populate_all_common both route here.
        self.insert_from_nwbfile(key["nwb_file_name"])

    def get_nwb_objects(self, nwb_file, nwb_file_name=None):
        """Acquisition ElectricalSeries that Raw does NOT claim.

        DECISION #1 (the crux): there is no NWB-native "this is EEG" flag. This
        default -- "acquisition ES not matched by Raw's name allowlist" -- is
        safe on Frank-lab files (their only ES is the Raw-named wideband) and
        picks up ElectricalSeries_BL2 here. It is still a heuristic: a file with
        a second genuine raw series would be miscaught. Prefer converging with
        the data producer on a naming convention or entries.yaml config.
        """
        from spyglass.common.common_ephys import Raw

        raw_names = {
            Raw.sanitize_nwb_object_name(n) for n in Raw._source_nwb_object_name
        }
        return [
            obj
            for obj in nwb_file.acquisition.values()
            if isinstance(obj, pynwb.ecephys.ElectricalSeries)
            and self.sanitize_nwb_object_name(obj.name) not in raw_names
        ]

    def generate_entries_from_nwb_object(self, nwb_obj, base_key=None):
        """IntervalList + master + .Electrode rows for one series."""
        base_key = (base_key or {}).copy()
        series = nwb_obj
        object_id = series.object_id
        rate = series.rate or estimate_sampling_rate(
            np.asarray(series.get_timestamps()[: int(1e6)])
        )
        interval_list_name = f"{series.name} valid times"

        interval_entry = dict(
            base_key,
            interval_list_name=interval_list_name,
            valid_times=self._valid_times(series, rate),
            pipeline="imported_eeg",
        )
        master_row = dict(
            base_key,
            eeg_object_id=object_id,
            interval_list_name=interval_list_name,
            eeg_sampling_rate=rate,
            name=series.name,
            description=getattr(series, "description", None),
            num_samples=int(series.data.shape[0]),
            unit=series.unit,
        )

        # DECISION #2: link each column to the existing Electrode row via the
        # series' .electrodes region. This carries the EEG-vs-EMG split
        # (EEGArray/EMGArray) without the master committing to a single group,
        # and reuses metadata already ingested by common_ephys -- no new
        # electrode schema. A series without a region -> master only + warning.
        elec_rows = []
        region = getattr(series, "electrodes", None)
        if region is None:
            logger.warning(
                f"ImportedEEG {series.name!r}: no .electrodes region; storing "
                "the signal reference without per-channel Electrode links."
            )
        else:
            group_names = region.table["group_name"].data
            electrode_ids = region.table.id.data
            for region_index, position in enumerate(region.data):
                position = int(position)
                if not 0 <= position < len(electrode_ids):
                    raise ValueError(
                        f"ImportedEEG {series.name!r}: region position "
                        f"{position} out of range for the electrodes table."
                    )
                elec_rows.append(
                    dict(
                        base_key,
                        eeg_object_id=object_id,
                        region_index=region_index,
                        electrode_group_name=str(group_names[position]),
                        electrode_id=int(electrode_ids[position]),
                    )
                )

        return {
            IntervalList: [interval_entry],
            self: [master_row],
            self.Electrode: elec_rows,
        }

    @staticmethod
    def _valid_times(series, rate):
        # Continuous acquisition -> one [start, end] interval.
        if series.timestamps is not None:
            ts = np.asarray(series.timestamps)
            return np.array([[ts[0], ts[-1]]])
        start = series.starting_time or 0.0
        end = start + (int(series.data.shape[0]) - 1) / rate
        return np.array([[start, end]])

    def nwb_object(self, key):
        object_id = (self & key).fetch1("eeg_object_id")
        nwbf = get_nwb_file(Nwbfile.get_abs_path(key["nwb_file_name"]))
        return nwbf.objects[object_id]

Register in populate_all_common (third table list, after Electrode is populated, since the .Electrode part FKs it):

ImportedEEG,  # Depends on Session and Electrode

Caveats (haven't run this yet): the .Electrode part FKs common_ephys.Electrode, so it only resolves once ordinary electrode ingestion has produced rows for the probe-less groups (first thing to test on a real populate); and the region.table[...] DynamicTable access should be confirmed against the pynwb version in use.

[alessandratrapani]

Thanks so much for digging into the actual file — this is really helpful, and the direction sounds right to me.

On the two open questions:

1. Series selection: agreed a naming convention is the way to go rather than guessing from group names. On reflection, I think the cleanest approach is to give the EEG and EMG series distinct, standardized name prefixes at conversion time, e.g. EEGElectricalSeries and EMGElectricalSeries, rather than relying on ElectrodeGroup to carry that distinction. That way ingestion can key off the series name directly and it stays robust as we roll this out to other labs' conversions too.
2. EEG + EMG bundling: given the above, I'd actually lean toward splitting them into separate series rather than keeping them bundled in one 16-channel series, one ElectricalSeries for the 14 EEG channels, one for the 2 EMG channels, each named per the convention above. Happy to update our conversion to do this if it makes the ingestion logic (and the ImportedEEG design) simpler on your end.

On the metadata gaps: we'll populate x/y/z directly rather than rel_x/rel_y, so no need for a fallback on your side unless it'd be useful for other labs' conversions.

One more question on our end: how should the EMG series itself be ingested? It's structurally identical to the EEG series (raw ElectricalSeries in acquisition, same electrodes-table pattern), but it's a different signal type (muscle activity, not brain), so I wasn't sure whether it makes sense to route it through the same ImportedEEG table, or whether it'd need its own table (e.g. ImportedEMG) so it's not misrepresented as EEG downstream. Happy to go whichever way makes more sense on the Spyglass side.

This all sounds like a solid direction. Please go ahead with the common_eeg draft, and I'll get you additional example files

[CBroz1]

Questions

Hi @alessandratrapani - could you help us understand...

1. Processing: What processing steps should happen at ingestion, if any? Is it different for EEG vs EMG?
2. Lineage: Where this table would connect downstream?

Convention

Taking LFP as a model of the existing convention, we have...

1. common
   1. Script
   2. Lineage, : Session -> LFPSelection -> LFP (fetching from Raw¹) -> LFPOutput.CommonLFP
   3. Processing: LFP.make runs some filtering defined by FirFilterParameters
2. imported
   1. Script
   2. Lineage: ImportedLFP -> LFPOutput.ImportedLFP
   3. Processing: minimal
3. custom
   1. Scripts: privately sharable, not in Spyglass
   2. Lineage: Custom1 -> Custom2 (where Custom2 may also inherit a Spyglass table like Electrode)
   3. Processing: user defined

Returning to the questions, the ImportedEEG sketch above, to my eye...

1. Processing: doesn't really fit the common convention for lack of user-defined processing steps.
2. Lineage: Doesn't suggest any fk inheritance (e.g., some merge table).
   1. If we expect this later, we could take the imported approach
   2. If not, we could talk about the what the Gonzalez-Sulser lab wants to see done the data. If that's just ensuring that their custom tables get populated by a make function or populate_all_common, I could see a more general adaptation there.

EEG vs EMG

If two things are structurally identical, I'm inclined to distinguish them with a descriptor field (e.g., source: enum('neural', 'muscular')) and let downstream tables determine how to process on that basis. I try to reserve new table declaration for things that are incompatible (e.g., 1:1 vs many:1 fk correspondence)

Footnotes

1. @samuelbray32 mentioned in conversation that Raw would not be a good fit for EEG given it's 1:1 correspondence with Session ↩