microdrop Package

microdrop Package

microdrop.__init__.base_path()

microdrop.__init__.glade_path()

Return path to .glade files used by gtk to construct views.

__main__ Module

app Module

app_context Module

microdrop.app_context.get_app()

microdrop.app_context.get_hub_uri()

config Module

class microdrop.config.Config(filename=None)

Bases: object

Methods

load([filename])	Load a Config object from a file.
save([filename])

default_config_directory = path('/home/docs/.microdrop')

default_config_path = path('/home/docs/.microdrop/microdrop.ini')

load(filename=None)

Load a Config object from a file.

Parameters:

filename – path to file. If None, try loading from the default location, and if there’s no file, create a Config object with the default options.

Raises:

• IOError – The file does not exist.
• ConfigObjError – There was a problem parsing the config file.
• ValidationError – There was a problem validating one or more fields.

save(filename=None)

spec = '\n [dmf_device]\n # name of the most recently used DMF device\n name = string(default=None)\n\n [protocol]\n # name of the most recently used protocol\n name = string(default=None)\n\n [plugins]\n # directory containing microdrop plugins\n directory = string(default=None)\n\n # list of enabled plugins\n enabled = string_list(default=list())\n '

exception microdrop.config.ValidationError

Bases: exceptions.Exception

dmf_device Module

exception microdrop.dmf_device.DeviceScaleNotSet

Bases: exceptions.Exception

class microdrop.dmf_device.DmfDevice(svg_filepath, name=None, **kwargs)

Bases: object

Attributes

df_electrode_channels
dirty
electrodes

Methods

actuated_area(state_of_all_channels)	Compute area of all actuated electrodes.
actuated_channels(actuated_electrodes_index)	param actuated_electrodes_index:  Actuated electrode identifiers.
actuated_electrodes(actuated_channels_index)	param actuated_channels_index:  Actuated channel indexes.
diff_electrode_channels()	Identify electrodes with modified channel lists.
find_path(source_id, target_id)	returns:A list of nodes on the shortest path from source to target.
get_actuated_electrodes_area(electrode_states)	Compute area of actuated electrodes.
get_bounding_box()	returns:Tuple containing origin-x, origin-y, width and height,
get_electrode_areas()	returns:Area of each electrode in square millimeters, indexed by electrode
get_electrode_channels()	Load the channels associated with each electrode from the device layer of an SVG source.
get_svg_frame()	Return a pandas.DataFrame containing the vertices for electrode paths.
load(svg_filepath, **kwargs)	Load a DmfDevice from a file.
max_channel()	returns:Maximum channel index.
set_electrode_channels(electrode_id, channels)	Set channels for electrode electrode_id to channels.
to_svg()	returns:SVG XML source with up-to-date electrode channel lists.

actuated_area(state_of_all_channels)

Compute area of all actuated electrodes.

Parameters:state_of_all_channels (np.array) – An array-like instance containing an actuation level for each respective channel. Returns:Area of actuated electrodes in square millimeters. Return type:float

actuated_channels(actuated_electrodes_index)

Parameters:actuated_electrodes_index (list or array-like) – Actuated electrode identifiers. Returns:Actuated channel index values, indexed by electrode identifier. Return type:pandas.Series

actuated_electrodes(actuated_channels_index)

Parameters:actuated_channels_index (list or array-like) – Actuated channel indexes. Returns:Actuated electrode identifiers, indexed by channel index. Return type:pandas.Series

df_electrode_channels

diff_electrode_channels()

Identify electrodes with modified channel lists.

Returns:Frame containing modified electrode channel lists. The two columns contain a list for the original and new assigned channels, respectively, indexed by electrode_id. Return type:pandas.DataFrame

dirty

electrodes

find_path(source_id, target_id)

Returns:A list of nodes on the shortest path from source to target. Return type:list

get_actuated_electrodes_area(electrode_states)

Compute area of actuated electrodes.

Parameters:electrode_states (pandas.Series) – Electrode states, indexed by electrode identifier. Any state greater than zero is considered actuated. Returns:Area of actuated electrodes in square millimeters. Return type:float

get_bounding_box()

Returns:Tuple containing origin-x, origin-y, width and height, respectively. Return type:tuple

get_electrode_areas()

Returns:Area of each electrode in square millimeters, indexed by electrode identifier. Return type:pandas.Series

get_electrode_channels()

Load the channels associated with each electrode from the device layer of an SVG source.

For each electrode polygon, the channels are read as a comma-separated list from the “data-channels” attribute.

Returns:Each row corresponds to a channel connected to an electrode, where the "electrode_id" column corresponds to the "id" attribute of the corresponding SVG polygon. Return type:pandas.DataFrame

Notes

