Testing

Data Interface Mixins

class DataInterfaceTestMixin(/, *args, **kwargs)

Bases: object

Generic class for testing DataInterfaces.

Several of these tests are required to be run in a specific order. In this case, there is a test_conversion_as_lone_interface that calls the check functions in the appropriate order, after the interface has been created. Normally, you might expect the interface to be simply created in the setUp method, but this class allows you to specify multiple interface_kwargs.

Class Attributes

data_interface_clsDataInterface

class, not instance

interface_kwargsdict or list

When it is a dictionary, take these as arguments to the constructor of the interface. When it is a list, each element of the list is a dictionary of arguments to the constructor. Each dictionary will be tested one at a time.

save_directoryPath, optional

Directory where test files should be saved.

data_interface_cls: type[BaseDataInterface]

interface_kwargs: dict

save_directory: Path = PosixPath('/tmp/tmp9ge9zc9r')

conversion_options: dict | None = None

maxDiff = None

check_read_nwb_backends: tuple[str, ...] = ('hdf5', 'zarr')

setup_interface(request)

Add this as a fixture when you want freshly created interface in the test.

setup_default_conversion_options()

test_source_schema_valid()

test_conversion_options_schema_valid(setup_interface)

test_metadata_schema_valid(setup_interface)

test_metadata(setup_interface)

Test the dict-based metadata, which is the format every interface will emit.

See catalystneuro/neuroconv#1557 for discussion on what get_metadata() should return (provenance vs convenience).

Dual-mode interfaces (those that still expose the old list-based format) opt into the dict format via use_new_metadata_format=True. Dict-only interfaces return it unconditionally from get_metadata().

check_extracted_metadata(metadata: dict)

Override this method to make assertions about specific extracted metadata values.

test_no_metadata_mutation(setup_interface)

Ensure the metadata object is not altered by add_to_nwbfile method.

test_all_conversion_checks(setup_interface, tmp_path, backend)

Write the interface out and validate what lands on disk, once per backend.

run_conversion resolves the default backend configuration internally, so passing one explicitly writes the same file; that equivalence is covered once on a mock interface in tests/test_minimal/test_interfaces_run_conversion.py.

edit_metadata(metadata: dict) → dict

Override this to edit the interface’s metadata before it is written, the way a user would.

abstractmethod check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

run_custom_checks()

Override this in child classes to inject additional custom checks.

class TemporalAlignmentMixin(/, *args, **kwargs)

Bases: object

Generic class for testing temporal alignment methods.

data_interface_cls: type[BaseDataInterface]

interface_kwargs: dict

save_directory: Path = PosixPath('/tmp/tmpdjox0qf0')

conversion_options: dict | None = None

maxDiff = None

setup_interface(request)

setup_default_conversion_options()

setUpFreshInterface()

Protocol for creating a fresh instance of the interface.

check_interface_get_original_timestamps()

Just to ensure each interface can call .get_original_timestamps() without an error raising.

Also, that it always returns non-empty.

check_interface_get_timestamps()

Just to ensure each interface can call .get_timestamps() without an error raising.

Also, that it always returns non-empty.

check_interface_set_aligned_timestamps()

Ensure that internal mechanisms for the timestamps getter/setter work as expected.

check_shift_timestamps_by_start_time()

Ensure that internal mechanisms for shifting timestamps by a starting time work as expected.

check_interface_original_timestamps_inmutability()

Check aligning the timestamps for the interface does not change the value of .get_original_timestamps().

check_nwbfile_temporal_alignment()

Check the temporally aligned timing information makes it into the NWB file.

test_interface_alignment(setup_interface)

class ImagingExtractorInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

data_interface_cls: type[BaseImagingExtractorInterface]

optical_series_name: str = 'TwoPhotonSeries'

check_read_nwb_backends: tuple[str, ...] = ('hdf5',)

test_metadata_old_list_format(setup_interface)

check_extracted_metadata_old_list_format(metadata: dict)

Override this method to make assertions about extracted metadata in old list-based format.

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

check_nwbfile_temporal_alignment()

Check the temporally aligned timing information makes it into the NWB file.

class SegmentationExtractorInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

data_interface_cls: BaseSegmentationExtractorInterface

test_metadata_old_list_format(setup_interface)

check_extracted_metadata_old_list_format(metadata: dict)

Override this method to make assertions about extracted metadata in old list-based format.

check_read(nwbfile_path: str)

class RecordingExtractorInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

Generic class for testing any recording interface.

data_interface_cls: type[BaseRecordingExtractorInterface]

is_lfp_interface: bool = False

test_metadata_old_list_format(setup_interface)

check_extracted_metadata_old_list_format(metadata: dict)

Override this method to make assertions about extracted metadata in old list-based format.

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

check_interface_set_aligned_timestamps()

Ensure that internal mechanisms for the timestamps getter/setter work as expected.

check_interface_set_aligned_segment_timestamps()

check_shift_timestamps_by_start_time()

Ensure that internal mechanisms for shifting timestamps by a starting time work as expected.

check_shift_segment_timestamps_by_starting_times()

check_interface_original_timestamps_inmutability()

Check aligning the timestamps for the interface does not change the value of .get_original_timestamps().

test_interface_alignment(setup_interface)

class SortingExtractorInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

data_interface_cls: type[BaseSortingExtractorInterface]

associated_recording_cls: type[BaseRecordingExtractorInterface] | None = None

associated_recording_kwargs: dict | None = None

setUpFreshInterface()

Protocol for creating a fresh instance of the interface.

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

check_interface_set_aligned_segment_timestamps()

check_shift_segment_timestamps_by_starting_times()

test_interface_alignment(setup_interface)

class AudioInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

A mixin for testing Audio interfaces.

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

test_interface_alignment()

class VideoInterfaceMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

