API

Probe

class probeinterface.Probe(ndim: int = 2, si_units: str = 'um', name: str | None = None, serial_number: str | None = None, model_name: str | None = None, manufacturer: str | None = None)

Class to handle the geometry of one probe.

This class mainly handles contact positions, in 2D or 3D. Optionally, it can also handle the shape of the contacts and the shape of the probe.

add_probe_to_zarr_group(group: zarr.Group) → None

Serialize the probe’s data and structure to a specified Zarr group.

This method is used to save the probe’s attributes, annotations, and other related data into a Zarr group, facilitating integration into larger Zarr structures.

Parameters

groupzarr.Group

The target Zarr group where the probe’s data will be stored.

annotate(**kwargs)

Annotates the probe object.

Parameters

**kwargs : list of keyword arguments to add to the annotations (e.g., brain_area=”CA1”)

annotate_contacts(**kwargs)

Annotates the contacts of the probe.

Parameters

**kwargs : list of keyword arguments to add to the annotations (e.g., quality=[“good”, “bad”, …])

property contact_positions

The position of the center for each contact

copy()

Copy to another Probe instance.

Note: device_channel_indices are not copied and contact_ids are not copied

create_auto_shape(probe_type: tip' | 'rect' | 'circular = 'tip', margin: float = 20.0)

Create a planar contour automatically based on probe contact positions.

This function generates a 2D polygon that outlines the shape of the probe, adjusted by a specified margin. The resulting contour is set as the planar contour of the probe.

Parameters

probe_type{“tip”, “rect”, “circular”}, default: “tip”

The type of probe used to collect contact data:

• “tip”: Assumes a single-point contact probe. The generated contour is

a rectangle with a triangular “tip” extending downwards. * “rect”: Assumes a rectangular contact probe. The generated contour is a rectangle. * “circular”: Assumes a circular contact probe. The generated contour is a circle.

marginfloat, default: 20.0

The margin to add around the contact positions. The behavior varies by probe type:

• “tip”: The margin is added around the rectangular portion of the contour

and to the base of the tip. The tip itself is extended downwards by four times the margin value. * “rect”: The margin is added evenly around all sides of the rectangle. * “circular”: The margin is added to the radius of the circle.

Notes

This function is designed for 2D data only. If you have 3D data, consider projecting it onto a plane before using this method.

static from_dataframe(df: pandas.DataFrame) → Probe

Create Probe from a pandas.DataFrame see Probe.to_dataframe()

Parameters

dfpandas.DataFrame

The dataframe representation of the probe

Returns

probeProbe

The instantiated Probe object

static from_dict(d: dict) → Probe

Instantiate a Probe from a dictionary

Parameters

ddict

The dictionary representation of the probe

Returns

probeProbe

The instantiated Probe object

static from_numpy(arr: ndarray) → Probe

Create Probe from a complex numpy array see Probe.to_numpy()

Parameters

arrnp.array

The structured np.array representation of the probe

Returns

probeProbe

The instantiated Probe object

static from_zarr(folder_path: str | Path) → Probe

Deserialize the Probe object from a Zarr file located at the given folder path.

Parameters

folder_pathstr | Path

The path to the folder where the Zarr file is located.

Returns

Probe

An instance of the Probe class initialized with data from the Zarr file.

static from_zarr_group(group: zarr.Group) → Probe

Load a probe instance from a given Zarr group.

Parameters

groupzarr.Group

The Zarr group from which to load the probe.

Returns

Probe

An instance of the Probe class initialized with data from the Zarr group.

get_contact_count() → int

Return the number of contacts on the probe.

get_contact_vertices() → list

Return a list of contact vertices.

get_shank_count() → int

Return the number of shanks for this probe.

get_shanks()

Return the list of Shank objects for this Probe

get_slice(selection: ndarray[bool | int])

Get a copy of the Probe with a sub selection of contacts.

Selection can be boolean or by index

Parameters

selectionnp.array of bool or int (for index)

Either an np.array of bool or for desired selection of contacts or the indices of the desired contacts

Returns

sliced_probe: Probe

The sliced probe

move(translation_vector: np.array | list)

Translate the probe in one direction.

Parameters

translation_vectorlist or array

The translation vector in shape 2D or 3D

rotate(theta: float, center: list | np.ndarray | None = None, axis: 'xy' | 'yz' | 'xz' | None = None)

Rotate the probe around a specified axis.

Parameters

thetafloat

In degrees, anticlockwise/counterclockwise