• Each electrode corresponds to a closed path in the device drawing.
• Each channel index corresponds to a DMF device channel that may be actuated independently.

get_svg_frame()

Return a pandas.DataFrame containing the vertices for electrode paths.

Each row of the frame corresponds to a single path vertex. The groupby() method may be used, for example, to apply operations to vertices on a per-path basis, such as calculating the bounding box.

classmethod load(svg_filepath, **kwargs)

Load a DmfDevice from a file.

Parameters:

filename – path to file.

Raises:

• TypeError – file is not a DmfDevice.
• FutureVersionError – file was written by a future version of the software.

max_channel()

Returns:Maximum channel index. Return type:int

set_electrode_channels(electrode_id, channels)

Set channels for electrode electrode_id to channels.

This includes updating self.df_electrode_channels.

Note

Existing channels assigned to electrode are overwritten.

Parameters:

• electrode_id (str) – Electrode identifier.
• channels (list) – List of channel identifiers assigned to the electrode.

Returns:

True if channel mappings have changed.

Return type:

bool

to_svg()

Returns:SVG XML source with up-to-date electrode channel lists. Return type:unicode

microdrop.dmf_device.extract_channels(df_shapes)

Load the channels associated with each electrode from the device layer of an SVG source.

For each electrode polygon, the channels are read as a comma-separated list from the “data-channels” attribute.

Parameters:

• svg_source (filepath) – Input SVG file containing connection lines.
• shapes_canvas (shapes_canvas.ShapesCanvas) – Shapes canvas containing shapes to compare against connection endpoints.
• electrode_layer (str) – Name of layer in SVG containing electrodes.
• electrode_xpath (str) – XPath string to iterate throught electrodes.
• namespaces (dict) – SVG namespaces (compatible with etree.parse).

Returns:

Each row corresponds to a channel connected to an electrode, where the "electrode_id" column corresponds to the "id" attribute of the corresponding SVG polygon.

Return type:

pandas.DataFrame

experiment_log Module

class microdrop.experiment_log.ExperimentLog(directory=None)

Methods

add_data(data[, plugin_name])
add_step(step_number[, attempt])
get(name[, plugin_name])
get_log_path()
load(filename)	Load an experiment log from a file.
save([filename, format])
start_time()
to_frame()	returns:

add_data(data, plugin_name='core')

add_step(step_number, attempt=0)

class_version = '0.3.0'

get(name, plugin_name='core')

get_log_path()

classmethod load(filename)

Load an experiment log from a file.

Parameters:

filename – path to file.

Raises:

• TypeError – file is not an experiment log.
• FutureVersionError – file was written by a future version of the software.

save(filename=None, format='pickle')

start_time()

to_frame()

Returns:

Tuple containing:

• Experiment information, including UTC start time, MicroDrop software version, list of plugin versions, etc.

• Data frame with multi-index columns, indexed first by plugin name, then by plugin field name.

Note

Values may be Python objects. In future versions of MicroDrop, values may be restricted to json compatible types.

Return type:(pd.Series, pd.DataFrame)

microdrop.experiment_log.log_data_to_frame(log_data_i)

Parameters:log_data_i (microdrop.experiment_log.ExperimentLog) – MicroDrop experiment log, as pickled in the data file in each experiment log directory. Returns:Tuple containing: - Experiment information, including UTC start time, MicroDrop software version, list of plugin versions, etc. - Data frame with multi-index columns, indexed first by plugin name, then by plugin field name.

Note

Values may be Python objects. In future versions of MicroDrop, values may be restricted to json compatible types.

Return type:(pd.Series, pd.DataFrame)

interfaces Module

class microdrop.interfaces.IFoo

Bases: pyutilib.component.core.core.Interface

class microdrop.interfaces.ILoggingPlugin

Bases: pyutilib.component.core.core.Interface

Methods

on_critical(record)
on_debug(record)
on_error(record)
on_info(record)
on_warning(record)

on_critical(record)

on_debug(record)

on_error(record)

on_info(record)

on_warning(record)

class microdrop.interfaces.IPlugin

Bases: pyutilib.component.core.core.Interface

Methods