A mixin for testing Video interfaces.

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

check_interface_set_aligned_timestamps()

Ensure that internal mechanisms for the timestamps getter/setter work as expected.

check_shift_timestamps_by_start_time()

Ensure that internal mechanisms for shifting timestamps by a starting time work as expected.

check_set_aligned_segment_starting_times()

check_interface_original_timestamps_inmutability()

Check aligning the timestamps for the interface does not change the value of .get_original_timestamps().

class MedPCInterfaceMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

A mixin for testing MedPC interfaces.

test_metadata()

Test the dict-based metadata, which is the format every interface will emit.

See catalystneuro/neuroconv#1557 for discussion on what get_metadata() should return (provenance vs convenience).

Dual-mode interfaces (those that still expose the old list-based format) opt into the dict format via use_new_metadata_format=True. Dict-only interfaces return it unconditionally from get_metadata().

test_conversion_options_schema_valid()

test_metadata_schema_valid()

test_no_metadata_mutation()

Ensure the metadata object is not altered by add_to_nwbfile method.

check_metadata_schema_valid()

check_conversion_options_schema_valid()

check_metadata()

check_no_metadata_mutation(metadata: dict)

Ensure the metadata object was not altered by add_to_nwbfile method.

check_run_conversion_with_backend_configuration(nwbfile_path: str, metadata: dict, backend: Literal['hdf5', 'zarr'] = 'hdf5')

check_conversion_in_nwbconverter(metadata: dict)

Build through an NWBConverter without writing; the written file is checked from the interface path.

test_all_conversion_checks(metadata: dict)

Write the interface out and validate what lands on disk, once per backend.

run_conversion resolves the default backend configuration internally, so passing one explicitly writes the same file; that equivalence is covered once on a mock interface in tests/test_minimal/test_interfaces_run_conversion.py.

check_interface_get_original_timestamps(medpc_name_to_info_dict: dict)

Just to ensure each interface can call .get_original_timestamps() without an error raising.

Also, that it always returns non-empty.

check_interface_get_timestamps()

Just to ensure each interface can call .get_timestamps() without an error raising.

Also, that it always returns non-empty.

check_interface_set_aligned_timestamps(medpc_name_to_info_dict: dict)

Ensure that internal mechanisms for the timestamps getter/setter work as expected.

check_shift_timestamps_by_start_time(medpc_name_to_info_dict: dict)

Ensure that internal mechanisms for shifting timestamps by a starting time work as expected.

check_interface_original_timestamps_inmutability(medpc_name_to_info_dict: dict)

Check aligning the timestamps for the interface does not change the value of .get_original_timestamps().

test_interface_alignment(medpc_name_to_info_dict: dict)

class MiniscopeImagingInterfaceMixin(/, *args, **kwargs)

Bases: ImagingExtractorInterfaceTestMixin

A mixin for testing Miniscope Imaging interfaces.

optical_series_name: str = 'OnePhotonSeries'

check_read_nwb_backends: tuple[str, ...] = ('hdf5', 'zarr')

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

class TDTFiberPhotometryInterfaceMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

Mixin for testing TDT Fiber Photometry interfaces.

test_metadata()

Test the dict-based metadata, which is the format every interface will emit.

See catalystneuro/neuroconv#1557 for discussion on what get_metadata() should return (provenance vs convenience).

Dual-mode interfaces (those that still expose the old list-based format) opt into the dict format via use_new_metadata_format=True. Dict-only interfaces return it unconditionally from get_metadata().

test_metadata_schema_valid()

test_conversion_options_schema_valid()

test_no_metadata_mutation()

Ensure the metadata object is not altered by add_to_nwbfile method.

check_metadata()

check_metadata_schema_valid()

check_conversion_options_schema_valid()

check_no_metadata_mutation(metadata: dict)

Ensure the metadata object was not altered by add_to_nwbfile method.

check_run_conversion_with_backend_configuration(nwbfile_path: str, metadata: dict, backend: Literal['hdf5', 'zarr'] = 'hdf5')

check_conversion_in_nwbconverter(metadata: dict)

Build through an NWBConverter without writing; the written file is checked from the interface path.

test_all_conversion_checks(metadata: dict)

Write the interface out and validate what lands on disk, once per backend.

run_conversion resolves the default backend configuration internally, so passing one explicitly writes the same file; that equivalence is covered once on a mock interface in tests/test_minimal/test_interfaces_run_conversion.py.

check_interface_get_original_timestamps()

Just to ensure each interface can call .get_original_timestamps() without an error raising.

Also, that it always returns non-empty.

check_interface_get_timestamps()

Just to ensure each interface can call .get_timestamps() without an error raising.

Also, that it always returns non-empty.

check_interface_set_aligned_timestamps()

Ensure that internal mechanisms for the timestamps getter/setter work as expected.

check_shift_timestamps_by_start_time()

Ensure that internal mechanisms for shifting timestamps by a starting time work as expected.

check_interface_original_timestamps_inmutability()

Check aligning the timestamps for the interface does not change the value of .get_original_timestamps().

test_interface_alignment()

class PoseEstimationInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin

Generic class for testing any pose estimation interface.

Format-specific assertions belong in run_custom_checks. TemporalAlignmentMixin is not a base because the pose interfaces’ alignment methods are on the way out; a child that wants them adds it.

check_read_nwb(nwbfile_path: str)

Every container the metadata declares is in the file, named and shaped as the metadata says.

test_metadata_propagation(setup_interface)

Every editable name and description under metadata["Pose"] reaches the written objects.

The interface’s own metadata is edited and handed back, so this covers the whole addressing chain: metadata_key to the container entry, its two cross-references to the skeleton and the device, and each keypoint to its series entry.

class FiberPhotometryInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin, TemporalAlignmentMixin

