Python API#

Python module for programmatic control of MaxLab Live.

General#

The Python API is based around objects that derive from a base class called maxlab.api_object.ApiObject. This base class contains only one abstract method called set(). Each class that derives from this base class can be sent with the maxlab.util.send() to the mxwserver. The set() method is hidden from this documentation since it is only there to construct the correct message that needs to be send to the mxwserver. Please note that these messages have a strict format and it is thus not advised to create them yourself. Instead, this API should be used.

Warning

It is important to understand that creating objects from classes that derive from maxlab.api_object.ApiObject will not have any effect on the system until they are sent to the server via maxlab.util.send().

maxlab.util.send(obj: ApiObject) → str#

Utility function to send command objects to the server API.

Parameters:: obj (ApiObject) – Any object derived from classes in maxlab.system or maxlab.chip. The command object needs a method called send(), which contains all the information needed to program the API
Return type:: str

System Commands#

The classes and functions in this library are used to control the system, which is the MaxHub and the Recording Unit.

class maxlab.system.DelaySamples(samples: int = 0)#

Insert a delay between two consecutive commands

Parameters:: samples (int) – How many samples to delay between two consecutive commands. Time between two recording samples is 50 µs and is independent of the data sampling rate, i.e it is the same for MaxOne and MaxTwo.

class maxlab.system.ReferenceStimulationHigh(reference_voltage: int = 2820)#

Sets the high reference voltage for the stimulation buffers.

Parameters:: reference_voltage (int) – Value in bits to set the reference voltage. Allowed values are between 0 and 4095, whereas 4095 corresponds to 3.3 volts. When doing voltage controlled stimulation, the recommended default value for this reference voltage is 2.25 volts, i.e. 2792 bits.

class maxlab.system.ReferenceStimulationLow(reference_voltage: int = 1304)#

Sets the low reference voltage for the stimulation buffers.

Parameters:: reference_voltage (int) – Value in bits to set the reference voltage. Allowed values are between 0 and 4095, whereas 4095 corresponds to 3.3 volts. When doing voltage controlled stimulation, a typically recommended value for this reference voltage is 1.05 volts, i.e. 1304.

Notes

Refer to the system manual for more details about this reference voltage.

class maxlab.system.GPIODirection(direction: int = 0)#

Set the direction of the GPIOs.

Please refer to the glossary if you are not sure what GPIO means.

Parameters:

direction (int) –

An 8-bit value, where each bit of direction controls the state of one GPIO, whether one GPIO is either in input or in output mode.

bit = ‘0’: setting the corresponding GPIO channel into input mode.
bit = ‘1’: setting the corresponding GPIO channel into output mode.

Notes

When the GPIO is set to input mode, the value applied to the GPIO pin is sampled together with each sampling frame of the MaxOne/MaxTwo chip and the values are recorded into the recording file.

Examples

>>> # This sets GPIO3 to output mode, GPIO7 - GPIO4 and GPIO2 - GPIO0 to input mode
>>> maxlab.send( maxlab.system.GPIODirection(0b00001000))

class maxlab.system.GPIOOutput(output: int = 0)#

Control the output of the GPIOs.

Please refer to the glossary if you are not sure what GPIO means.

Parameters:: output (int) – An 8-bit value specifying the output state of each GPIO channel.

Notes

When the corresponding bit is set to output mode with maxlab.system.GPIODirection(), the output of that channel can be controlled through this function.

Examples

The following example generates a pulse on the GPIO channel 3, by toggling bit 4:

>>> maxlab.send( maxlab.system.GPIOOutput(0b1000))
>>> maxlab.send( maxlab.system.DelaySamples(100))
>>> maxlab.send( maxlab.system.GPIOOutput(0b0000))

class maxlab.system.StatusLED(color: int = 0)#

Control the color of the status LED.

Parameters:

color (int) –

Value to control the color of the LED on the Recording Unit.

Values for the color parameter can be:

0: light blue.
1: cyan.
2: pink
3: dark blue
4: light green
5: dark green
6: red
7: off

Notes

When the experiment is light sensitive, for example during a retina experiment, this LED can be switched off by setting the color parameter to 7.