get_schedule_requests(function_name)	param function_name:  Plugin callback function name.
get_step_form_class()
get_step_values([step_number])
on_app_exit()	Handler called just before the MicroDrop application exits.
on_app_options_changed(plugin_name)	Handler called when the app options are changed for a particular plugin.
on_dmf_device_changed(dmf_device)	Handler called when a DMF device is modified (e.g., channel assignment, scaling, etc.).
on_dmf_device_saved(dmf_device)	Handler called when a DMF device is saved.
on_dmf_device_swapped(old_dmf_device, dmf_device)	Handler called when a different DMF device is swapped in (e.g., when a new device is loaded).
on_experiment_log_changed(experiment_log)	Handler called when the current experiment log changes (e.g., when a protocol finishes running.
on_experiment_log_selection_changed(data)	Handler called whenever the experiment log selection changes.
on_export_experiment_log_data(experiment_log)	Handler called when the experiment log is exported.
on_metadata_changed(schema, ...)	Handler called each time the experiment metadata has changed.
on_plugin_disable()	Handler called once the plugin instance is disabled.
on_plugin_disabled(env, plugin)	Handler called to notify that a plugin has been disabled.
on_plugin_enable()	Handler called once the plugin instance is enabled.
on_plugin_enabled(env, plugin)	Handler called to notify that a plugin has been enabled.
on_protocol_changed()	Handler called when a protocol is modified.
on_protocol_finished()	Handler called when a protocol finishes (i.e., runs the last step of the final repetition).
on_protocol_pause()	Handler called when a protocol is paused.
on_protocol_run()	Handler called when a protocol starts running.
on_protocol_swapped(old_protocol, protocol)	Handler called when a different protocol is swapped in (e.g., when a protocol is loaded or a new protocol is created).
on_step_complete(plugin_name[, return_value])	Handler called whenever a plugin completes a step.
on_step_created(step_number)	Handler called whenever a new step is created.
on_step_options_changed(plugin, step_number)	Handler called when the step options are changed for a particular plugin.
on_step_options_swapped(plugin, ...)	Handler called when the step options are changed for a particular plugin.
on_step_run()	Handler called whenever a step is executed.
on_step_swapped(old_step_number, step_number)	Handler called when the current step is swapped.

get_schedule_requests(function_name)

Parameters:function_name (str) – Plugin callback function name. Returns:List of scheduling requests (i.e., ScheduleRequest instances) for the function specified by function_name. Return type:list

get_step_form_class()

get_step_values(step_number=None)

on_app_exit()

Handler called just before the MicroDrop application exits.

on_app_options_changed(plugin_name)

Handler called when the app options are changed for a particular plugin. This will, for example, allow for GUI elements to be updated.

Parameters:plugin (str) – Plugin name for which the app options changed

on_dmf_device_changed(dmf_device)

Handler called when a DMF device is modified (e.g., channel assignment, scaling, etc.).

Parameters:dmf_device (microdrop.dmf_device.DmfDevice) –

on_dmf_device_saved(dmf_device)

Handler called when a DMF device is saved.

Parameters:dmf_device (microdrop.dmf_device.DmfDevice) –

on_dmf_device_swapped(old_dmf_device, dmf_device)

Handler called when a different DMF device is swapped in (e.g., when a new device is loaded).

Parameters:

• old_dmf_device (microdrop.dmf_device.DmfDevice) – Original device.
• dmf_device (microdrop.dmf_device.DmfDevice) – New device.

on_experiment_log_changed(experiment_log)

Handler called when the current experiment log changes (e.g., when a protocol finishes running.

Parameters:experiment_log (microdrop.experiment_log.ExperimentLog) – Reference to new experiment log instance.

on_experiment_log_selection_changed(data)

Handler called whenever the experiment log selection changes.

Parameters:data – experiment log data (list of dictionaries, one per step) for the selected steps

on_export_experiment_log_data(experiment_log)

Handler called when the experiment log is exported.

Parameters:log – experiment log data (list of dictionaries, one per step) for the selected steps Returns:A dictionary of pandas.DataFrame objects containing any relevant data that should be exported by the plugin, each keyed by a unique name.

on_metadata_changed(schema, original_metadata, metadata)

Handler called each time the experiment metadata has changed.

Parameters:

• schema (dict) – jsonschema schema definition for metadata.
• original_metadata – Original metadata.
• metadata – New metadata matching schema

on_plugin_disable()

Handler called once the plugin instance is disabled.

on_plugin_disabled(env, plugin)

Handler called to notify that a plugin has been disabled.

Note that this signal is broadcast to all plugins implementing the IPlugin interface, whereas the on_plugin_disable() method is called directly on the plugin that is being disabled.

Parameters:

• env (str) – pyutilib plugin environment.
• plugin (str) – Plugin name.

on_plugin_enable()

Handler called once the plugin instance is enabled.

Note: if you inherit your plugin from AppDataController and don’t implement this handler, by default, it will automatically load all app options from the config file. If you decide to overide the default handler, you should call:

AppDataController.on_plugin_enable(self)

to retain this functionality.

on_plugin_enabled(env, plugin)

Handler called to notify that a plugin has been enabled.

Note that this signal is broadcast to all plugins implementing the IPlugin interface, whereas the on_plugin_enable() method is called directly on the plugin that is being enabled.

Parameters:

• env (str) – pyutilib plugin environment.
• plugin (str) – Plugin name.

on_protocol_changed()

Handler called when a protocol is modified.

on_protocol_finished()

Handler called when a protocol finishes (i.e., runs the last step of the final repetition).

on_protocol_pause()

Handler called when a protocol is paused.

on_protocol_run()

Handler called when a protocol starts running.

on_protocol_swapped(old_protocol, protocol)

Handler called when a different protocol is swapped in (e.g., when a protocol is loaded or a new protocol is created).

Parameters:

• old_protocol (microdrop.protocol.Protocol) – Original protocol.
• protocol (microdrop.protocol.Protocol) – New protocol.

on_step_complete(plugin_name, return_value=None)

Handler called whenever a plugin completes a step.

Returns:

• 'Repeat': repeat the step
• 'Fail': unrecoverable error (stop the protocol)

Return type:str or None

on_step_created(step_number)

Handler called whenever a new step is created.

Parameters:step_number (int) – New step number.

on_step_options_changed(plugin, step_number)

Handler called when the step options are changed for a particular plugin. This will, for example, allow for GUI elements to be updated based on step specified.

Parameters:

• plugin (SingletonPlugin) – Plugin instance for which the step options changed.
• step_number (int) – Step number that the options changed for.

on_step_options_swapped(plugin, old_step_number, step_number)

Handler called when the step options are changed for a particular plugin. This will, for example, allow for GUI elements to be updated based on step specified.

Parameters:

• plugin (SingletonPlugin) – Plugin instance for which the step options changed.
• old_step_number (int) – Original step number.
• step_number (int) – New step number.

on_step_run()

Handler called whenever a step is executed. Note that this signal is only emitted in realtime mode or if a protocol is running.

Plugins that handle this signal must emit the on_step_complete() signal once they have completed the step. The protocol controller will wait until all plugins have completed the current step before proceeding.

Returns:

• 'Repeat': repeat the step
• 'Fail': unrecoverable error (stop the protocol)

Return type:str or None

on_step_swapped(old_step_number, step_number)

Handler called when the current step is swapped.

Parameters:

• old_step_number (int) – Original step number.
• step_number (int) – New step number.

class microdrop.interfaces.IWaveformGenerator

Bases: pyutilib.component.core.core.Interface

Methods

set_frequency(frequency)	Set the waveform frequency.
set_voltage(voltage)	Set the waveform voltage.

set_frequency(frequency)

Set the waveform frequency.

Parameters:frequency – frequency in Hz

set_voltage(voltage)

Set the waveform voltage.

Parameters:voltage – RMS voltage

logger Module

class microdrop.logger.CustomHandler

Bases: logging.Handler

Attributes

name

Methods

acquire()	Acquire the I/O thread lock.
addFilter(filter)	Add the specified filter to this handler.
close()	Tidy up any resources used by the handler.
createLock()	Acquire a thread lock for serializing access to the underlying I/O.
emit(record)
filter(record)	Determine if a record is loggable by consulting all the filters.
flush()	Ensure all logging output has been flushed.
format(record)	Format the specified record.
get_name()
handle(record)	Conditionally emit the specified logging record.
handleError(record)	Handle errors which occur during an emit() call.
release()	Release the I/O thread lock.
removeFilter(filter)	Remove the specified filter from this handler.
setFormatter(fmt)	Set the formatter for this handler.
setLevel(level)	Set the logging level of this handler.
set_name(name)

emit(record)

microdrop Module

microdrop.microdrop.except_handler(*args, **kwargs)

microdrop.microdrop.initialize_core_plugins()

microdrop.microdrop.main()

plugin_helpers Module

class microdrop.plugin_helpers.AppDataController

Bases: object

Methods

get_app_fields()
get_app_form_class()
get_app_value(key)
get_app_values()
get_default_app_options()
get_plugin_app_values(plugin_name)
on_plugin_enable()	Handler called once the plugin instance has been enabled.
set_app_values(values_dict)

get_app_fields()

get_app_form_class()

get_app_value(key)

get_app_values()

get_default_app_options()

static get_plugin_app_values(plugin_name)

on_plugin_enable()

Handler called once the plugin instance has been enabled.

set_app_values(values_dict)

class microdrop.plugin_helpers.PluginMetaData

Bases: tuple

Attributes

package_name	Alias for field number 0
plugin_name	Alias for field number 1
version	Alias for field number 2

Methods

as_dict()
count(...)
from_dict(data)
index((value, [start, ...)	Raises ValueError if the value is not present.

as_dict()

static from_dict(data)

package_name

Alias for field number 0

plugin_name

Alias for field number 1

version

Alias for field number 2

class microdrop.plugin_helpers.StepOptionsController

Bases: object

Methods

get_default_step_options()
get_plugin_step_values(plugin_name[, ...])
get_step(step_number)
get_step_fields()
get_step_form_class()
get_step_number(default)
get_step_options([step_number])
get_step_value(name[, step_number])
get_step_values([step_number])
set_step_values(values_dict[, step_number])	Consider a scenario where most step options are simple types that are supported by flatland and can be listed in StepOptions (e.g., Integer, Boolean, etc.), but there is at least one step option that is a type not supported by flatland, such as a numpy.array.

get_default_step_options()

static get_plugin_step_values(plugin_name, step_number=None)

get_step(step_number)

get_step_fields()

get_step_form_class()

get_step_number(default)

get_step_options(step_number=None)

get_step_value(name, step_number=None)

get_step_values(step_number=None)

set_step_values(values_dict, step_number=None)

Consider a scenario where most step options are simple types that are supported by flatland and can be listed in StepOptions (e.g., Integer, Boolean, etc.), but there is at least one step option that is a type not supported by flatland, such as a numpy.array.

Currently, this requires custom handling for all methods related to step options, as in the case of the DMF control board. Instead, during validation of step option values, we could simply exclude options that are not listed in the StepOptions definition from the validation, but pass along all values to be saved in the protocol.

This should maintain backwards compatibility while simplifying the addition of arbitrary Python data types as step options.

microdrop.plugin_helpers.from_dict(data)

microdrop.plugin_helpers.get_plugin_info(plugin_root)

Load the plugin properties metadata from a plugin directory.

Parameters:plugin_root (str) – Path to plugin directory. Returns:Plugin metadata in the form (package_name, plugin_name, version).

Returns None if plugin is not installed or is invalid.

Return type:namedtuple or None

microdrop.plugin_helpers.hub_execute(*args, **kwargs)

microdrop.plugin_helpers.hub_execute_async(*args, **kwargs)

plugin_manager Module

class microdrop.plugin_manager.ScheduleRequest

Bases: tuple

Attributes

after	Alias for field number 1
before	Alias for field number 0

Methods

count(...)
index((value, [start, ...)	Raises ValueError if the value is not present.

after

Alias for field number 1

before

Alias for field number 0

microdrop.plugin_manager.disable(name, env='microdrop.managed')

Disable specified plugin.

Parameters:

• name (str) –

  Plugin name (e.g., microdrop.zmq_hub_plugin).

  Corresponds to plugin_name key in plugin properties.yml file.

• env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘).

microdrop.plugin_manager.emit_signal(function, args=None, interface=<class 'microdrop.interfaces.IPlugin'>)

Call specified function on each enabled plugin implementing the function and collect results.

Parameters:

• function (str) – Name of function to generate schedule for.
• interface (class, optional) – Plugin interface class.

Returns:

Mapping from each service name to the respective function return value.

Return type:

dict

microdrop.plugin_manager.enable(name, env='microdrop.managed')

Enable specified plugin.

Parameters:

• name (str) –

  Plugin name (e.g., microdrop.zmq_hub_plugin).

  Corresponds to plugin_name key in plugin properties.yml file.

• env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘).

microdrop.plugin_manager.get_observers(function, interface=<class 'microdrop.interfaces.IPlugin'>)

Get dictionary of observers implementing the specified function.

Parameters:

• function (str) – Name of function to generate schedule for.
• interface (class, optional) – Plugin interface class.

Returns:

Mapping from service names to service instances.

Return type:

dict

microdrop.plugin_manager.get_plugin_names(env=None)

Parameters:env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘). Returns:List of plugin names (e.g., ['StepLabelPlugin', ...]). Return type:list(str)

microdrop.plugin_manager.get_plugin_package_name(module_name)

Parameters:module_name (str) – Fully-qualified class name (e.g., 'plugins.dmf_control_board_plugin'). Returns:Relative module name (e.g., 'dmf_control_board_plugin') Return type:str

microdrop.plugin_manager.get_schedule(observers, function)

Generate observer order based on scheduling requests for specified function.

Parameters:

• observers (dict) – Mapping from service names to service instances.
• function (str) – Name of function to generate schedule for.

Returns:

List of observer service names in scheduled order.

Return type:

list

microdrop.plugin_manager.get_service_class(name, env='microdrop.managed')

Parameters:

• name (str) – Plugin class name (e.g., App).
• env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘).

Returns:

Class type matching specified plugin class name.

..notes::

Returns actual class type – not an instance of the plugin service.

Return type:

class

microdrop.plugin_manager.get_service_instance(class_, env='microdrop.managed')

Parameters:

• class (class) – Plugin class type.
• env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘).

Returns:

Registered service instance for the specified plugin class type.

Returns None if no service is registered for the specified plugin class type.

Return type:

object or None

microdrop.plugin_manager.get_service_instance_by_name(name, env='microdrop.managed')

Parameters:

• name (str) –

  Plugin name (e.g., microdrop.zmq_hub_plugin).

  Corresponds to plugin_name key in plugin properties.yml file.

• env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘).