Shared tests for single-series fiber photometry interfaces.

This mixin is the contract between the expected values a child supplies by hand — the response-series data and its timing, which every child determines independently for its own format/file — and how those values surface in the NWB file, which is uniform across all interfaces built on BaseFiberPhotometryInterface and therefore lives here. A child only declares expected_response_series_data and the expected timing (expected_rate + expected_starting_time for a regular series, or expected_timestamps for an irregular one); it does not reimplement check_read_nwb. The response-series expectations are deliberately not derived from the interface’s own reading methods (that would be circular); they are hand-supplied literals. The FiberPhotometryTable / device / indicator assertions instead validate the metadata → NWB mapping, and only run when the metadata actually carries a FiberPhotometryTable — with the bare default an interface writes a lone response series and nothing else. Format idiosyncrasies (e.g. where a session start time comes from) belong in a small dedicated override or unit test.

expected_response_series_data: ndarray

Hand-supplied expected samples of the written FiberPhotometryResponseSeries. With a small stub_samples in conversion_options this is a short, readable literal.

expected_starting_time: float | None = None

set expected_rate + expected_starting_time for a regularly sampled series, or expected_timestamps for an irregular one.

Type:

Expected timing

expected_rate: float | None = None

expected_timestamps: ndarray | None = None

expected_unit: str = 'a.u.'

Expected unit of the written series. Unit is a property of the data (not editable metadata), set when the series is built; uncalibrated fiber photometry defaults to “a.u.”.

check_read_nwb(nwbfile_path: str)

Read the produced NWB file and compare it to the interface.

class EventsInterfaceTestMixin(/, *args, **kwargs)

Bases: DataInterfaceTestMixin

Shared tests for the interfaces built on BaseEventsInterface.

A subclass sets data_interface_cls and interface_kwargs and inherits the schema, metadata and round-trip tests of DataInterfaceTestMixin, with check_read_nwb asserting what is true of every events interface whatever its source: the written tables carry the times get_event_times reports. A subclass may also set event_names to write under the names a user would give the types, in which case the round trip runs, and is checked, under those names. Nothing here touches alignment. Nothing here reads the source directly either, so a subclass that wants to pin the actual times of its fixture states them in its own check_read_nwb, calling super().check_read_nwb first.

event_names: dict[str, str] = {}

event_type_source_id to event_name. Empty means the interface’s own names are written.

edit_metadata(metadata: dict) → dict

Override this to edit the interface’s metadata before it is written, the way a user would.

check_read_nwb(nwbfile_path: str)

Each type’s rows in the written file carry the times get_event_times reports for it.

Mock Interfaces

class MockInterface(verbose: bool = False, **source_data)

Bases: BaseDataInterface

A mock interface for testing basic command passing without side effects.

get_metadata() → DeepDict

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None, add_subject: bool = False)

Add a mock subject to the NWBFile when asked to, and nothing otherwise.

The one conversion option this interface takes, so that a test can assert an option reached it by reading the file it wrote rather than by reading state off the interface.

class MockTimeSeriesInterface(*, num_channels: int = 4, sampling_frequency: float = 30000.0, duration: float = 1.0, seed: int = 0, verbose: bool = False, metadata_key: str = 'TimeSeries')

Bases: BaseDataInterface

A mock TimeSeries interface for testing purposes.

This interface uses pynwb’s mock_TimeSeries to create synthetic time series data without only pynwb as a dependency.

Initialize a mock TimeSeries interface.

Parameters:

• num_channels (int, optional) – Number of channels to generate, by default 4.

• sampling_frequency (float, optional) – Sampling frequency in Hz, by default 30,000.0 Hz.

• duration (float, optional) – Duration of the data in seconds, by default 1.0.

• seed (int, optional) – Seed for the random number generator, by default 0.

• verbose (bool, optional) – Control verbosity, by default False.

• metadata_key (str, optional) – Key for the TimeSeries metadata in the metadata dictionary, by default “TimeSeries”.

get_metadata() → DeepDict

Get metadata for the TimeSeries interface.

Returns:

The metadata dictionary containing NWBFile and TimeSeries metadata.

Return type:

dict

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None)

Add mock TimeSeries data to an NWB file.

Parameters:

• nwbfile (NWBFile) – The NWB file to which the TimeSeries data will be added.

• metadata (dict, optional) – Metadata dictionary. If None, uses default metadata.

class MockBehaviorEventInterface(event_times: list | numpy.ndarray | None = None)

Bases: BaseTemporalAlignmentInterface

A mock behavior event interface for testing purposes.

Initialize the interface with event times for behavior.

Parameters:

event_times (list of floats, optional) – The event times to set as timestamps for this interface. The default is the array [1.2, 2.3, 3.4] to simulate a time series similar to the MockSpikeGLXNIDQInterface.

classmethod get_source_schema() → dict

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

get_original_timestamps() → ndarray

Get the original event times before any alignment or transformation.

Returns:

The original event times as a NumPy array.

Return type:

np.ndarray

get_timestamps() → ndarray

Get the current (possibly aligned) event times.

Returns:

The current event times as a NumPy array, possibly modified after alignment.

Return type:

np.ndarray

set_aligned_timestamps(aligned_timestamps: ndarray)

Set the event times after alignment.

Parameters:

aligned_timestamps (np.ndarray) – The aligned event timestamps to update the internal event times.

add_to_nwbfile(nwbfile: NWBFile, metadata: dict)

Add the event times to an NWBFile as a DynamicTable.

Parameters:

• nwbfile (NWBFile) – The NWB file to which the event times will be added.

• metadata (dict) – Metadata to describe the event times in the NWB file.

Notes

This method creates a DynamicTable to store event times and adds it to the NWBFile’s acquisition.