class maxlab.system.Event(well_id: int, event_type: int, user_id: int, properties: str)#

Triggers the sending of an event which is then converted to status_out command

Parameters:

well_id (int) – ID of the specific well.
event_type (int) – The type of the event. At the moment, the event_type needs to be 1.
user_id (int) – Custom event identifier assigned by the user. Further we have 1 <= user_id <= 2**20-1. Be careful that user_id can not be 0.
properties (str) – Additional properties associated with the event. Space separated key, value pairs, i.e. "key_1 value_1 key_2 value_2".

Examples

>>> mx.Event(0, 1, event_id, f"custom_id {number}")

Notes

Events, along with the frame number at which they occur, are stored in the recording file. If they are sent before a stimulation pulse within a sequence, they will share the same frame number as the onset of the stimulation and can, therefore, be used to identify the exact timing of the stimulation.

The combination of the well_id and user_id must be unique for different events.

Chip Commands#

The classes and functions in this library are used to control the MaxOne sensor chip.

class maxlab.chip.Amplifier(gain: int = 512)#

Program gain of the MaxOne/MaxTwo on-chip amplifiers.

Parameters:: gain (int) – The gain to be set.

Notes

Default gain for this command is 512. Use maxlab.chip.Amplifier.set_gain() to set a different gain.

set_gain(gain: int) → Amplifier#

Set different gain values for the amplifier.

Parameters:

gain (int) –

The gain to be set.

Possible gain values are:

1
7
112
512
1024
1025
2048

Notes

Other values are not valid and will raise an exception. For example trying to set the gain to 1000:

Raises:: ValueError – If gain is not a valid gain setting.

Examples

>>> try:
>>>     maxlab.chip.Amplifier().set_gain(1000)
>>> except ValueError as error:
>>>     print(error.args[0])
Not a valid gain parameter: 1000

class maxlab.chip.DAC(dac_no: int = 0, dac_code: int = 512, dac_code_second: int = 512)#

Program the three on-chip DACs (digital-to-analog converters) channels.

Parameters:

dac_no (int) – Which DAC channel to control.
dac_code (int) – DAC code in bits.
dac_code_second (int) – This parameter is only relevant when dac_no=3.

Notes

Depending on which DAC channel is specified in the command, the parameter dac_code has a different meaning.

The meaning of dac_code depending on dac_no (DAC channel) is:

0: dac_code controls DAC0

1: dac_code controls DAC1

2: dac_code controls DAC2

3: dac_code controls DAC0 and dac_code_second controls DAC1 at the very same time.

The last mode dac_code=3 is useful for applications where the outputs of two DAC channels need to be controlled/changed at the exact same time.

Each DAC channel can be programmed with 10 bits, i.e. possible values range between 0 and 1023. To convert between DAC bits and stimulation amplitude, one needs to multiply the DAC bits with the value from maxlab.util.query_DAC_lsb_mV().

Examples

When the stimulation buffers are in voltage mode, the conversion between DAC code and stimulation voltage goes as follows:

>>> stimVoltage = (512 - dac_code) * maxlab.query_DAC_lsb_mV()

class maxlab.chip.StimulationUnit(unit_no: int)#

Program the 32 on-chip stimulation units.

Parameters:: unit_no (int) – The stimulation unit to configure.

Notes

When doing voltage stimulation, the amplifier in the stimulation unit acts as an inverting amplifier. A DAC code of 512 corresponds to mid-supply, i.e. 0-volt stimulation. 512+100 results in a negative voltage. 512-100 results in a positive voltage.

Examples

To convert between bits and stimulation voltage, one needs to know the DAC lsb:

>>> lsb = maxlab.query_DAC_lsb_mV()
>>> amplitude = -(lsb * bits)

connect(connect: bool) → StimulationUnit#

Connect or disconnect the stimulation unit.

Parameters:: connect (bool) – Connect or disconnect the output of the unit.
Return type:: maxlab.chip.StimulationUnit

dac_source(dac: int) → StimulationUnit#

Choose the DAC channel for the stimulation unit.

Parameters:

dac (int) –

The DAC channel to choose for the unit.

Possible values for DAC channels are:

0=DAC0
1=DAC1
2=DAC2

Return type:

maxlab.chip.StimulationUnit

external_reference(ref_source: bool = True) → StimulationUnit#

Use an external reference voltage for this stimulation unit instead of a DAC channel.

Parameters:: ref_source (bool) – If true, use the external reference source instead of a DAC channel.
Return type:: maxlab.chip.StimulationUnit

get_readout_channel() → int#

Get the readout channel for this stimulation unit

Returns:: The readout channel for the stimulation unit.
Return type:: int

power_up(power_up: bool) → StimulationUnit#

Power-up this stimulation unit.

Parameters:: power_up (bool) – Enable on-chip power for this particular stimulation unit.
Return type:: maxlab.chip.StimulationUnit

set_voltage_mode() → StimulationUnit#

Set the stimBuffer unit into voltage mode.

Return type:: maxlab.chip.StimulationUnit

class maxlab.chip.Array(token: str = 'online', persistent: bool = False)#

Control the electrode array of the MaxOne/MaxTwo chip.

Parameters:

token (str) – Token id to identify this instance on the server. Default is ‘online’
persistent (bool) – Should the instance of this array get deleted on the server when ‘close’ gets called

Notes

Similarly to maxlab.Sequence, for each maxlab.Array object there is a counter part on the server, which can be uniquely identified through the token id parameter. However, differently than for maxlab.Sequence, creating such Array objects on the server is computationally expensive. It takes multiple seconds and it consumes significant amounts of RAM.

One option is to use one of the already available array objects, whilst another is to create a new array object on the server. The names of the available objects are ‘online’ and ‘offline’. The online array object is the same controlled through MaxLab Live. I.e. when downloading a configuration from the scope GUI, the ‘online’ array will have the same configuration set. If it is required to manipulate the array without affecting the online version, it is recommended to use the ‘offline’ version. By specifying a different name, arbitrary amounts of arrays can be controlled at the same time.

All operations on the array, such as loading a configuration or connecting amplifiers to stimulation units are done in software and no changes are applied to the hardware. Only once the Array.download() method is executed, the state of the array gets downloaded to the actual electrode array on the chip.

Examples

When creating configurations through the Array.route() method, all other configurations, such as connecting stimulation channels etc. will be lost. So the best procedure is to:

Select electrodes

Route

Connect stimulation channels

Save configuration

>>> array = maxlab.chip.Array('online')
>>> array.reset()
>>> array.select_electrodes( [11110, 11111, 11112] )
>>> array.select_stimulation_electrodes( [11330, 11331, 11332] )
>>> array.route()
>>> array.connect_electrode_to_stimulation( 11330 )
>>> array.connect_electrode_to_stimulation( 11331 )
>>> array.connect_electrode_to_stimulation( 11332 )
>>> array.save_config("myConfig.cfg")
>>>
>>> stim1 = array.query_stimulation_at_electrode( 11330 )
>>> stim2 = array.query_stimulation_at_electrode( 11331 )
>>> stim3 = array.query_stimulation_at_electrode( 11332 )

clear_selected_electrodes() → str#

Clear all selected electrodes.

Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

close() → None#

Close this Array object.

If persistent is not set, delete the array with the same token from the server.

connect_all_floating_amplifiers() → str#

Connect all floating amplifiers to a common node.

Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

Notes

By enabling Core.use_external_port(), the floating amplifiers can be connected to the external port.

connect_amplifier_to_ringnode(amplifier_channel: int) → str#

Connect amplifier to the common ring node.

Parameters:: amplifier_channel (int) – Amplifier to be connected to the ring node.
Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

Notes

By enabling Core.use_external_port(), the ring node can be connected to the external port.

connect_amplifier_to_stimulation(amplifier_channel: int) → str#

Connect the amplifier to a stimulation unit.

Parameters:: amplifier_channel (int) – Amplifier to be connected to a stimulation unit.
Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

connect_electrode_to_stimulation(electrode_no: int) → str#

Connect electrode to stimulation unit.

Parameters:: electrode_no (int) – Electrode ID to be connected to a stimulation unit.
Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

Notes

For this method to work, the selected electrode ID needs already be routed to an amplifier.

disconnect_amplifier_from_ringnode(amplifier_channel: int) → str#

Disconnect amplifier from ring node.