Returns:

Active service instance matching specified plugin name.

Return type:

object

Raises:

KeyError – If no plugin is found registered with the specified name.

microdrop.plugin_manager.get_service_instance_by_package_name(name, env='microdrop.managed')

Parameters:

• name (str) –

  Plugin Python module name (e.g., dmf_control_board_plugin).

  Corresponds to package_name key in plugin properties.yml file.

• env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘).

Returns:

Active service instance matching specified plugin module name.

Return type:

object

microdrop.plugin_manager.get_service_names(env='microdrop.managed')

Parameters:env (str, optional) – Name of pyutilib.component.core plugin environment (e.g., 'microdrop.managed‘). Returns:List of plugin names (e.g., ['microdrop.step_label_plugin', ...]). Return type:list

microdrop.plugin_manager.load_plugins(plugins_dir='plugins', import_from_parent=True)

Import each Python plugin module in the specified directory and create an instance of each contained plugin class for which an instance has not yet been created.

Parameters:

• plugins_dir (str) – Directory containing zero or more Python plugin modules to import.
• import_from_parent (bool) –

  Add parent of specified directory to system path and import <parent>.<module>.

  ..notes::

  Not recommended, but kept as default to maintain legacy protocol compatibility.

Returns:

Newly created plugins (plugins are not recreated if they were previously loaded.)

Return type:

list

microdrop.plugin_manager.log_summary()

Dump summary of plugins to log.

protocol Module

class microdrop.protocol.Protocol(name=None)

Attributes

plugins

Methods

current_step()
delete_step(step_number)
delete_steps(step_ids)
first_step()
from_dict(protocol_dict)	param protocol_dict:
from_json(istream)	param istream:Input JSON to read protocol from.
from_ndjson([istream])	Read protocol from newline delimited JSON (i.e., ndjson, see specification).
get_data(plugin_name)
get_step([step_number])
get_step_number(default)
goto_step(step_number)
insert_step([step_number, value, notify])
insert_steps([step_number, count, values])
last_step()
load(filename)	Load a Protocol from a file.
next_repetition()
next_step()
plugin_name_lookup(name[, re_pattern])
prev_step()
remove_exceptions(exceptions[, inplace])
save(filename[, format])
set_data(plugin_name, data)
to_dict()	returns:Dictionary object with the following top-level keys:
to_frame()	returns:Data frame with multi-index columns, indexed first by plugin name,
to_json([ostream])	param ostream:Output stream to write to.
to_ndjson([ostream, ignore_errors])	Write protocol as newline delimited JSON (i.e., ndjson, see specification).

class_version = '0.2.0'

current_step()

delete_step(step_number)

delete_steps(step_ids)

first_step()

classmethod from_dict(protocol_dict)

Parameters:protocol_dict (dict) –

Dictionary object with the following top-level keys:

• name: Protocol name.
• version: Protocol version.
• steps: List of dictionaries, each containing data for a single protocol step.
• uuid, optional: Universally unique identifier.

Returns:MicroDrop protocol. Return type:Protocol

classmethod from_json(istream)

Parameters:istream (str or file-like) –

Input JSON to read protocol from.

If file-like, read from as an input stream.

If a string, assume input is JSON serialized protocol string.

Returns:MicroDrop protocol. Return type:Protocol

See also

to_json(), to_dict(), to_ndjson()

classmethod from_ndjson(istream=None)

Read protocol from newline delimited JSON (i.e., ndjson, see specification).

Parameters:istream (str or file-like) –

Input new-line delimited JSON to read protocol from.

If file-like, read from as an input stream.

If a string, assume input is new-line delimited JSON serialized protocol string.

Returns:MicroDrop protocol. Return type:Protocol

See also

protocol_to_ndjson(), to_ndjson(), to_json()

get_data(plugin_name)

get_step(step_number=None)

get_step_number(default)

goto_step(step_number)

insert_step(step_number=None, value=None, notify=True)

insert_steps(step_number=None, count=None, values=None)

last_step()

classmethod load(filename)

Load a Protocol from a file.

Parameters:

filename (str) – Path to file.

Raises:

• TypeError – If file is not a Protocol.
• FutureVersionError – If file was written by a future version of the software.

next_repetition()

next_step()

plugin_name_lookup(name, re_pattern=False)

plugins

prev_step()

remove_exceptions(exceptions, inplace=False)

save(filename, format='pickle')

set_data(plugin_name, data)

to_dict()

Returns:Dictionary object with the following top-level keys: - name: Protocol name. - version: Protocol version. - steps: List of dictionaries, each containing data for a single protocol step. - uuid, optional: Universally unique identifier. Return type:dict

to_frame()

Returns:Data frame with multi-index columns, indexed first by plugin name, then by plugin step field name.

Note

If an exception is encountered while processing a plugin value, the plugin causing the exception is skipped and protocol values related to the plugin are not included in the result.

Return type:pandas.DataFrame

See also

to_json(), to_ndjson()

to_json(ostream=None, **kwargs)

Parameters:ostream (file-like, optional) – Output stream to write to. Returns:If ostream parameter is None, return serialized protocol in JSON format as string.

See protocol_to_json() for details on JSON object structure.

Return type:None or str

See also

to_dict(), to_ndjson()

to_ndjson(ostream=None, ignore_errors=False)

Write protocol as newline delimited JSON (i.e., ndjson, see specification).

Parameters:

• ostream (file-like, optional) – Output stream to write to.
• ignore_errors (bool, optional) – If True, skip any step plugin data that causes an error during serialization.

Returns:

If ostream parameter is None, return output as string.

Return type:

None or str

Raises:

SerializationError – If exception occurs during serialization.

The SerializationError object includes an exceptions attribute containing details on errors encountered. See SerializationError class for more details.

See also

protocol_to_ndjson(), to_json()

exception microdrop.protocol.SerializationError(message, exceptions)

Bases: exceptions.Exception

message

str – Error message.

exceptions

list – List of objects corresponding to serialization exceptions.

Objects are in the following form:

{'step': <step number>, 'plugin': <plugin name>, 'data': <plugin data>, error': <error message>}

class microdrop.protocol.Step(plugin_data=None)

Bases: object

Attributes

plugins

Methods

copy()
get_data(plugin_name)
plugin_name_lookup(name[, re_pattern])
set_data(plugin_name, data)

copy()

get_data(plugin_name)

plugin_name_lookup(name, re_pattern=False)

plugins

set_data(plugin_name, data)

microdrop.protocol.protocol_dict_remove_exceptions(protocol_dict, exceptions, inplace=False)

Parameters:

• protocol_dict (dict) –

  Dictionary object with the following top-level keys:

  • name: Protocol name.
  • version: Protocol version.
  • steps: List of dictionaries, each containing data for a single protocol step.
  • uuid, optional: Universally unique identifier.

• exceptions (list-like) – Exceptions in format recorded in exceptions attribute of SerializationError instances.
• inplace (bool, optional) –

  If True, directly modify protocol_dict.

  Otherwise, return modified copy.

  Default is False.

Returns:

Modified copy of protocol_dict if inplace is False.

Return type:

dict or None

See also

protocol_dict_remove_exceptions()

microdrop.protocol.protocol_dict_transform_plugin_data(protocol_dict, transform_func, inplace=False)

Parameters:

• protocol_dict (dict) –

  A MicroDrop protocol in dictionary format.

  See protocol_to_dict() and Protocol.to_dict().

• transform_func (function) –

  Function to transform a plugin data dictionary.

  Must accept a plugin data dict as the only argument and return a dict in the same form, but potentially with different contents.

• inplace (bool, optional) –

  If True, directly modify protocol_dict.

  Otherwise, return modified copy.

  Default is False.

Returns:

A MicroDrop protocol in dictionary format with protocol-level and step-level plugin data dictionaries transformed using transform_func.

Return type:

dict

microdrop.protocol.protocol_from_dict(protocol_dict)

Convert a protocol dictionary representation to a Protocol.

Each plugin MAY independently implement a custom to_dict method on the respective plugin step options class, along with a corresponding from_dict class method. If these methods are implemented, the fully-qualified class name is looked up in the respective __class__ item in the step plugin data to reconstruct the step options with the corresponding from_dict class method.

Parameters:protocol_dict (dict) –

Dictionary object with the following top-level keys:

• name: Protocol name.
• version: Protocol version.
• steps: List of dictionaries, each containing data for a single protocol step.
• uuid, optional: Universally unique identifier.

Returns:MicroDrop protocol. Return type:Protocol

microdrop.protocol.protocol_remove_exceptions(protocol, exceptions, inplace=False)

Parameters:

• protocol (Protocol) – MicroDrop protocol.
• exceptions (list-like) – Exceptions in format recorded in exceptions attribute of SerializationError instances.
• inplace (bool, optional) –

  If True, directly modify protocol.

  Otherwise, return modified copy.

  Default is False.

Returns:

Modified copy of protocol if inplace is False.

Return type:

Protocol or None

See also

protocol_dict_remove_exceptions()

microdrop.protocol.protocol_to_dict(protocol, loaded=True)

Convert a Protocol to a dictionary representation.

Each plugin MAY independently implement a custom to_dict method on the respective plugin step options class, along with a corresponding from_dict class method. If these methods are implemented, the resulting dictionary from to_dict MUST contain the key __class__ indicating the fully-qualified class name of the step options (used to reconstruct the step options with the from_dict class method).

Parameters:

• protocol (Protocol) –

  MicroDrop protocol.

  Note

  A MicroDrop protocol object is stored as pickled in the protocol file in each experiment log directory.

• loaded (bool, optional) – True if protocol was loaded using Protocol.load().

Returns:

Dictionary object with the following top-level keys:

• name: Protocol name.
• version: Protocol version.
• steps: List of dictionaries, each containing data for a single protocol step.
• uuid, optional: Universally unique identifier.

Return type:

dict

microdrop.protocol.protocol_to_frame(protocol_i)

Parameters:protocol_i (Protocol) –

MicroDrop protocol.

Note

A MicroDrop protocol object is stored as pickled in the protocol file in each experiment log directory.

Returns:Data frame with rows indexed by 0-based step number and columns indexed (multi-index) first by plugin name, then by step field name.

Note

Values may be Python objects. In future versions of MicroDrop, values may be restricted to json compatible types.

Return type:pandas.DataFrame

microdrop.protocol.protocol_to_json(protocol, validate=True, ostream=None, json_kwargs=None, **kwargs)

Parameters:

• protocol (Protocol) – MicroDrop protocol.
• validate (bool, optional) – If True, validate protocol in dictionary form before serializing to JSON.
• ostream (file-like, optional) – Output stream to write to.
• kwargs (bool, optional) – True if protocol was loaded using Protocol.load().

Returns:

If ostream parameter is None, return serialized protocol in JSON format as string.

See protocol_to_dict() for details on JSON object structure.

Return type:

None or str

microdrop.protocol.protocol_to_ndjson(protocol, ostream=None)

Write protocol as newline delimited JSON (i.e., ndjson, see specification).

The first row is a header JSON object containing at least the keys name and version.

Each subsequent line in the output is a nested JSON object, one line per protocol step. The keys of the top-level object of each step object correspond to plugin names. The second-level keys correspond to the step field name.

Parameters:

• protocol (Protocol) – MicroDrop protocol.
• ostream (file-like, optional) – Output stream to write to.

Returns:

If ostream parameter is None, return output as string.

Return type:

None or str

Raises:

SerializationError – If exception occurs during serialization.

The SerializationError object includes an exceptions attribute containing details on errors encountered. See SerializationError class for more details.

See also

protocol_to_json()

microdrop.protocol.safe_pickle_loads(data)

Parameters:data (bytes) – Pickled data. Returns:Deserialized pickled object.

If exception occurs during unpickling, error is logged and None is returned.

Return type:object or None

microdrop.protocol.serialize_protocol(protocol_dict, serialize_func)

Parameters:

• protocol_dict (dict) –

  A MicroDrop protocol in dictionary format.

  See protocol_to_dict() and Protocol.to_dict().

• serialize_func (function) – Serialization function.

Returns:

Result of call to serialize_func.

Return type:

object

Raises:

SerializationError – If exception occurs during serialization.

The SerializationError object includes an exceptions attribute containing details on errors encountered. See SerializationError class for more details.

Subpackages

• bin Package
  • create_portable_config Module
  • latest_versions Module
• core_plugins Package
  • Subpackages
    • device_info_plugin Package
      • device_info_plugin Package
      • on_plugin_install Module
      • release Module
      • rename Module
    • electrode_controller_plugin Package
      • electrode_controller_plugin Package
      • on_plugin_install Module
      • release Module
      • rename Module
    • zmq_hub_plugin Package
      • zmq_hub_plugin Package
      • on_plugin_install Module
      • release Module
      • rename Module
• gui Package
  • app_options_controller Module
  • cairo_view Module
  • channel_sweep Module
  • config_controller Module
  • dmf_device_controller Module
  • dmf_device_controller.video Module
  • dmf_device_view.video Module
  • experiment_log_controller Module
  • field_filter_controller Module
  • main_window_controller Module
  • plugin_download_dialog Module
  • plugin_manager_controller Module
  • plugin_manager_dialog Module
  • protocol_controller Module
  • protocol_grid_controller Module
• tests Package
  • test_dmf_device Module
  • test_experiment_log Module
  • test_protocol Module
  • update_dmf_control_board Module