class MockEventsInterface(*, metadata_key: str | None = None, num_event_types: int = 1, num_events: int = 4, event_extent: Literal['point event', 'event with duration'] = 'point event', event_payload: Literal['timestamps only', 'single value', 'single value variable length', 'multi value'] = 'timestamps only', verbose: bool = False)

Bases: BaseEventsInterface

A configurable mock events interface for exercising the EventsTable writer without a real acquisition format.

Generates num_event_types synthetic event types, each keyed by its own id ("events" for a single type, else "events_0" .. "events_{N-1}") and, by default, its own table. Their shape is set by two taxonomy axes describing the generated data: event_extent (point vs event with duration) and event_payload (timestamps only / a single categorical value / a multi-value struct); both apply to every type. Timestamps are staggered across types so pooling several into one table interleaves in time. Data is deterministic (no seed needed). Everything else a test exercises, renaming a column, merging types into one table (repoint their table_metadata_key), dropping the meanings map, lives in the returned metadata and is driven by editing it, not by a constructor flag.

Initialize a mock events interface.

Parameters:

• metadata_key (str, optional) – The key under metadata["Events"] namespacing this interface’s event_types. If None (default), "mock_events" is used.

• num_event_types (int, optional) – How many event types (streams) to generate, by default 1. Each gets its own id and, by default, its own table; a test merges them by repointing their table_metadata_key at a shared table.

• num_events (int, optional) – Number of events (timestamps) generated per event type, by default 4.

• event_extent ({“point event”, “event with duration”}, optional) – The temporal extent of the generated events (the taxonomy’s Extent axis). "point event" (default) generates timestamp-only events; "event with duration" gives each event a duration, so the writer adds a duration column. Applies to every event type.

• event_payload ({“timestamps only”, “single value”, “single value variable length”, “multi value”}, optional) – The payload carried per event (the taxonomy’s Payload axis). "timestamps only" (default) is a timestamp-only event with no value column; "single value" carries one categorical field (a labeled column with a MeaningsTable); "single value variable length" carries that same one field, but each of its cells holds several values rather than one, which the writer turns into a ragged column: an event tagged with two conditions at once, or a behavior scored with two qualifiers. The cells vary in length, including the empty one, so it exercises the fill a row with nothing to say gets. "multi value" carries a three-field struct that fans into three columns on the same rows, one per way the writer treats a value column: outcome (labels and meanings, so a MeaningsTable), cue (labels but nothing to explain, so no MeaningsTable), and amplitude (raw numeric values). Applies to every event type.

• verbose (bool, optional) – Whether to print status messages, by default False.

get_event_type_source_ids() → list[str]

Return the identifiers of the event types this interface reads, in the order it reports them.

The handles get_event_times() takes, and the keys of the metadata’s event_types block, which get_metadata() builds from this list. For a signal-encoded interface they are what detection_configuration resolves to, so a spec carrying an event_name is addressed by that name; for a pre-extracted one they are the source’s own handles for its event types.

Subclasses that can list their types from a header or a configuration override this so that listing them reads no events. This default reads the source.

Returns:

The event type identifiers.

Return type:

list of str

get_metadata() → DeepDict

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

class MockSignalEncodedEventsInterface(*, digital_line_waveforms: dict[int, Union[Literal['pulses', 'idle', 'unclosed_pulses'], tuple[str, Literal['pulses', 'idle', 'unclosed_pulses']]]] | None = None, analog_waveforms: dict[str, Literal['levels', 'noisy_two_level']] | None = None, detection_configuration: dict | None = None, duration: float = 1.0, num_events: int = 4, sampling_frequency: float = 1000.0, sampling: Literal['regular', 'irregular'] = 'regular', metadata_key: str | None = None, verbose: bool = False)

Bases: BaseEventsInterface

A mock signal-encoded events interface: a synthetic digital word, real derivation machinery.

Where MockEventsInterface hands the writer finished event records, this one starts a step earlier, from a sampled signal that still has to be discretized, so it exercises the part of the stack every signal-encoded interface shares: the detection_configuration grammar, the conditioning and detection split in neuroconv.tools.signal_processing, and the frame-to-seconds adapter. Only discovery is faked; everything after it is the shipped code path.

It speaks the packed-word dialect deliberately. One line per signal is the degenerate shape and cannot exercise one-signal-to-many, so it would bless the wrong abstraction; a word whose bits are carved out by bits is the general case that Intan and the National Instruments data acquisition (NIDQ) board both need.

digital_line_waveforms is the core knob and is the synthetic word: it says which bit positions the format recorded and what each line does. detection_configuration then says what the user carves out of it. That existence-versus-selection split is what makes selection, defaults and absent-bit errors testable. Configuration describes what to generate; the mock never takes data arrays.

analog_waveforms adds continuous signals alongside the word. They were originally planned as a separate mock, on the grounds that cutting a continuous trace is distinct enough from the bits carve to test apart from it. They live here because the conditioning machinery turned out to be shared rather than parallel: a given cut and a derived one are the same binarize in the same _condition_signal(), so a mock that exercises one and not the other leaves shipped code with no end-to-end coverage. Hysteresis, the genuinely analog-only knob, is still unbuilt and is what a separate mock would be for.

Initialize a mock signal-encoded events interface.

Parameters:

