neurocarto.probe

class neurocarto.probe.ProbeDesp

A probe interface for GUI interaction between different probe implementations.

Some GUI view components may require specific operations, and they are defined in a Protocol. There are:

ProbeElectrodeDensityProtocol for providing density curves.
ProbePlotBlueprintProtocol for plotting blueprint category zones.
ProbePlotElectrodeProtocol for plotting electrode data.

Parameters:

M – channelmap, any class
E – electrode, subclass of ElectrodeDesp

STATE_UNUSED: ClassVar = 0: electrode default state

STATE_USED: ClassVar = 1: electrode is selected as readout channel

STATE_DISABLED: ClassVar = 2: electrode is disabled

CATE_UNSET: ClassVar = 0: electrode initial category

CATE_SET: ClassVar = 1: electrode pre-select category. Electrode must be selected

CATE_EXCLUDED: ClassVar = 2: electrode excluded category. Electrode must not be selected

CATE_LOW: ClassVar = 3: electrode low-priority category.

abstract property supported_type: dict[str, int]

All supported probe type.

Used in CartoApp. install_right_panel_views() for dynamic generating options.

Returns:: dict of {description: code}, where code is used in new_channelmap(code)

type_description(code)

Get the description for given channelmap code.

Read the content from supported_type.

Parameters:: code (int | None) – channelmap code
Returns:: channelmap description
Return type:: str | None

abstract property possible_states: dict[str, int]

Export electrode states.

Those states are used in CartoApp. install_right_panel_views() for generating buttons dynamically, which means only manual states need to be exported. The state such as STATE_DISABLED is programming update for remaining electrodes that users cannot change electrode as this state.

Returns:: dict of {description: state}
See:: all_possible_states()

state_description(state)

Get the description for given electrode state.

Read the content from possible_states.

Parameters:: state (int) – electrode state code
Returns:: electrode state description
Return type:: str | None

abstract property possible_categories: dict[str, int]

All possible exported electrode categories.

Those categories are used in CartoApp. install_right_panel_views() for generating buttons dynamically.

Returns:: dict of {description: category}
See:: all_possible_categories()

category_description(code)

Get the description for given electrode category code.

Read the content from possible_categories.

Parameters:: code (int) – electrode category code
Returns:: electrode category description
Return type:: str | None

classmethod all_possible_states()

All possible electrode states.

Note

It finds all class variable that its name starts with ‘STATE_*’.

Returns:: dict of {state_name: state_value}
Return type:: dict[str, int]

classmethod all_possible_categories()

All possible electrode categories.

Note

It finds all class variable that its name starts with ‘CATE_*’.

Returns:: dict of {category_name: category_value}
Return type:: dict[str, int]

extra_controls(config)

Probe specific controls.

Parameters:: config (CartoConfig) – application configurations.
Returns:: list of type of the probe-specific views.
Return type:: list[type[ViewBase]]

abstract property channelmap_file_suffix: list[str]

The filename extension for supported channelmap.

The first suffix in returned list is considered the primary format.

Returns:: list of file extensions, like [“.imro”] for the Neuropixel probe.

abstract load_from_file(file)

Load a channelmap file.

Parameters:

file (Path) – channelmap filepath

Returns:

channelmap instance

Raises:

IOError – If file is not supported.
FileNotFoundError – If file is not existed.
RuntimeError – errors when parsing the file.

Return type:

M

abstract save_to_file(chmap, file)

Save a channelmap into a file.

Parameters:

chmap (M) – channelmap instance
file (Path) – channelmap filepath

Raises:

IOError – If file suffix is not supported.
IOError – If target directory is not existed.
RuntimeError – errors when serializing the channelmap.

abstract channelmap_code(chmap)

Identify a given channelmap, and return the corresponding code.

Parameters:: chmap (Any | None) – Any instance. It could be a channelmap instance.
Returns:: a code from supported_type. None if chmap is unknown or is not supported.
Return type:: int | None

abstract new_channelmap(chmap)

Create a new, empty channelmap instance.

If you want to copy a channelmap instance, use copy_channelmap() instead.

Parameters:: chmap (int | str | M) – a code from supported_type or a channelmap instance as probe type.
Returns:: a channelmap instance
Return type:: M

abstract copy_channelmap(chmap)

Copy a channelmap instance, including properties of electrodes.

Parameters:: chmap (M) – channelmap instance as reference.
Returns:: a channelmap instance
Return type:: M

abstract channelmap_desp(chmap)

A description for displaying the status of a channelmap instance.

Parameters:: chmap (M | None) – a channelmap instance, or None when no probe (an initial description)
Returns:: description.
Return type:: str

abstract all_electrodes(chmap)

Get all possible electrode set for the given channelmap code.

Implement Node:: make sure the result is consistent in its ordering.

Parameters:: chmap (int | M) – a channelmap instance or a code from supported_type.
Returns:: a list of ElectrodeDesp
Return type:: list[E]

abstract all_channels(chmap, electrodes=None)

Get a list of a selected electrodes in the given channelmap.

Parameters:

chmap (M) – a channelmap instance
electrodes (Iterable[E] | None) – restrict electrode set that the return set is its subset.

Returns:

