ezmsg.tools.chmeta#

Turning a structured ch coordinate axis into per-channel display names.

An AxisArray’s ch axis usually carries a structured array with one row per channel. What is in those rows depends on the acquisition system: an LSL or NWB source typically offers a label; a Blackrock source additionally offers bank and elec, which is what its users actually read off the front panel. A plot needs one string per channel, so something has to choose.

This module makes that choice explicit and configurable rather than hard-coding one system’s convention. label is the default because it is the field most sources populate and the one most likely to be meaningful to whoever recorded the data; a GUI that knows better can ask for other fields.

Functions

available_fields(ch_axis_data)[source]#

Field names present on a structured ch axis, for building a chooser.

Parameters:

ch_axis_data (ndarray | None)

Return type:

List[str]

channel_names(ch_axis_data, n_ch=None, *, fields=('label',), sep='-', fallback='ch{index}')[source]#

Per-channel display names from a structured ch axis.

Parameters:

  • ch_axis_data (ndarray | None) – The axis’s structured array, or None if the source provided no ch axis.

  • n_ch (int | None) – Channel count, used only when ch_axis_data is None or unstructured. Otherwise the axis’s own length governs.

  • fields (Sequence[str]) – Field names to join, in order. Fields absent from the dtype are skipped; fields present but empty for a given channel are skipped for that channel only, so a partially-populated column degrades per-row rather than for the whole array.

  • sep (str) – Joins the field values, e.g. ("bank", "elec") -> "A-1".

  • fallback (str) – Format string used when no requested field yields anything for a channel. {index} is the channel’s index.

Returns:

One name per channel. Never empty strings, so a caller can render the result without further guarding.

Return type:

List[str]

available_fields(ch_axis_data)[source]#

Field names present on a structured ch axis, for building a chooser.

Parameters:

ch_axis_data (ndarray | None)

Return type:

List[str]

channel_names(ch_axis_data, n_ch=None, *, fields=('label',), sep='-', fallback='ch{index}')[source]#

Per-channel display names from a structured ch axis.

Parameters:

  • ch_axis_data (ndarray | None) – The axis’s structured array, or None if the source provided no ch axis.

  • n_ch (int | None) – Channel count, used only when ch_axis_data is None or unstructured. Otherwise the axis’s own length governs.

  • fields (Sequence[str]) – Field names to join, in order. Fields absent from the dtype are skipped; fields present but empty for a given channel are skipped for that channel only, so a partially-populated column degrades per-row rather than for the whole array.

  • sep (str) – Joins the field values, e.g. ("bank", "elec") -> "A-1".

  • fallback (str) – Format string used when no requested field yields anything for a channel. {index} is the channel’s index.

Returns:

One name per channel. Never empty strings, so a caller can render the result without further guarding.

Return type:

List[str]