• digital_line_waveforms (dict, optional) – The synthetic word: {bit position: waveform kind}, or {bit position: (line name, waveform kind)} to name the line. The keys are the recorded bit inventory, reaching the validator as the word descriptor’s bits, and they need not be contiguous, so a configuration naming a bit the word does not carry can be exercised in the gap as well as past the end. No real fixture can state the gap case, since every .nidq.meta anyone has declares niXDChans1=0:7. A named line becomes that event type’s identifier under the default configuration (the event_name route, rule 3); an unnamed one falls to the derived form, word_bit0_high_period. Naming is what keeps the default legible, at the price of the default no longer exercising derivation, so a test that cares about derived identifiers passes bare waveform kinds. Each waveform kind is one of:

  • "pulses" (the ordinary line): num_events complete pulses, which detection then reads four ways.

  • "idle": no edges at all, a line that was recorded and never fired, which is the zero-row table path and is unreachable from a "pulses" line under any reading.

  • "unclosed_pulses": num_events pulses whose last one stays high to the end, which is the NaN-duration path, kept separate so not every durative test carries a NaN.

  Defaults to {0: ("lick", "pulses"), 1: ("reward", "idle")}: one line that fires and one recorded line that never did, the second being the zero-row table path.

• analog_waveforms (dict, optional) – Continuous signals to expose alongside the word, {signal_source_id: waveform kind}. Each key is a signal_source_id, naming a signal of kind "analog" that detection_configuration then addresses the way it addresses "word"; the caller picks it, since a mock discovers nothing from a file. It names a signal, not an event type, though a signal given a single spec keeps its signal_source_id as that event type’s identifier. A digital line is not one of these, being a bit inside the single packed word rather than a signal of its own, and "word" itself is reserved. Each value is one of:

  • "levels": a trace stepping through four amplitudes, which no edge reading can read without being told where to cut, so it is what a given binarize cut point needs.

  • "noisy_two_level": a trace that is conceptually a line and numerically is not, sitting near two amplitudes with jitter on every sample, which is what binarize exists for.

  Defaults to none, keeping the mock digital-only unless a test asks otherwise.

• detection_configuration (dict, optional) – What to carve out of the word, exactly as on a real interface. If None (default), every recorded bit becomes its own event type at high_period, which is lossless and assumes the lines are independent.

• duration (float, optional) – Signal length in seconds, by default 1.0.

• num_events (int, optional) – Pulses generated per active line, by default 4.

• sampling_frequency (float, optional) – Samples per second, by default 1000.0. With duration this fixes the frame count, and it is what makes timestamps land in seconds rather than frames.

• sampling ({“regular”, “irregular”}, optional) – The clock. "regular" (default) steps by 1 / sampling_frequency. "irregular" keeps the frame count and stretches one gap, which is the only way to tell a duration read from the clock apart from one estimated off a median sampling period. No real fixture in the suite samples irregularly.

• metadata_key (str, optional) – The key under metadata["Events"] namespacing this interface’s event_types. If None (default), "mock_signal_encoded_events" is used.

• verbose (bool, optional) – Whether to print status messages, by default False.

get_event_type_source_ids() → list[str]

The event types the configuration resolves to, read from nothing.

SIGNAL_SOURCE_ID = 'word'

get_metadata() → DeepDict

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

class MockFiberPhotometryInterface(*, excitation_wavelengths_in_nm: float | list[float] = 470.0, num_fibers: int = 1, num_samples: int = 100, sampling_frequency: float = 100.0, seed: int = 0, metadata_key: str | None = None, verbose: bool = False)

Bases: BaseFiberPhotometryInterface

A mock acquisition fiber photometry interface backed by synthetic data.

Writes one FiberPhotometryResponseSeries from a synthetic trace, so the ndx-fiber-photometry write/read path is exercised with no data on disk.

Initialize a mock fiber photometry interface.

Parameters:

• excitation_wavelengths_in_nm (float or list of float, default: 470.0) – The excitation wavelength(s) this interface’s series carries, one source stream each. ndx-fiber-photometry recommends one series per excitation/emission wavelength, so the default is a single wavelength and a second one is a second interface writing its own series into the same table. Passing a list aggregates over the wavelength axis instead, which asserts that they share a clock: true of a frequency-multiplexed (lock-in) rig where every LED is on at once, false of a time-multiplexed one where they alternate.

• num_fibers (int, default: 1) – How many fibers the series carries, one column per fiber. Columns are wavelength-major, so two wavelengths and two fibers give [w0f0, w0f1, w1f0, w1f1], and fiber_photometry_table_region has to list its row keys in that order. A single fiber reads as a 1-D array, several as (num_samples, num_fibers), which is the shape a real multi-fiber acquisition store returns.

• num_samples (int, default: 100) – Number of samples in the synthetic response series.

• sampling_frequency (float, default: 100.0) – Sampling frequency (Hz) of the synthetic response series.

• seed (int, default: 0) – Seed for the synthetic data.

• metadata_key (str, optional) – Override the response-series metadata key (default derived from the wavelengths).

• verbose (bool, default: False) – Whether to print status messages.

get_metadata() → DeepDict

Return the base metadata with a fixed session start time; no fiber photometry provenance.

class MockSpikeGLXNIDQInterface(signal_duration: float = 7.0, ttl_times: list[list[float]] | None = None, ttl_duration: float = 1.0)

Bases: SpikeGLXNIDQInterface

A mock SpikeGLX interface for testing purposes.

Define a mock SpikeGLXNIDQInterface by overriding the recording extractor to be a mock TTL signal.

Parameters:

• signal_duration (float, default: 7.0) – The number of seconds to simulate.

• ttl_times (list of lists of floats, optional) – The times within the signal_duration to trigger the TTL pulse for each channel. The outer list is over channels, while each inner list is the set of TTL times for each specific channel. The default generates 8 channels with periodic on/off cycle (which start in the ‘off’ state) each of which is of length ttl_duration with a 0.1 second offset per channel.

• ttl_duration (float, default: 1.0) – How long the TTL pulses stays in the ‘on’ state when triggered, in seconds.

ExtractorName = 'NumpyRecording'

classmethod get_source_schema() → dict

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