centerarray | list | None, default: None

Center of rotation. If None, the center of probe is used

axis“xy” | “yz” | “xz” | None, default: None

Axis of rotation. It must be None for 2D probes It must be given for 3D probes

rotate_contacts(thetas: float | np.array[float] | list[float])

Rotate each contact of the probe. Internally, it modifies the contact_plane_axes.

Parameters

thetasfloat | array[float] | list[float]

Rotation angle in degrees. If scalar, then it is applied to all contacts.

set_contact_ids(contact_ids: np.array | list)

Set contact ids. Channel ids are converted to strings. Contact ids must be unique for the Probe and also for the ProbeGroup

Parameters

contact_idslist or array

Array with contact ids. If contact_ids are int or float they are converted to str

set_contacts(positions, shapes='circle', shape_params={'radius': 10}, plane_axes=None, contact_ids=None, shank_ids=None)

Sets contacts to a Probe.

This sets four attributes of the probe:

contact_positions, contact_shapes, contact_shape_params, _contact_plane_axes

Parameters

positionsarray (num_contacts, ndim)

Positions of contacts (2D or 3D depending on probe ‘ndim’).

shapes“circle” | “square” | “rect” | array, default: “circle”

Shape of each contact (‘circle’/’square’/’rect’).

shape_paramsdict or list of dict, default: {“radius”: 10}

Contains kwargs for shapes: * “radius” for circle * “width” for square, * “width/height” for rect

plane_axesnp.array (num_contacts, 2, ndim) | None, default: None

Defines the two axes of the contact plane for each electrode. The third dimension corresponds to the probe ndim (2d or 3d).

contact_ids: array[str] | None, default: None

Defines the contact ids for the contacts. If None, contact ids are not assigned.

shank_idsarray[str] | None, default: None

Defines the shank ids for the contacts. If None, then these are assigned to a unique Shank.

set_device_channel_indices(channel_indices: np.array | list)

Manually set the device channel indices.

If some channels are not connected or not recorded then channel should be set to “-1”

Parameters

channel_indicesarray[int] | list[int]

The device channel indices to set

set_planar_contour(contour_polygon: list)

Set the planar contour (the shape) of the probe.

Parameters

contour_polygonlist

List of contour points (2D or 3D depending on ndim)

set_shank_ids(shank_ids: np.array | list)

Set shank ids.

Parameters

shank_idslist or array

Array with shank ids, if int or float converted to strings

to_2d(axes: xy' | 'yz' | 'xz = 'xy')

Transform 3d probe to 2d probe.

Note: device_channel_indices are not copied.

Parameters

plane“xy” | “yz” | “xz”, default: “xy”

The plane on which the 2D probe is defined.

to_3d(axes: xy' | 'yz' | 'xz = 'xz')

Transform 2d probe to 3d probe.

Note: device_channel_indices are not copied.

Parameters

axes“xy” | “yz” | “xz”, default: “xz”

The axes that define the plane on which the 2D probe is defined. ‘xy’, ‘yz’ ‘, xz’

to_dataframe(complete: bool = False) → pandas.DataFrame

Export the probe to a pandas dataframe

Parameters

completebool, default: False

If True, export complete information about the probe, including the probe plane axis.

Returns

dfpandas.DataFrame

The dataframe representation of the probe

to_dict(array_as_list: bool = False) → dict

Create a dictionary of all necessary attributes. Useful for dumping and saving to json.

Parameters

array_as_listbool, default: False

If True, arrays are converted to lists

Returns

ddict

The dictionary representation of the probe

to_image(values: np.array | list, pixel_size: float = 0.5, num_pixel: Optional[int] = None, method: linear' | 'nearest' | 'cubic = 'linear', xlims: Optional[tuple] = None, ylims: Optional[tuple] = None) → tuple[np.ndarray, tuple, tuple]

Generated a 2d (image) from a values vector with an interpolation into a grid mesh.

Parameters

valuesnp.ndarray | list

vector same size as contact number to be color plotted

pixel_sizefloat, default: 0.5

size of one pixel in micrometers

num_pixelOptional[int] | None, default: None

alternative to pixel_size give pixel number of the image width

method“linear” | “nearest” | “cubic”, default: “linear”

Method of interpolation to generate a grid mesh

xlimsOptional[tuple], default: None

Force image xlims

ylimsOptional[tuple], default: None

Force image ylims

Returns

image2d array

The generated image

xlimstuple

The x limits

ylimstuple

The y limits

to_numpy(complete: bool = False) → array