Parameters:: amplifier_channel (int) – Which amplifier channel to disconnect from the ring node.
Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

disconnect_amplifier_from_stimulation(amplifier_channel: int) → str#

Disconnect amplifier from stimulation.

Parameters:: amplifier_channel (int) – Which amplifier channel to disconnect from a stimulation unit.
Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

disconnect_electrode_from_stimulation(electrode: int) → str#

Disconnect electrode from stimulation.

Parameters:: electrode (int) – Which electrode ID to disconnect from a stimulation unit.
Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

download(wells: List[int] | None = None) → None#

Download the electrode configuration to the chip.

Parameters:: wells (List[int]) – A list of the wells.

get_config() → Config#

Obtain a mx.Config object representing the config routed to the Array.

Return type:: Config

load_config(config_file_name: str) → str | int#

Loads an electrode configuration from disk and sends it to the API.

Parameters:: config_file_name (str) – File name where to save the configuration to. Should end with “.cfg”
Returns:: If the configuration is successfully loaded and sent to the API, the method returns a string indicating either ‘OK’ or ‘ERROR’. If there is an error or the configuration loading fails, the method returns an integer value of -1.
Return type:: Union[str, int]

query_amplifier_at_electrode(electrode_no: int) → str#

Query amplifier at the electrode.

Parameters:: electrode_no (int) – Which electrode ID to query.
Returns:: A string containing the number of the amplifier at the desired electrode, or an empty string if no amplifier is connected.
Return type:: str

query_amplifier_at_ringnode() → str#

Query which amplifiers are connected to the ring node.

Returns:: A string containing the number of the amplifier at the ring node, or an empty string if no amplifier is connected.
Return type:: str

query_amplifier_at_stimulation(stimulation_channel: int) → str#

Query amplifier at stimulation unit.

Parameters:: stimulation_channel (int) – Which stimulation unit to query.
Returns:: A string containing the number of the amplifier at the desired stimulation unit, or an empty string if no amplifier is connected.
Return type:: str

query_stimulation_at_amplifier(amplifier_channel: int) → str#

Query stimulation unit at amplifier.

Parameters:: amplifier_channel (int) – Which amplifier channel to query.
Returns:: A string containing the number of the stimulation unit at the desired amplifier, or an empty string if no stimulation unit is connected.
Return type:: str

query_stimulation_at_electrode(electrode_no: int) → str#

Query stimulation unit at the electrode.

Parameters:: electrode_no (int) – Which electrode ID to query.
Returns:: A string containing the number of the stimulation unit at the desired electrode, or an empty string if no stimulation unit is connected.
Return type:: str

reset() → str#

Resets the array into a defined state.

This method disconnects all electrodes and all amplifiers.

Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

route() → str#

Route electrode configuration.

Returns:: Possible values are ‘OK’ or ‘ERROR’
Return type:: str

Notes

Be aware that any manual switch settings, such as stimulation connections, are lost after the routing. This is due to the routing starting from an ‘empty’ array.

save_config(config_file_name: str) → int#

Save current array configuration to disk.

Parameters:: config_file_name (str) – File name where to save the configuration to. Should end with “.cfg”
Returns:: An integer value of 0 indicating the successful execution of the save operation.
Return type:: int

select_electrodes(electrodes: List[int], weight: int = 1) → str#

Select the given electrodes for routing.

Parameters:

electrodes (List[int]) – List of recording electrodes.
weight (int) –
Set the routing priority for the electrodes.

By passing a weight parameter, the routing priority for the electrodes can be adjusted. The higher the weight, the higher the routing priority during routing.

Only one weight can be set for the electrode ids in the method argument. Usually, different priorities need to be assigned and select_electrodes can be called for each set of priorities. See below for an example.

Returns:

Possible values are ‘OK’ or ‘ERROR’

Return type:

str

Examples

>>> array = maxlab.chip.Array()
>>> array.select_electrodes([1,2,3,4], 10) # electrodes with priority of '10'
>>> array.select_electrodes([5,6,7,8], 15) # other electrodes with a higher priority

select_stimulation_electrodes(electrodes: List[int]) → str#

Select the given electrodes for stimulation.

Parameters:

electrodes (List[int]) –

List of stimulation electrodes.

The selected electrodes get automatically a high priority when routed.

Returns:

Possible values are ‘OK’ or ‘ERROR’

Return type:

str

Notes

Make sure not to select more than 1020 of these electrodes. Otherwise, routing will not work (converge) well.

class maxlab.chip.Core#

Control core settings of the MaxOne/MaxTwo chip.

enable_stimulation_power(enable: bool) → Core#

Powers up the Stimulation Units and enables stimulations to be delivered to the array.

Parameters:: enable (bool) – True if stimulation power is enabled.
Return type:: maxlab.chip.Core

use_external_port(enable: bool) → Core#

Enables the external port access to the array.

Parameters:: enable (bool) – True if external port is used.
Return type:: maxlab.chip.Core

Stimulation#

Using maxlab.send() to send commands may not provide sufficiently precise timing for stimulation purposes due to limited control over the execution timing of these commands. Several factors can introduce variability: the Python interpreter may experience pauses, such as a delay between consecutive commands, or network jitter between MaxLab Live and the MaxOne/MaxTwo may further disrupt timing accuracy.

In order to avoid the problem explained above, we use maxlab.Sequence. With such a sequence, we can download all commands which belong together in one go to the MaxHub and thus avoid any jitter in the execution. Precise timing of command execution is particularly important when performing stimulation experiments.

Thus, a typical (positive-first, biphasic voltage) stimulation pulse, using a maxlab.Sequence, would look like:

>>> sequence = maxlab.Sequence()
>>> sequence.append( maxlab.chip.DAC(0, 512-100) )
>>> sequence.append( maxlab.system.DelaySamples(4) )
>>> sequence.append( maxlab.chip.DAC(0, 512+100) )
>>> sequence.append( maxlab.system.DelaySamples(4) )
>>> sequence.append( maxlab.chip.DAC(0, 512) )
>>> sequence.send()

Note

When doing voltage stimulation, the amplifier in the stimulation unit acts as an inverting amplifier, i.e. this is why we first subtract and then add to the DAC eventhough we want a positive-first, biphasic pulse.

The calls to Sequence.append() prepare the correct calls in the `mxwserver` with the correct commands. But only the last call to Sequence.send() actually executes the commands i.e. sends them to the system.

Relevant classes#

class maxlab.sequence.Sequence(name: str | None = None, initial_delay: int = 100, persistent: bool = False)#

Holds a sequence of commands.

Parameters:

name (Optional[str]) – The name associated with the sequence. If not provided, a new token will be generated.
initial_delay (int) – The number of samples to delay the first command in the sequence.
persistent (bool) – Indicates whether the sequence should persist on the server even after the Sequence object is deleted. In principle, you can trigger the sequence from C++ even after the python object associated to it has been deleted.

Notes

The commands contained in a sequence are executed immediately one after each other.

Thus, the timing between consecutive commands can be precisely controlled, down to a resolution of 50 µs. The jitter between consecutive commands is negligible with respect to 50 µs, and this is relevant for sequences implementing electrical stimulation pulses. For a more detailed explanation, please see the introduction of this document.

In case the first command of the sequence gets executed before all remaining commands were successfully downloaded, the timing would be no longer precise. To prevent this from happening, it is good practise to insert a delay command right at the beginning of the sequence. This is done through the parameter initial_delay. Delaying for 100 samples (i.e. 5 ms) should be enough in virtually all cases.

The sequences are managed on the server and one can generate as many sequences as needed. They will be maintained on the server. Whenever a sequence object in the python code gets deleted, either through explicitely calling del or if the code goes out of scope, the respective sequence in the server will also be removed:

>>> s1 = maxlab.Sequence()
>>> s1.append( maxlab.system.DelaySamples(4) )
>>> del s1 # All information about Sequence s1 is removed from the server
>>>
>>> def func(samples):
>>>     s = maxlab.Sequence()
>>>     s.append(maxlab.system.DelaySamples(samples))
>>>     return 0 # As soon as the function finishes, the sequence s is removed from the server

append(obj: ApiObject) → Sequence#

Append the ApiObject obj to the sequence.