class MockRecordingInterface(*args, num_channels: int = 4, sampling_frequency: float = 30000.0, durations: tuple[float, ...] = (1.0,), seed: int = 0, verbose: bool = False, es_key: str | None = None, metadata_key: str | None = None, set_probe: bool = False, calibration: Literal['unknown', 'uniform', 'heterogeneous_gains', 'heterogeneous_offsets'] = 'uniform')

Bases: BaseRecordingExtractorInterface

An interface with a spikeinterface recording object for testing purposes.

General interface for OpenEphys data. It works for both the legacy and the binary format.

For “legacy” format (.continuous files) the interface redirects to OpenEphysLegacyRecordingInterface. For “binary” format (.dat files) the interface redirects to OpenEphysBinaryRecordingInterface.

Parameters:

• folder_path (DirectoryPath) – Path to OpenEphys directory (.continuous or .dat files).

• stream_name (str, optional) – The name of the recording stream. When the recording stream is not specified the channel stream is chosen if available. When channel stream is not available the name of the stream must be specified.

• block_index (int, optional, default: None) – The index of the block to extract from the data.

• verbose (bool, default: False)

• es_key (str, default: “ElectricalSeries”)

• metadata_key (str, optional) – Key that indexes this interface’s entries in the dict-based metadata. Defaults to "open_ephys_recording".

classmethod get_extractor_class()

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = True) → DeepDict

Get metadata for the recording interface.

Returns:

The metadata dictionary containing NWBFile metadata with session start time.

Return type:

dict

class MockSortingInterface(num_units: int = 4, sampling_frequency: float = 30000.0, durations: tuple[float, ...] = (1.0,), seed: int = 0, verbose: bool = False)

Bases: BaseSortingExtractorInterface

A mock sorting extractor interface for generating synthetic sorting data.

Parameters:

• num_units (int, optional) – Number of units to generate, by default 4.

• sampling_frequency (float, optional) – Sampling frequency of the generated data in Hz, by default 30,000.0 Hz.

• durations (tuple of float, optional) – Durations of the segments in seconds, by default (1.0,).

• seed (int, optional) – Seed for the random number generator, by default 0.

• verbose (bool, optional) – Control whether to display verbose messages during writing, by default True.

classmethod get_extractor_class()

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata() → DeepDict

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

class MockImagingInterface(num_samples: int = 30, num_rows: int = 10, num_columns: int = 10, sampling_frequency: float = 30, dtype: str = 'uint16', verbose: bool = False, seed: int = 0, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', metadata_key: str | None = None)

Bases: BaseImagingExtractorInterface

A mock imaging interface for testing purposes.

Parameters:

• num_samples (int, optional) – The number of samples (frames) in the mock imaging data, by default 30.

• num_rows (int, optional) – The number of rows (height) in each frame of the mock imaging data, by default 10.

• num_columns (int, optional) – The number of columns (width) in each frame of the mock imaging data, by default 10.

• sampling_frequency (float, optional) – The sampling frequency of the mock imaging data in Hz, by default 30.

• dtype (str, optional) – The data type of the generated imaging data (e.g., ‘uint16’), by default ‘uint16’.

• seed (int, optional) – Random seed for reproducibility, by default 0.

• photon_series_type (Literal[“OnePhotonSeries”, “TwoPhotonSeries”], optional) – The type of photon series for the mock imaging data, either “OnePhotonSeries” or “TwoPhotonSeries”, by default “TwoPhotonSeries”.

• verbose (bool, default False) – controls verbosity

classmethod get_extractor_class()

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = True) → DeepDict

Retrieve the metadata for the imaging data.

Parameters:

use_new_metadata_format (bool, default: True) – When False, returns the old list-based metadata format (backward compatible). When True, returns only NWBFile-level metadata (session_description, identifier, etc.) without ophys keys. Ophys defaults are filled by add_imaging_to_nwbfile() internally.

Returns:

Dictionary containing metadata. When use_new_metadata_format is False, includes device information, imaging plane details, and photon series configuration. When True, includes only NWBFile basics.

Return type:

DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, *args, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, parent_container: Literal['acquisition', 'processing/ophys'] = 'acquisition', stub_test: bool = False, always_write_timestamps: bool = False, iterator_type: str | None = 'v2', iterator_options: dict | None = None)

Add imaging data to the NWB file.

This method demonstrates the *args pattern for deprecating positional arguments while maintaining schema validation for keyword-only arguments.

Parameters:

• nwbfile (NWBFile) – The NWB file where the imaging data will be added.

• metadata (dict, optional) – Metadata for the NWBFile, by default None.

• photon_series_type ({“TwoPhotonSeries”, “OnePhotonSeries”}, optional) – The type of photon series to be added, by default “TwoPhotonSeries”.

• photon_series_index (int, optional) – The index of the photon series in the provided imaging data, by default 0.

• parent_container ({“acquisition”, “processing/ophys”}, optional) – Specifies the parent container to which the photon series should be added.

• stub_test (bool, optional) – If True, only writes a small subset of frames for testing purposes, by default False.

• always_write_timestamps (bool, optional) – Whether to always write timestamps, by default False.

• iterator_type ({“v2”, None}, default: “v2”) – The type of iterator for chunked data writing.

• iterator_options (dict, optional) – Options for controlling the iterative write process.

class MockSegmentationInterface(num_rois: int = 10, num_samples: int = 30, num_rows: int = 25, num_columns: int = 25, sampling_frequency: float = 30.0, has_summary_images: bool = True, has_raw_signal: bool = True, has_dff_signal: bool = True, has_deconvolved_signal: bool = True, has_neuropil_signal: bool = True, seed: int = 0, verbose: bool = False, metadata_key: str | None = None)

Bases: BaseSegmentationExtractorInterface

A mock segmentation interface for testing purposes.

Parameters:

• num_rois (int, optional) – number of regions of interest, by default 10.

• num_samples (int, optional) – number of samples (frames), by default 30.