Export the probe to a numpy structured array. This array handles all contact attributes.

Similar to the ‘to_dataframe()’ pandas function, but without pandas dependency.

The intended use is to attach this array to a recording object as a property (“contact vector”)

Parameters

completebool, default: False

If True, export complete information about the probe, including contact_plane_axes/si_units/device_channel_indices.

Returns

arrnumpy.array

Structured array with the following dtype schema:

dtype = [

(‘x’, ‘float64’), (‘y’, ‘float64’), (‘z’, ‘float64’, optional), (‘contact_shapes’, ‘U64’), # Shape parameters (‘shape_param_1’, ‘float64’), (‘shape_param_2’, ‘float64’),

⋮ ⋮ ⋮

variable number of shape parameters … (‘shank_ids’, ‘U64’), (‘contact_ids’, ‘U64’),

# The rest is added only if complete=True (‘device_channel_indices’, ‘int64’, optional), (‘si_units’, ‘U64’, optional), (‘plane_axis_x_0’, ‘float64’, optional), (‘plane_axis_x_1’, ‘float64’, optional), (‘plane_axis_y_0’, ‘float64’, optional), (‘plane_axis_y_1’, ‘float64’, optional), (‘plane_axis_z_0’, ‘float64’, optional), (‘plane_axis_z_1’, ‘float64’, optional), # Annotations (‘annotation_name_1’, ‘dtype of annotation’, optional), (‘annotation_name_2’, ‘dtype of annotation’, optional), ⋮

⋮ ⋮ ⋮

variable number of annotations …

]

to_zarr(folder_path: str | Path) → None

Serialize the Probe object to a Zarr file located at the specified folder path.

This method initializes a new Zarr group at the given folder path and calls add_probe_to_zarr_group to serialize the Probe’s data into this group, effectively storing the entire Probe’s state in a Zarr archive.

Parameters

folder_pathstr | Path

The path to the folder where the Zarr data structure will be created and where the serialized data will be stored. If the folder does not exist, it will be created.

wiring_to_device(pathway: str, channel_offset: int = 0)

Automatically set device_channel_indices based on a pathway.

See probeinterface.get_available_pathways()

Parameters

pathwaystr

The pathway. E.g. ‘H32>RHD’

channel_offset: int, default: 0

An optional offset to add to the device_channel_indices

ProbeGroup

class probeinterface.ProbeGroup

Class to handle a group of Probe objects and the global wiring to a device.

Optionally, it can handle the location of different probes.

add_probe(probe: Probe)

Add an additional probe to the ProbeGroup

Parameters

probe: Probe

The probe to add to the ProbeGroup

auto_generate_contact_ids(*args, **kwargs)

Annotate all contacts with unique contact_id values.

Parameters

*args: will be forwarded to probeinterface.utils.generate_unique_ids **kwargs: will be forwarded to

probeinterface.utils.generate_unique_ids

auto_generate_probe_ids(*args, **kwargs)

Annotate all probes with unique probe_id values.

Parameters

*args: will be forwarded to probeinterface.utils.generate_unique_ids **kwargs: will be forwarded to

probeinterface.utils.generate_unique_ids

static from_dict(d: dict)

Instantiate a ProbeGroup from a dictionary

Parameters

ddict

The dictionary representation of the probegroup

Returns

probegroupProbeGroup

The instantiated ProbeGroup object

static from_numpy(arr: ndarray) → ProbeGroup

Create ProbeGroup from a complex numpy array see ProbeGroup.to_numpy()

Parameters

arrnp.array

The structured np.array representation of the probe

Returns

probegroupProbeGroup

The instantiated ProbeGroup object

get_contact_count() → int

Total number of channels.

Returns

n: int

The total number of channels

get_global_contact_ids() → ndarray

Gets all contact ids concatenated across probes

Returns

contact_ids: np.ndarray

An array of the contaact ids across all probes

get_global_device_channel_indices() → ndarray

Gets the global device channels indices and returns as an array

Returns

channels: np.ndarray

a numpy array vector with 2 columns (probe_index, device_channel_indices)

Notes

If a channel within channels has a value of -1 this indicates that that channel is disconnected

set_global_device_channel_indices(channels: np.array | list)

Set global indices for all probes

Parameters

channels: np.array | list

The device channal indices to be set

to_dataframe(complete: bool = False) → pandas.DataFrame

Export the probegroup to a pandas dataframe

Parameters

completebool, default: False

If True, export complete information about the probegroup, including the probe plane axis.

