microdrop Package¶
microdrop
Package¶
app
Module¶
app_context
Module¶
config
Module¶
-
class
microdrop.config.
Config
(filename=None)[source]¶ 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)[source]¶ 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.
-
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
[source]¶ Bases:
exceptions.Exception
dmf_device
Module¶
-
exception
microdrop.dmf_device.
DeviceScaleNotSet
[source]¶ Bases:
exceptions.Exception
-
class
microdrop.dmf_device.
DmfDevice
(svg_filepath, name=None, **kwargs)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ 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)[source]¶ Returns: A list of nodes on the shortest path from source to target. Return type: list
-
get_actuated_electrodes_area
(electrode_states)[source]¶ 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
()[source]¶ Returns: Tuple containing origin-x, origin-y, width and height, respectively. Return type: tuple
-
get_electrode_areas
()[source]¶ Returns: Area of each electrode in square millimeters, indexed by electrode identifier. Return type: pandas.Series
-
get_electrode_channels
()[source]¶ 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
()[source]¶ 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)[source]¶ 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.
-
set_electrode_channels
(electrode_id, channels)[source]¶ 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:
-
-
microdrop.dmf_device.
extract_channels
(df_shapes)[source]¶ 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)[source]¶ 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: -
class_version
= '0.3.0'¶
-
classmethod
load
(filename)[source]¶ 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.
-
to_frame
()[source]¶ 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)[source]¶ 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.
ILoggingPlugin
[source]¶ Bases:
pyutilib.component.core.core.Interface
Methods
on_critical
(record)on_debug
(record)on_error
(record)on_info
(record)on_warning
(record)
-
class
microdrop.interfaces.
IPlugin
[source]¶ 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)[source]¶ Parameters: function_name (str) – Plugin callback function name. Returns: List of scheduling requests (i.e., ScheduleRequest
instances) for the function specified byfunction_name
.Return type: list
-
on_app_options_changed
(plugin_name)[source]¶ 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)[source]¶ 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)[source]¶ Handler called when a DMF device is saved.
Parameters: dmf_device (microdrop.dmf_device.DmfDevice) –
-
on_dmf_device_swapped
(old_dmf_device, dmf_device)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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_disabled
(env, plugin)[source]¶ Handler called to notify that a plugin has been disabled.
Note that this signal is broadcast to all plugins implementing the
IPlugin
interface, whereas theon_plugin_disable()
method is called directly on the plugin that is being disabled.Parameters:
-
on_plugin_enable
()[source]¶ 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)[source]¶ Handler called to notify that a plugin has been enabled.
Note that this signal is broadcast to all plugins implementing the
IPlugin
interface, whereas theon_plugin_enable()
method is called directly on the plugin that is being enabled.Parameters:
-
on_protocol_finished
()[source]¶ Handler called when a protocol finishes (i.e., runs the last step of the final repetition).
-
on_protocol_swapped
(old_protocol, protocol)[source]¶ 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)[source]¶ 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)[source]¶ Handler called whenever a new step is created.
Parameters: step_number (int) – New step number.
-
on_step_options_changed
(plugin, step_number)[source]¶ 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)[source]¶ 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:
-
on_step_run
()[source]¶ 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
-
-
class
microdrop.interfaces.
IWaveformGenerator
[source]¶ Bases:
pyutilib.component.core.core.Interface
Methods
set_frequency
(frequency)Set the waveform frequency. set_voltage
(voltage)Set the waveform voltage.
logger
Module¶
-
class
microdrop.logger.
CustomHandler
[source]¶ 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)
microdrop
Module¶
plugin_helpers
Module¶
-
class
microdrop.plugin_helpers.
AppDataController
[source]¶ 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)
-
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
[source]¶ 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. -
set_step_values
(values_dict, step_number=None)[source]¶ 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.
get_plugin_info
(plugin_root)[source]¶ 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
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')[source]¶ Disable specified plugin.
Parameters:
-
microdrop.plugin_manager.
emit_signal
(function, args=None, interface=<class 'microdrop.interfaces.IPlugin'>)[source]¶ 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:
-
microdrop.plugin_manager.
enable
(name, env='microdrop.managed')[source]¶ Enable specified plugin.
Parameters:
-
microdrop.plugin_manager.
get_observers
(function, interface=<class 'microdrop.interfaces.IPlugin'>)[source]¶ 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:
-
microdrop.plugin_manager.
get_plugin_names
(env=None)[source]¶ 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)[source]¶ 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)[source]¶ Generate observer order based on scheduling requests for specified function.
Parameters: Returns: List of observer service names in scheduled order.
Return type: list
-
microdrop.plugin_manager.
get_service_class
(name, env='microdrop.managed')[source]¶ Parameters: 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')[source]¶ 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:
-
microdrop.plugin_manager.
get_service_instance_by_name
(name, env='microdrop.managed')[source]¶ Parameters: Returns: Active service instance matching specified plugin name.
Return type: 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')[source]¶ Parameters: Returns: Active service instance matching specified plugin module name.
Return type:
-
microdrop.plugin_manager.
get_service_names
(env='microdrop.managed')[source]¶ 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)[source]¶ 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: Returns: Newly created plugins (plugins are not recreated if they were previously loaded.)
Return type: list
protocol
Module¶
-
class
microdrop.protocol.
Protocol
(name=None)[source]¶ 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'¶
-
classmethod
from_dict
(protocol_dict)[source]¶ 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)[source]¶ 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
-
classmethod
from_ndjson
(istream=None)[source]¶ 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
-
classmethod
load
(filename)[source]¶ Load a Protocol from a file.
Parameters: filename (str) – Path to file.
Raises: TypeError
– If file is not aProtocol
.FutureVersionError
– If file was written by a future version of the software.
-
plugins
¶
-
to_dict
()[source]¶ 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
()[source]¶ 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
(ostream=None, **kwargs)[source]¶ Parameters: ostream (file-like, optional) – Output stream to write to. Returns: If ostream
parameter isNone
, 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_ndjson
(ostream=None, ignore_errors=False)[source]¶ 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 isNone
, return output as string.Return type: Raises: SerializationError
– If exception occurs during serialization.The
SerializationError
object includes anexceptions
attribute containing details on errors encountered. SeeSerializationError
class for more details.See also
-
-
exception
microdrop.protocol.
SerializationError
(message, exceptions)[source]¶ 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)[source]¶ Bases:
object
Attributes
plugins
Methods
copy
()get_data
(plugin_name)plugin_name_lookup
(name[, re_pattern])set_data
(plugin_name, data)-
plugins
¶
-
-
microdrop.protocol.
protocol_dict_remove_exceptions
(protocol_dict, exceptions, inplace=False)[source]¶ 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 ofSerializationError
instances. - inplace (bool, optional) –
If
True
, directly modifyprotocol_dict
.Otherwise, return modified copy.
Default is
False
.
Returns: Modified copy of
protocol_dict
ifinplace
isFalse
.Return type: See also
- protocol_dict (dict) –
-
microdrop.protocol.
protocol_dict_transform_plugin_data
(protocol_dict, transform_func, inplace=False)[source]¶ Parameters: - protocol_dict (dict) –
A MicroDrop protocol in dictionary format.
See
protocol_to_dict()
andProtocol.to_dict()
. - transform_func (function) –
Function to transform a plugin data dictionary.
Must accept a plugin data
dict
as the only argument and return adict
in the same form, but potentially with different contents. - inplace (bool, optional) –
If
True
, directly modifyprotocol_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: - protocol_dict (dict) –
-
microdrop.protocol.
protocol_from_dict
(protocol_dict)[source]¶ 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 correspondingfrom_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 correspondingfrom_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)[source]¶ Parameters: - protocol (Protocol) – MicroDrop protocol.
- exceptions (list-like) – Exceptions in format recorded in
exceptions
attribute ofSerializationError
instances. - inplace (bool, optional) –
If
True
, directly modifyprotocol
.Otherwise, return modified copy.
Default is
False
.
Returns: Modified copy of
protocol
ifinplace
isFalse
.Return type: See also
-
microdrop.protocol.
protocol_to_dict
(protocol, loaded=True)[source]¶ 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 correspondingfrom_dict
class method. If these methods are implemented, the resulting dictionary fromto_dict
MUST contain the key__class__
indicating the fully-qualified class name of the step options (used to reconstruct the step options with thefrom_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 usingProtocol.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: - protocol (Protocol) –
-
microdrop.protocol.
protocol_to_frame
(protocol_i)[source]¶ 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)[source]¶ 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 usingProtocol.load()
.
Returns: If
ostream
parameter isNone
, return serialized protocol in JSON format as string.See
protocol_to_dict()
for details on JSON object structure.Return type:
-
microdrop.protocol.
protocol_to_ndjson
(protocol, ostream=None)[source]¶ 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
andversion
.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 isNone
, return output as string.Return type: Raises: SerializationError
– If exception occurs during serialization.The
SerializationError
object includes anexceptions
attribute containing details on errors encountered. SeeSerializationError
class for more details.See also
-
microdrop.protocol.
safe_pickle_loads
(data)[source]¶ 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)[source]¶ Parameters: - protocol_dict (dict) –
A MicroDrop protocol in dictionary format.
See
protocol_to_dict()
andProtocol.to_dict()
. - serialize_func (function) – Serialization function.
Returns: Result of call to
serialize_func
.Return type: Raises: SerializationError
– If exception occurs during serialization.The
SerializationError
object includes anexceptions
attribute containing details on errors encountered. SeeSerializationError
class for more details.- protocol_dict (dict) –
Subpackages¶
- bin Package
- core_plugins Package
- gui Package
app_options_controller
Modulecairo_view
Modulechannel_sweep
Moduleconfig_controller
Moduledmf_device_controller
Moduledmf_device_controller.video
Moduledmf_device_view.video
Moduleexperiment_log_controller
Modulefield_filter_controller
Modulemain_window_controller
Moduleplugin_download_dialog
Moduleplugin_manager_controller
Moduleplugin_manager_dialog
Moduleprotocol_controller
Moduleprotocol_grid_controller
Module
- tests Package