• num_rows (int, optional) – number of rows in the hypothetical video from which the data was extracted, by default 25.

• num_columns (int, optional) – number of columns in the hypothetical video from which the data was extracted, by default 25.

• sampling_frequency (float, optional) – sampling frequency of the hypothetical video from which the data was extracted, by default 30.0.

• has_summary_images (bool, optional) – whether the dummy segmentation extractor has summary images or not (mean and correlation).

• has_raw_signal (bool, optional) – whether a raw fluorescence signal is desired in the object, by default True.

• has_dff_signal (bool, optional) – whether a relative (df/f) fluorescence signal is desired in the object, by default True.

• has_deconvolved_signal (bool, optional) – whether a deconvolved signal is desired in the object, by default True.

• has_neuropil_signal (bool, optional) – whether a neuropil signal is desired in the object, by default True.

• seed (int, default 0) – seed for the random number generator, by default 0

• verbose (bool, optional) – controls verbosity, by default False.

• metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “mock_segmentation”.

classmethod get_extractor_class()

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = True) → DeepDict

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

class MockPoseEstimationInterface(num_samples: int = 1000, num_nodes: int = 3, seed: int = 0, sampling: Literal['regular', 'irregular'] = 'regular', verbose: bool = False, metadata_key: str = 'MockPoseEstimation', pose_estimation_metadata_key: str | None = None)

Bases: BasePoseEstimationInterface

A mock pose estimation interface for testing purposes.

Initialize a mock pose estimation interface.

Parameters:

• num_samples (int, optional) – Number of samples to generate, by default 1000.

• num_nodes (int, optional) – Number of nodes/body parts to track, by default 3.

• seed (int, optional) – Random seed for reproducible data generation, by default 0.

• sampling ({“regular”, “irregular”}, optional) – The clock. "regular" (default) steps at 30 Hz. "irregular" draws the samples out of a denser 30 Hz grid, which is the shape a SLEAP .slp has, since it labels a sparse selection of the video’s frames, and it is what makes the writer store a timestamps dataset rather than a rate.

• verbose (bool, optional) – Control verbosity, by default False.

• metadata_key (str, default: “MockPoseEstimation”) – Metadata key for this interface.

• pose_estimation_metadata_key (str, optional) – Deprecated. Renamed to metadata_key; passing it forwards the value to metadata_key and will be removed on or after February 2027.

display_name: str | None = 'Mock Pose Estimation'

keywords: tuple[str] = ('behavior', 'pose estimation', 'mock')

associated_suffixes: tuple[str] = []

info: str | None = 'Mock interface for pose estimation data testing.'

classmethod get_source_schema() → dict

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

get_original_timestamps() → ndarray

Get the original timestamps before any alignment.

get_timestamps() → ndarray

Get the current (possibly aligned) timestamps.

set_aligned_timestamps(aligned_timestamps: ndarray)

Set aligned timestamps.

get_metadata() → DeepDict

Name the objects after this interface’s key and add what the mock pretends its source records.

class MockExternalVideoInterface(file_paths: list[str] | None = None, num_frames: int = 100, frame_rate: float = 30.0, verbose: bool = False, *, metadata_key: str | None = None)

Bases: ExternalVideoInterface

A mock external video interface for testing purposes.

Overrides exactly one thing: what the container header says. The frame count and the frame rate are constructor arguments rather than reads, so a test can compose a video of any length into a conversion at no cost, and everything else runs the real interface’s course. In particular the timing is left unset, as it is on a freshly constructed real interface, so a single file writes a starting time and a rate while several files raise until the test says where they sit.

Nothing that reads the video itself is stubbed, only the header, so a method that decodes frames (get_original_timestamps, and set_aligned_segment_starting_times which goes through it) will fail here as it would on any missing file. Give the times directly with set_aligned_timestamps.

The paths land in external_file as they were passed and deliberately do not resolve, which is what keeps the file a mock produces from being mistaken for a publishable one; nwbinspector flags the dangling path, and that is the intent.

Initialize a mock external video interface.

Parameters:

• file_paths (list of str, optional) – The paths written to external_file; they do not have to exist. Defaults to a single "mock_video.mp4".

• num_frames (int, default: 100) – The frame count each file’s header reports, which backs num_samples and starting_frame.

• frame_rate (float, default: 30.0) – The frame rate each file’s header reports.

• verbose (bool, default: False) – If True, display verbose output.

• metadata_key (str, optional) – Snake_case key identifying this video’s entry under metadata["Behavior"]["ExternalVideos"]. Defaults to the stem-based key of the parent interface.

display_name: str | None = 'Mock Video'

keywords: tuple[str] = ('video', 'behavior', 'mock')

associated_suffixes: tuple[str] = ()

info: str | None = 'Mock interface for external video data testing.'

get_metadata() → DeepDict

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

class MockIcephysInterface(*, mode: Literal['voltage_clamp', 'current_clamp', 'izero'] = 'current_clamp', num_sweeps: int = 3, sweep_duration: float = 1.0, sampling_frequency: float = 10000.0, inter_sweep_interval: float = 0.0, starting_time: float = 0.0, sequence: str = 'run', stimulus_type: str | None = 'mock protocol', repetition: str | None = None, condition: str | None = None, metadata_key: str = 'mock', seed: int = 0, verbose: bool = False)

Bases: BaseDataInterface

A mock intracellular electrophysiology interface for testing purposes.

Writes one electrode’s synthetic response as a single continuous response series (the class chosen by the clamp mode, as a real interface does) plus one intracellular-recordings row per sweep, each addressing the sweep’s (start_index, count) sample range. That is the contract every icephys interface emits, so this exercises the format-independent machinery in neuroconv.tools.icephys (which reads those rows back to build the hierarchy tables and the sweep intervals) without any acquisition file. Combine several instances in a ConverterPipe for the multi-channel and multi-run cases: instances sharing a starting_time describe the same sweeps recorded on two electrodes (a dual patch), distinct ones place two runs on a single timeline.