Parameters:: obj (ApiObject) – ApiObject to be appended to the sequence.
Returns:: The Sequence object itself after appending, not a new sequence.
Return type:: maxlab.sequence.Sequence

send() → Sequence#

Sends the sequence to the system.

This method downloads the sequence to the MaxOne Hub/MaxTwo, from where it gets executed, command by command.

Returns:: The Sequence object itself after sending, not a new sequence.
Return type:: maxlab.sequence.Sequence

Utilities#

maxlab.util.activate(wells: List[int]) → None#

Function to select the wells, i.e. in the same fashion as you select wells in scope for assays.

Parameters:: wells (List[int]) – A list of wells to activate.

maxlab.util.initialize(wells: List[int] | None = None) → None#

Function to initialize wells to a known state.

Parameters:: wells (List[int], optional) – A list of wells to initialize. If no parameter is passed in, initializes all activated wells.

maxlab.util.offset() → None#

Function to run offset compensation on all activated wells.

Notes

You only need to run an offset compensation command after initialization using the mx.initialize() command.

maxlab.util.set_primary_well(well: int) → None#

Select the (single) well from which real-time data should be streamed.

Parameters:: well (int)

maxlab.util.query_DAC_lsb_mV() → str#

Query LSB value of the DAC channels.

Return type:: str

Notes

This value is only valid when doing voltage stimulation.

maxlab.util.electrode_neighbors(index: int, radius: int) → List[int]#

Given an index on the chip, i.e. an electrode number and a radius, this function returns the numbers of the neighboring electrodes.

Parameters:

index (int) – Electrode index.
radius (int) –
Radius to consider, where the value corresponds to the logical Euclidean Distance (lED) between the points on the grid. As an example, consider this simple 3 x 6 grid
```
   0         5
  +-+-+-+-+-+-+
0 | |A| | | | |
  +-+-+-+-+-+-+
  | | | | | | |   lED(A, B) = sqrt(abs(0-2)**2 + abs(1-4)**2) ~ 3.60
  +-+-+-+-+-+-+
2 | | | | |B| |
  +-+-+-+-+-+-+
```
i.e. assuming index is the position of A, then setting radius to >=4 will capture B, otherwise it will not.

Returns:

indices

Return type:

List[int]

Examples

>>> neighbors(45, 1)
[44, 46, 265]
>>> neighbors(789, 2)
[349, 568, 569, 570, 787, 788, 790, 791, 1008, 1009, 1010, 1229]

class maxlab.util.Timing#

Class defining suitable wait times after various commands to ensure proper execution.

These can be used with the time.sleep() command after executing the respective commands.

waitInit#

How many seconds to wait after mx.initialize(). Equal to 2.

Type:: int

waitAfterDownload#

How many seconds to wait after mx.Array.download(). Equal to 5.

Type:: int

waitInMX1Offset#

How many seconds to wait after mx.offset() for MaxOne. Equal to 5.

Type:: int

waitInMX2Offset#

How many seconds to wait after mx.offset() for MaxTwo. Equal to 15.

Type:: int

waitAfterRecording#

How many seconds to wait after mx.Saving.stop_recording(). Equal to 2.

Type:: int

Examples

>>> mx.initialize()
>>> time.sleep(mx.Timing.waitInit)

maxlab.util.clear_events() → None#

Clear all events in the event buffer.

Notes

This removes all events from the internal event buffer.

maxlab.util.set_event_threshold(threshold: float) → None#

Set the spike detection threshold for the system.

Parameters:: threshold (float) – The threshold value to set, in standard deviations away from the mean.
Return type:: None

Examples

>>> mx.set_event_threshold(3.5)
>>> mx.set_event_threshold(5.5)

Notes

This function does not update Scope. Make sure to either restart scope if you have it open, or set the threshold back to the default value of 5.0.

File Saving#

class maxlab.saving.Saving#

group_define(well: int, name: str, channels: List[int] = []) → str#

Define the recording groups

This method sets which electrodes we want to store the data from and their respective grouping. It is only used for the new file format (legacy_file_format = False) and if we want to store the signal traces. The parameter name sets the group name used for these electrodes, e.g., “all_channels”:

>>> s.group_define(0, "all_channels", range(1024))