Returns

dfpandas.DataFrame

The dataframe representation of the probegroup

to_dict(array_as_list: bool = False)

Create a dictionary of all necessary attributes.

Parameters

array_as_listbool, default: False

If True, arrays are converted to lists, by default False

Returns

ddict

The dictionary representation of the probegroup

to_numpy(complete: bool = False) → ndarray

Export all probes into a numpy array.

Parameters

complete: bool, default: False

If True, export complete information about the probegroup including contact_plane_axes/si_units/device_channel_indices

Import/export to formats

Read/write probe info using a variety of formats:

• probeinterface (.json)

• PRB (.prb)

• CSV (.csv)

• mearec (.h5)

• spikeglx (.meta)

• ironclust/jrclust (.mat)

• Neurodata Without Borders (.nwb)

probeinterface.io.read_probeinterface(file: str | Path) → ProbeGroup

Read probeinterface JSON-based format.

Parameters

file: Path or str

The file path

Returns

probegroup : ProbeGroup object

probeinterface.io.write_probeinterface(file: str | Path, probe_or_probegroup: Probe | ProbeGroup)

Write a probeinterface JSON file.

The format handles several probes in one file.

Parameters

filePath or str

The file path

probe_or_probegroupProbe or ProbeGroup object

If probe is given a probegroup is created anyway

probeinterface.io.read_prb(file: str | Path) → ProbeGroup

Read a PRB file and return a ProbeGroup object.

Since PRB does not handle contact shapes, contacts are set to be circle of 5um radius. Same for the probe shape, where an auto shape is created.

PRB format does not contain any information about the channel of the probe Only the channel index on device is given.

Parameters

filePath or str

The file path

Returns

probegroup : ProbeGroup object

probeinterface.io.write_prb(file: str, probegroup: ProbeGroup, total_nb_channels: int | None = None, radius: float | None = None, group_mode: str = 'by_probe')

Write ProbeGroup into a prb file.

This format handles:

• multi Probe with channel group index key

• channel positions with “geometry”

• device_channel_indices with “channels “key

Note: much information is lost in the PRB format:

• contact shape

• shape

• channel index

Note:

• “total_nb_channels” is needed by spyking-circus

• “radius” is needed by spyking-circus

• “graph” is not handled

Parameters

file: str

The name of the file to be written

probegroup: ProbeGroup

The Probegroup to be used for writing

total_nb_channels: Optional[int], default None

***to do

radius: Optional[float], default None

*** to do

group_mode: str

One of “by_probe” or “by_shank

probeinterface.io.read_csv(file: str | Path)

Return a 2 or 3 columns csv file with contact positions

probeinterface.io.write_csv(file, probe)

Write contact postions into a 2 or 3 columns csv file

probeinterface.io.read_spikeglx(file: str | Path) → Probe

Read probe position for the meta file generated by SpikeGLX

See http://billkarsh.github.io/SpikeGLX/#metadata-guides for implementation. The x_pitch/y_pitch/width are set automatically depending on the NP version.

The shape is auto generated as a shank.

Now reads:

• NP0.0 (=phase3A)

• NP1.0 (=phase3B2)

• NP2.0 with 4 shank

• NP1.0-NHP

Parameters

filePath or str

The .meta file path

Returns

probe : Probe object

probeinterface.io.read_mearec(file: str | Path) → Probe

Read probe position, and contact shape from a MEArec file.

See https://mearec.readthedocs.io/en/latest/ and https://doi.org/10.1007/s12021-020-09467-7 for implementation.

Parameters

filePath or str

The file path

Returns

probe : Probe object

probeinterface.io.read_nwb(file)

Read probe position from an NWB file

Probe generators

This module contains useful helper functions for generating probes.

probeinterface.generator.generate_dummy_probe(elec_shapes: circle' | 'square' | 'rect = 'circle') → Probe

Generate a dummy probe with 3 columns and 32 contacts. Mainly used for testing and examples.

Parameters

elec_shapes“circle” | “square” | “rect”, default: ‘circle’

Shape of the electrodes

Returns

probeProbe

The generated probe

probeinterface.generator.generate_dummy_probe_group() → ProbeGroup

Generate a ProbeGroup with 2 probes. Mainly used for testing and examples.

Returns

probeProbe

The generated probe

probeinterface.generator.generate_tetrode(r: float = 10.0) → Probe

Generate a tetrode Probe.

Parameters

r: float, default: 10

The distance multiplier for the positions

Returns

probeProbe