a list of ElectrodeDesp, keep in ordering by its channel identify (skip None electrodes).

Return type:

list[E]

abstract is_valid(chmap)

Is it a valid and completed channelmap?

A valid and completed channelmap means:

This channelmap is able to save into a file
no electrode pair will break the probe restriction (probe_rule()).
The saved file can be read by other software or machines without any error or any mis-located electrode.

Parameters:: chmap (M) – a channelmap instance
Returns:
Return type:: bool

get_electrode(electrodes, e)

Get an electrode from a set with a given identify e.

Parameters:

electrodes (Iterable[E]) – an electrode set
e (Hashable | E) – electrode identify, as same as ElectrodeDesp.:attr:~neurocarto.probe.ElectrodeDesp.electrode.

Returns:

found electrode in s. None if not found.

Return type:

E | None

abstract add_electrode(chmap, e, *, overwrite=False)

Add an electrode e into chmap.

An error raised when:

Either chmap or e is in incorrect state. For example, e is None.
chmap is complete, and it doesn’t allow to add any additional electrode.
chmap is incomplete, but it doesn’t allow to add e due to probe restriction.

It is better to raise an error instead of ignoring because an error can carry the message to frontend.

Parameters:

chmap (M) – a channelmap instance
e (E) – an electrode
overwrite – force add electrode

Raise:

any error means the action was failed.

abstract del_electrode(chmap, e)

Remove an electrode e from the chmap.

Parameters:

chmap (M) – a channelmap instance
e (E) – an electrode

Raise:

any error means the action was failed.

clear_electrode(chmap)

Remove all electrodes from the chmap.

Parameters:: chmap (M) – a channelmap instance

copy_electrode(electrodes)

Copy an electrode set, including ALL information for every electrode.

The default implement only consider simple case, so it won’t work once any following points break:

type E has no-arg __init__
type E has any attribute name start with ‘_’
type E overwrite __getattr__, __setattr__

Parameters:: electrodes (Sequence[E])
Returns:
Return type:: list[E]

abstract probe_rule(chmap, e1, e2)

Does electrode e1 and e2 can be used in the same time?

This method’s implementation should follow the rules in most cases:

probe_rule(M, e, e) should return False
probe_rule(M, e1, e2) == probe_rule(M, e2, e1)

Parameters:

chmap (M) – channelmap type. It is a reference.
e1 (E) – an electrode.
e2 (E) – an electrode.

Returns:

True when e1 and e2 are compatible.

Return type:

bool

invalid_electrodes(chmap, e, electrodes)

Collect the invalid electrodes that an electrode from electrodes will break the probe_rule() with the electrode e (or any electrode from e).

Note that e may also be contained in the result if e in electrodes.

Parameters:

chmap (M) – channelmap type. It is a reference.
e (E | Iterable[E]) – an electrode.
electrodes (Iterable[E]) – an electrode set.

Returns:

an invalid electrode set from electrodes.

Return type:

list[E]

abstract select_electrodes(chmap, blueprint, **kwargs)

Selecting electrodes based on the electrode blueprint.

Parameters:

chmap (M) – channelmap type. It is a reference.
blueprint (list[E]) – channelmap blueprint
kwargs – other parameters.

Returns:

generated channelmap

Return type:

M

abstract save_blueprint(blueprint)

Store blueprint, included all electrode information into a numpy array.

Parameters:: blueprint (list[E]) – blueprint.
Returns:: blueprint matrix.
Return type:: ndarray[tuple[int, …], dtype[int64]]

abstract load_blueprint(a, chmap)

Restore blueprint, included all electrode information from a numpy array a.

If chmap is a list[E], it indicates only restore the information only for this electrode subset.

Parameters:

a (str | Path | ndarray[tuple[int, ...], dtype[int64]]) – saved category matrix, or a saved ‘.npy’ file path
chmap (int | M | list[E]) – channelmap type, or an electrode set.

Returns:

blueprint

Return type:

list[E]

class neurocarto.probe.ElectrodeDesp

An electrode interface for GUI interaction between different electrode implementations.

s: int: shank

x: float: x position in um

y: float: y position in um

electrode: Hashable: electrode identify. It should be a hashable.

channel: Any: channel identify. It is used for display (str-able).

state: int = 0: electrode selecting state

category: int = 0: electrode selecting category.

copy(r, **kwargs)

A copy helper function to move data from r.

Parameters:

r (ElectrodeDesp) – copy reference electrode
kwargs – overwrite fields. If you want a deep copy for particular fields.

Returns:

self

Return type:

Self

neurocarto.probe.get_probe_desp(name)

Get probe describer.

Naming rules (finding in order):

a module path MODULE:NAME, import MODULE and use NAME.
(following rule does not specific which ProbeDesp subtype, find the first matched.)
a probe family name, which can be found in module neurocarto.probe_NAME.
a probe family name, which can be found in module neurocarto.NAME.
a module name, which can be found in module NAME.

Parameters:: name (str) – probe family name.
Returns:: type of ProbeDesp.
Raises:: RuntimeError – module not found; no ProbeDesp implementation found; not a ProbeDesp subtype.
See:: import_name()
Return type:: type[ProbeDesp]