This method needs to be called before starting the recordings with start_recording(), but after the initialization of the file with start_file() . It is recommended to delete potential already-existing groups before running group_define(), by running the method group_delete_all().

Parameters:

well (int) – Well index specifying from which well to store data from.
name (str) – Name of the group used for the recording electrodes.
channels (List[int]) – List of channels to record from. Values range from 0 to 1023, which is the maximal number of recording channels.

Returns:

“ok” if the groups were correctly defined, else “error”.

Return type:

str

Notes

If needed, we can also define multiple groups for same recording, with a set of channels. These groups can also have overlapping channels.

Channels that are not connected to an electrode still transmit data to the software; however, these values are not meaningful. It is the user’s responsibility to select appropriate, connected channels for recording and to consider only relevant channels during analysis.

group_delete(well: int, name: str) → str#

Delete a specific group

This method deletes a specific group from the recording file and as defined by the method group_define(). It takes as input the well index and the group name.

Parameters:

well (int) – Well index.
name (str) – Group name.

Returns:

“ok” if the group was succesfully deleted, else “error”.

Return type:

str

group_delete_all() → str#

Delete all groups

This method deletes all group from the recording, as defined by the method group_define().

Returns:: “ok” if the groups were succesfully deleted, else “error”.
Return type:: str

group_delete_well(well: int) → str#

Delete a specific well

This method deletes a specific well from the recording file and as defined by the method group_define(). It takes as input the well index.

Parameters:: well (int) – Well index.
Returns:: “ok” if the well was succesfully deleted, else “error”.
Return type:: str

open_directory(directory_name: str) → None#

Open the recording directory

This methods open the directory where the data will be saved. It needs to be run before initializing the file with the method start_file() and it takes as parameter the directory name, i.e., the path.

Parameters:: directory_name (str) – Directory name, i.e., path, to where we wish to save the recording data.
Return type:: None

record_wells(wells: List[int]) → None#

Set the wells that should be recorded in the files

Parameters:: wells (List[int]) – List of well indices.
Return type:: None

set_legacy_format(use: bool = True) → None#

Set the legacy file format for saving.

Parameters:: use (bool, default True) – If True, the legacy file format is used for saving. If False, the new file format is used for saving.
Return type:: None

Notes

If the new data format is used and we want to also store the signal traces, we must declare which electrodes we want to store data from. This can be set through the group_define() method.

start_file(file_name: str) → None#

Initialize a recording file

This method initialize an emtpy recording file and needs to be run before calling start_recording().

Parameters:: file_name (str) – The filename in which the data is recorded.
Return type:: None

start_recording(wells: List[int] | None = None) → None#

Start the recording

This method starts the recording and needs to be run after the initialization of the recording file with the method start_file().

Optionally, the method can take as parameter which wells we wish to record data from.

Parameters:: wells (List[int], optional) – List of well indices specifying from which well we want to record data.
Return type:: None

stop_file() → None#

Terminate a recording file

This method terminates the filled recording file and needs to be run after calling stop_recording().

Return type:: None

stop_recording() → None#

Stop the recording

This method stops the recording and needs to be run before the termination of the recording file with the method stop_file().

Querying Electrode Configurations#

class maxlab.config.Config(str: str)#

An object representing a given electrode configuration, along with channel mappings.

Parameters:

str (str) –

A string representing the configuration, in the same format saved in .cfg files. The string is in the following format:

<channel>(<electrode>)<X>/<Y>;<channel>(<electrode>)<X>/<Y>;...

where <X> and <Y> represent horizonal and vertical positions on the array, respectively, in µm. The position <X>=0 and <Y>=0 represents the top left corner of the array.

Notes

The Config object representing a configuration routed to an maxlab.chip.Array can be obtained by calling mx.Array.get_config().

get_channels() → List[int]#

Obtain the channel numbers routed in the configuration.

Returns:: A list of channel numbers.
Return type:: List[int]

get_channels_for_electrodes(electrodes: List[int]) → List[int]#

Obtain the channel numbers routed to a list of specified electrodes.

Parameters:: electrodes (List[int]) – A list of electrode numbers.
Returns:: A list of channel numbers routed to the specified electrodes.
Return type:: List[int]