The generated probe

probeinterface.generator.generate_multi_columns_probe(num_columns: int = 3, num_contact_per_column: int = 10, xpitch: float = 20, ypitch: float = 20, y_shift_per_column: Optional[np.array | list] = None, contact_shapes: circle' | 'rect' | 'square = 'circle', contact_shape_params: dict = {'radius': 6}) → Probe

Generate a Probe with several columns.

Parameters

num_columnsint, default: 3

Number of columns

num_contact_per_columnint, default: 10

Number of contacts per column

xpitchfloat, default: 20

Pitch in x direction

ypitchfloat, default: 20

Pitch in y direction

y_shift_per_columnOptional[array-like], default: None

Shift in y direction per column. It needs to have the same length as num_columns, by default None

contact_shapes“circle” | “rect” | “square”, default: “circle”

Shape of the contacts

contact_shape_paramsdict, default: {‘radius’: 6}

Parameters for the shape. For circle: {“radius”: float} For square: {“width”: float} For rectangle: {“width”: float, “height”: float}

Returns

probeProbe

The generated probe

probeinterface.generator.generate_linear_probe(num_elec: int = 16, ypitch: float = 20, contact_shapes: circle' | 'rect' | 'square = 'circle', contact_shape_params: dict = {'radius': 6}) → Probe

Generate a one-column linear probe.

Parameters

num_elecint, default: 16

Number of electrodes

ypitchfloat, default: 20

Pitch in y direction

contact_shapes“circle” | “rect” | “square”, default ‘circle’

Shape of the contacts

contact_shape_paramsdict, default: {‘radius’: 6}

Parameters for the shape. For circle: {“radius”: float} For square: {“width”: float} For rectangle: {“width”: float, “height”: float}

Returns

probeProbe

The generated probe

Plotting

A simple implementation for plotting a Probe or ProbeGroup using matplotlib.

Depending on Probe.ndim, the plotting is done in 2D or 3D

probeinterface.plotting.plot_probe(probe, ax=None, contacts_colors=None, with_contact_id: bool = False, with_device_index: bool = False, text_on_contact: list | ndarray | None = None, contacts_values: ndarray | None = None, cmap: str = 'viridis', title: bool = True, contacts_kargs: dict = {}, probe_shape_kwargs: dict = {}, xlims: tuple | None = None, ylims: tuple | None = None, zlims: tuple | None = None, show_channel_on_click: bool = False)

Plot a Probe object. Generates a 2D or 3D axis, depending on Probe.ndim

Parameters

probeProbe

The probe object

axmatplotlib.axis | None, default: None

The axis to plot the probe on. If None, an axis is created

contacts_colorsmatplotlib color | None, default: None

The color of the contacts

with_contact_idbool, default: False

If True, channel ids are displayed on top of the channels

with_device_indexbool, default: False

If True, device channel indices are displayed on top of the channels

text_on_contact: None | list | numpy.array, default: None

Addintional text to plot on each contact

contacts_valuesnp.array, default: None

Values to color the contacts with

cmapa colormap color, default: “viridis”

A colormap color

titlebool, default: True

If True, the axis title is set to the probe name

contacts_kargsdict, default: {}

Dict with kwargs for contacts (e.g. alpha, edgecolor, lw)

probe_shape_kwargsdict, default: {}

Dict with kwargs for probe shape (e.g. alpha, edgecolor, lw)

xlimstuple | None, default: None

Limits for x dimension

ylimstuple | None, default: None

Limits for y dimension

zlimstuple | None, default: None

Limits for z dimension

show_channel_on_clickbool, default: False

If True, the channel information is shown upon click

Returns

polyPolyCollection

The polygon collection for contacts

poly_contourPolyCollection

The polygon collection for the probe shape

probeinterface.plotting.plot_probe_group(probegroup, same_axes: bool = True, **kargs)

This function is deprecated and will be removed in 0.2.23 Please use plot_probegroup instead

Library

Provides functions to download and cache pre-existing probe files from some manufacturers.

The library is hosted here: https://gin.g-node.org/spikeinterface/probeinterface_library

The gin platform enables contributions from users.

probeinterface.library.get_probe(manufacturer: str, probe_name: str, name: str | None = None) → Probe

Get probe from ProbeInterface library

Parameters

manufacturer“cambridgeneurotech” | “neuronexus”

The probe manufacturer

probe_namestr (see probeinterface_libary for options)

The probe name

namestr | None, default: None

Optional name for the probe

Returns

probe : Probe object