Initialize a mock intracellular electrophysiology interface.

Parameters:

• mode ({“current_clamp”, “voltage_clamp”, “izero”}, default: “current_clamp”) – The clamp mode, which selects the response series class the same way a real interface does.

• num_sweeps (int, default: 3) – Number of sweeps, one intracellular-recordings row each.

• sweep_duration (float, default: 1.0) – Duration of every sweep, in seconds.

• sampling_frequency (float, default: 10000.0) – Sampling rate of the response series, in Hz.

• inter_sweep_interval (float, default: 0.0) – Dead time between the end of a sweep and the start of the next one, in seconds. The default of 0.0 leaves the samples regular, so the series is written with a uniform rate; a non-zero value makes them irregular, so it is written with explicit timestamps instead (the rule a real interface uses).

• starting_time (float, default: 0.0) – Time of the first sample, in seconds.

• sequence (str, default: “run”) – Run identity written to the sequence column of every row, the label that groups the rows into one sequential recording.

• stimulus_type (str, optional, default: “mock protocol”) – Value of the stimulus_type column, carried up to the sequential recording when aggregated. Pass None to omit the column, as an interface whose format describes no stimulus does.

• repetition (str, optional) – Label grouping this run’s sequential recording with others into a Repetitions entry. Written as a column only when given, as a real interface does.

• condition (str, optional) – Label grouping this run’s repetition with others into an ExperimentalConditions entry. Written as a column only when given.

• metadata_key (str, default: “mock”) – Identity of this interface’s electrode and response series in the metadata dict. Give combined instances distinct keys so each writes its own electrode and series.

• seed (int, default: 0) – Seed for the random number generator.

• verbose (bool, default: False) – Control verbosity.

get_metadata() → DeepDict

Get metadata for the intracellular electrophysiology interface.

Returns:

The metadata dictionary, with the device, electrode and response series entries keyed by metadata_key and cross-linked the way a real icephys interface links them.

Return type:

DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None)

Add the mock response series and its per-sweep intracellular-recordings rows to an NWB file.

Parameters:

• nwbfile (NWBFile) – The NWB file the series and rows are added to.

• metadata (dict, optional) – Metadata dictionary. If None, uses default metadata.

Mock TTL Signals

generate_mock_ttl_signal(signal_duration: float = 7.0, ttl_times: list | ndarray | None = None, ttl_duration: float = 1.0, sampling_frequency_hz: float = 25000.0, dtype: DTypeLike = 'int16', baseline_mean: int | float | None = None, signal_mean: int | float | None = None, channel_noise: int | float | None = None, random_seed: int | None = 0) → ndarray

Generate a synthetic signal of TTL pulses similar to those seen in .nidq.bin files using SpikeGLX.

Parameters:

• signal_duration (float, default: 7.0) – The number of seconds to simulate.

• ttl_times (array of floats, optional) – The times within the signal_duration to trigger the TTL pulse. In conjunction with the ttl_duration, these must produce disjoint ‘on’ intervals. The default generates a periodic 1 second on, 1 second off pattern.

• ttl_duration (float, default: 1.0) – How long the TTL pulse stays in the ‘on’ state when triggered, in seconds. In conjunction with the ttl_times, these must produce disjoint ‘on’ intervals.

• sampling_frequency_hz (float, default: 25,000.0) – The sampling frequency of the signal in Hz. The default is 25000 Hz; similar to that of typical .nidq.bin files.

• dtype (numpy data type or one of its accepted string input, default: “int16”) – The data type of the trace. Must match the data type of baseline_mean, signal_mean, and channel_noise, if any of those are specified. Recommended to be int16 for maximum efficiency, but can also be any size float to represent voltage scalings.

• baseline_mean (integer or float, depending on specified ‘dtype’, optional) – The average value for the baseline; usually around 0 Volts. The default is approximately 0.005645752 Volts, estimated from a real example of a TTL pulse in a .nidq.bin file.

• signal_mean (integer or float, optional) – Type depends on specified ‘dtype’. The average value for the signal; usually around 5 Volts. The default is approximately 4.980773925 Volts, estimated from a real example of a TTL pulse in a .nidq.bin file.

• channel_noise (integer or float, optional) – Type depends on specified ‘dtype’. The standard deviation of white noise in the channel. The default is approximately 0.002288818 Volts, estimated from a real example of a TTL pulse in a .nidq.bin file.

• random_seed (int or None, default: 0) – The seed to set for the numpy random number generator. Set to None to choose the seed randomly. The default is kept at 0 for generating reproducible outputs.

Returns:

trace – The synethic trace representing a channel with TTL pulses.

Return type:

numpy.ndarray

regenerate_test_cases(folder_path: Annotated[Path, PathType(path_type=dir)], regenerate_reference_images: bool = False)

Regenerate the test cases of the file included in the main testing suite, which is frozen between breaking changes.

Parameters:

• folder_path (PathType) – Folder to save the resulting NWB file in. For use in the testing suite, this must be the ‘/test_testing/test_mock_ttl/’ subfolder adjacent to the ‘test_mock_tt.py’ file.

• regenerate_reference_images (bool) – If true, uses the kaleido package with plotly (you may need to install both) to regenerate the images used as references in the documentation.

Mock Files

generate_path_expander_demo_ibl(folder_path: str | None = None) → None

Partially replicate the file structure of IBL data with dummy files for experimentation with LocalPathExpander. Specifically, it recreates the directory tree for the video files of the Steinmetz Lab’s data.

Parameters:

folder_path (str, optional) – Path to folder where the files are to be generated. If None, the current working directory will be used.