5. Library Reference — ESIBD Explorer 0.6 documentation

# 5. Library Reference

## 5.1. The plugin module

This module contains only `plugins` and plugin templates. The user controls generally have a large amount of logic integrated and can act as an intelligent database. This avoids complex and error prone synchronization between redundant data in the UI and a separate database. Every parameter should only exist in one unique location at run time. Separating the logic from the PyQt specific UI elements may be required in the future, but only if there are practical and relevant advantages that outweigh the drawbacks of managing syncronization.

class esibd.plugins.Device(*args: Any, **kwargs: Any)

  A `Device` manages access to parameters on a physical device, represented as a `Channel`.

  class SignalCommunicate(*args: Any, **kwargs: Any)

    Object than bundles pyqtSignals for the device

    appendDataSignal

      Signal that triggers appending of data from channels to history.

    plotSignal

      Signal that triggers plotting of history.

  addChannel(item, index=None)

    Maps dictionary to `Channel`.

  appendOutputData(f, default=False)

    Appends `Device` data to hdf file.

  apply(apply=False)

    Applies `Channel` values to physical devices. Only used by input `devices`.

    Parameters:

      apply (bool, optional) – If false, only values that have changed since last apply will be updated, defaults to False

  channelType

    The type of channel used.

    alias of `Channel`

  channels: [<class 'esibd.core.Channel'>]

    List of `channels`.

  close()

    Closes plugin cleanly without leaving any data or communication running. Extend to make sure your custom data and custom communication is closed as well.

  convertDataDisplay(data)

    Overwrite to apply scaling and offsets to data before it is displayed. Use, e.g., to convert to another unit.

  exportConfiguration(file=None, default=False)

    Saves an .ini or .h5 file which contains the configuration for this `Device`. The .ini file can be easily edited manually with a text editor to add more `channels`.

  getChannelByName(name)

    Returns a device specific channel based on its unique name.

  getDefaultSettings()

    Define device specific settings that will be added to the general settings tab. Settings will be generated automatically if not found in the settings file. Overwrite and extend as needed.

  getSelectedChannel()

    Returns selected channel. Note, channels can only be selected in advanced mode.

  getUnit()

    Overwrite if you want to change units dynamically.

  init()

    Extend device initialization as needed. Note, this inits the device GUI. Device communication is initialized by the corresponding `esibd.core.DeviceController`

  initialized()

    Extend to indicate when the device is initialized.

  inout: INOUT

    Flag specifying if this is an input or output device.

  intervalChanged()

    Extend to add code to be executed in case the Interval changes.

  liveDisplay: LiveDisplay

    Internal plugin to display data in real time.

  loadConfiguration(file=None, default=False)

    Loads `Channel` configuration from file. If only values should be loaded without complete reinitialization, use ‘load’ function instead.

    Parameters:

      - file (pathlib.Path, optional) – File from which to load configuration, defaults to None

      - default (bool, optional) – Use internal configuration file if True, defaults to False

  loadValues(file=None)

    Loads values only, instead of entire configuration, for `channels` matching in file and current configuraion. Channels that exist in the file but not in the current configuration will be ignored. Only used by input devices.

  name: str = 'Device'

    A unique name that will be used in the graphic user interface. Plugins can be accessed directly from the Console using their name.

  plot()

    Plots current values from all real `channels`.

  pluginType: PluginManager.TYPE = 'Input Device'

    `Devices` are categorized as input or output devices. Overwrite with `OUTPUTDEVICE` after inheriting if applicable.

  restoreOutputData()

    Restores data from internal restore file.

  runDataThread(recording)

    Regulartly triggers reading and appending of data. This uses the current value of `channels` which is updated independently by the corresponding `DeviceController`.

  setBackground()

    Sets the background based on current channel values. Only used by output devices.

  startAcquisition()

    Extend to start all device related communication.

  staticDisplay: StaticDisplay

    Internal plugin to display data from file.

  stop()

    Stops recording and also closes all device communication. Extend to add custom code to close device communication.

  stopAcquisition()

    Extend to stop all device related communication.

  supportsFile(file)

    Tests if a file is supported by the plugin.

    Parameters:

      file (pathlib.Path) – File that has been selected by the user.

    Returns:

      Returns True if the file is supported by the plugin. Test if supported based on file extension or content.

    Return type:

      bool

  toggleRecording()

    Toggle recoding of data in `LiveDisplay`.

  unit: str = ''

    Unit used in user interface.

  updateChannelConfig(items, file)

    Scans for changes and displays change log before overwriting old channel configuraion.

  updateValues(N=2, apply=False)

    Updates channel values based on equations. This minimal implementation will not give a warning about circular definitions. It will also fail if expressions are nested on more than N levels but N can be increased as needed. N=2 should however be sufficient for day to day work. More complex algorithms should only be implemented if they are required to solve a practical problem.

  useBackgrounds: bool

    If True, the device implements controls to define and subtract background signals.

  version: str = 1.0

    The version of the plugin. Plugins are independent programs that require independent versioning and documentation.

class esibd.plugins.DeviceManager(*args: Any, **kwargs: Any)

  Top-level manager that controls data acquisition from all instruments. While the instruments run independently in separate threads, this class provides control over all devices. It provides access to individual channels by name, or to all input or outout channels, independent of their devices. This enables for example use of channels of arbitrary devices in channel equations and scan modes.

  class SignalCommunicate(*args: Any, **kwargs: Any)

    Object that bundles pyqtSignals.

    storeSignal

      Signal that triggers storage of device data.

  getChannelByName(name, inout=INOUT.BOTH)

    Get channel based on unique name and type.

    Parameters:

      - name (str) – Unique channel name.

      - inout (`INOUT`, optional) – Type of channel, defaults to `BOTH`

    Returns:

      The requested channel.

    Return type:

      `Channel`

  name: str = 'DeviceManager'

    A unique name that will be used in the graphic user interface. Plugins can be accessed directly from the Console using their name.

  optional: bool = False

    Defines if the user can deactivate the plugin in the `PluginManager` user interface.

  pluginType: PluginManager.TYPE = 'DeviceManager'

    The type defines the location of the plugin in the user interface and allows to run operations on a group of plugins with the same type.

  previewFileTypes: [str] = ['_combi.dat.h5']

    File extensions that are supported by this plugin. If a corresponding file is selected in the `Explorer()`, the plugins `loadData()` function will be called.

  store()

    Regularly stores device data to minimize loss in the event of a program crash. Safer to run in main thread, in case GUI elements are accessed.

  toggleRecording()

    Toggle recording of data.

  version: str = '1.0'

    The version of the plugin. Plugins are independent programs that require independent versioning and documentation.

class esibd.plugins.LiveDisplay(*args: Any, **kwargs: Any)

  Displays `Device` data in real time.

  copyClipboard()

    Extends matplotlib based version to add support for pyqtgraph.

  plot(apply=False)

    Plots the enabled and initialized channels in the main output plot The x axis is either time or a selected channel

  pluginType: PluginManager.TYPE = 'LiveDisplay'

    The type defines the location of the plugin in the user interface and allows to run operations on a group of plugins with the same type.

class esibd.plugins.Plugin(*args: Any, **kwargs: Any)

  Abstracts basic GUI code for devices scans and other high level UI elements. All plugins are ultimately derived from the `Plugin` class. The doc string of the plugin class will be shown in the corresponding help window.

  about()

    Displays the about dialog of the plugin using Browser or Text.

  addAction(func=None, toolTip='', icon=None, before=None)

    Adds a simple Action to the toolBar.

    Parameters:

      - func (method, optional) – The function triggered by the action, defaults to None

      - toolTip (str, optional) – The toolTip of the action, defaults to ‘’

      - icon (`BetterIcon`, optional) – The icon of the action, defaults to None

      - before (`Action`, optional) – The existing action before which the new action will be placed, defaults to None. If None, the new action will be added to the end.

    Returns:

      The new Action

    Return type:

      `Action`

  addContentLayout(lay)

    Use this to add a content layout instead of a content widget to the user interface.

    Parameters:

      lay (QLayout) – Content layout

  addContentWidget(cw)

    Use this to add your main content widget to the user interface.

    Parameters:

      cw (QWidget) – Content widget

  addRightAxis(ax)

    Adds additional y labels on the right.

  addStateAction(func=None, toolTipFalse='', iconFalse=None, toolTipTrue='', iconTrue=None, before=None, attr=None, restore=True)

    Adds an action with can be toggled between two states, each having a dedicated tooltip and icon.

    Parameters:

      - func (method, optional) – The function triggered by the stateAction, defaults to None

      - toolTipFalse (str, optional) – The toolTip of the stateAction if state is False, defaults to ‘’

      - iconFalse (`BetterIcon`, optional) – The icon of the stateAction if state is False, defaults to None

      - toolTipTrue (str, optional) – The toolTip of the stateAction if state is True, defaults to ‘’

      - iconTrue (`BetterIcon`, optional) – The icon of the stateAction if state is True, defaults to None

      - before (`Action`, optional) – An existing action or stateAction before which the new action will be placed, defaults to None. If None, the new stateAction will be added to the end.

      - attr (str, optional) – Enables direct access to the state of the stateAction using self.attr, defaults to None

      - restore (bool, optional) – If True state will be restored when the program is restarted, defaults to True

    Returns:

      The new StateAction

    Return type:

      `StateAction`

  axes: [matplotlib.axes.Axes]

    The axes of `fig`.

  canvas: matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg

    The canvas the figure renders into.

  close()

    Closes plugin cleanly without leaving any data or communication running. Extend to make sure your custom data and custom communication is closed as well.

  closeGUI()

    Closes the user interface but might keep data available in case the user interface is restored later. Closes all open references. Extend to save data and make hardware save if needed.

  closeUserGUI()

    Called when the user closes a single plugin. Extend to react to user triggered closing.

  copyClipboard()

    Copy matplotlib figure to clipboard.

  dependencyPath: Path = WindowsPath('.')

    Path to the plugin file defining the plugin. Can be used to locate corresponding dependencies like external scripts or media which are stored next to the plugin file or in subfolders relative to its location.

  dock: BetterDockWidget

    The dockWidget that allows to float and rearrange the plugin user interface.

  fig: matplotlib.pyplot.figure

    A figure, initialized e.g. using plt.figure(constrained_layout=True, dpi=self.getDPI()) and followed by self.makeFigureCanvasWithToolbar(self.fig).

  finalizeInit(aboutFunc=None)

    Executed after all other Plugins are initialized. Use this for code that modifies other `Plugins`, e.g. adding an `Action` to the `DeviceManager`.

    Parameters:

      aboutFunc (method, optional) – Function displaying the about dialog of the plugin, defaults to None. `about()` is used if no other is provided.

  getDPI()

    Gets the DPI from Settings.

    Returns:

      DPI

    Return type:

      int

  getDefaultSettings()

    Defines a dictionary of `parameterDict()` which specifies default settings for this plugin. Overwrite or extend as needed to define specific settings that will be added to Settings.

    Returns:

      Settings dictionary

    Return type:

      {`parameterDict()`}

  getIcon()

    Gets the plugin icon. Overwrite to introduce custom icons. Consider using a themed icon that works in dark and light modes.

    Returns:

      Icon

    Return type:

      `BetterIcon`

  getTestMode()

    Gets the test mode from Settings.

    Returns:

      Test mode

    Return type:

      bool

  initDock()

    Initializes the dockWidget.

  initFig()

    Will be called when a display is closed and reopened or the theme is changed. Overwrite your figure initialization here to make sure all references are updated correctly.

  initGUI()

    Initializes the graphic user interface (GUI), independent of all other plugins.

  initializedDock: bool

    A flag signaling if the plugin `dock` has been initialized. You may want to ignore certain events before initialization is complete.

  initializedGUI: bool

    A flag signaling if the plugin graphical user interface has been initialized. You may want to ignore certain events before initialization is complete.

  labelPlot(ax, label)

    Adds file name labels to plot to trace back which file it is based on.

  loadData(file, _show=True)

    Loads and displays data from file. This should only be called for files where `supportsFile()` returns True. Overwrite depending on data supported by the plugin.

    Parameters:

      - file (pathlib.Path) – File from which to load data.

      - _show (bool, optional) – Show plugin after loading data, defaults to True. Some files are handled by multiple plugins and only one of them should be shown by default.

  property loading

    A flag that can be used to suppress certain events while loading data or initializing the user interface. Make sure the flag is reset after every use. Internal logic allows nested use.

  makeCoreIcon(file)

    Returns an icon based on a filename. Looks for files in the internal media folder.

    Parameters:

      file (str) – Icon file name.

    Returns:

      Icon

    Return type:

      `BetterIcon`

  makeFigureCanvasWithToolbar(figure)

    Creates `canvas()`, which can be added to the user interface, and adds the corresponding `navToolBar()` to the plugin `titleBar()`.

    Parameters:

      figure (matplotlib.pyplot.figure) – A matplotlib figure.

  makeIcon(file)

    Returns an icon based on a filename. Looks for files in the `dependencyPath()`.

    Parameters:

      file (str) – Icon file name.

    Returns:

      Icon

    Return type:

      `BetterIcon`

  name: str = ''

    A unique name that will be used in the graphic user interface. Plugins can be accessed directly from the Console using their name.

  navToolBar: ThemedNavigationToolbar

    Provides controls to interact with the figure.

  optional: bool = True

    Defines if the user can deactivate the plugin in the `PluginManager` user interface.

  plot()

    If applicable, overwrite with a plugin specific plot method.

  pluginManager: PluginManager

    A reference to the central `PluginManager`.

  pluginType: TYPE = 'Internal'

    The type defines the location of the plugin in the user interface and allows to run operations on a group of plugins with the same type.

  previewFileTypes: [<class 'str'>] = []

    File extensions that are supported by this plugin. If a corresponding file is selected in the `Explorer()`, the plugins `loadData()` function will be called.

  print(message, flag=PRINT.MESSAGE)

    The print function will send a message to stdout, the statusbar, the Console, and if enabled to the logfile. It will automatically add a timestamp and the name of the sending plugin.

    Parameters:

      - message (str) – A short informative message.

      - flag (`PRINT()`, optional) – Flag used to adjust message display, defaults to `MESSAGE`

  provideDock()

    Adding existing `dock` to UI.

  raiseDock(_show=True)

    Raises `dock` if _show is True.

  requireGroup(g, name)

    Replaces require_group from h5py, and adds support for track_order.

  requiredPlugin(name)

    Throws exeption if required plugin is not available.

  runTestParallel()

    Runs a series of tests by changing values of selected controls and triggering the corresponding events. Extend to add more plugin specific tests.

    Returns:

      Returns True if the plugin is initialized and further tests can be executed.

    Return type:

      bool

  setLabelMargin(ax, margin)

    Sets top margin only, to reserve space for file name label.

  supportedVersion: [<class 'str'>] = '0.6'

    By default the current program version is used. You can define a fixed version and future program versions will state that they are incompatible with this plugin. This can be used to prompt developers to update and test their plugins before distributing them for a more recent program version.

  supportsFile(file)

    Tests if a file is supported by the plugin.

    Parameters:

      file (pathlib.Path) – File that has been selected by the user.

    Returns:

      Returns True if the file is supported by the plugin. Test if supported based on file extension or content.

    Return type:

      bool

  test()

    Runs `runTestParallel()` in parallel thread.

  testControl(control, value, delay=0)

    Changes control states and triggers corresponding events.

  titleBar: PyQt6.QtWidgets.QToolBar

    Actions can be added to the titleBar using `addAction()` or `addStateAction()`.

  titleBarLabel: PyQt6.QtWidgets.QLabel

    The label used in the titleBar.

  toggleTitleBar()

    Adjusts the title bar layout and `titleBarLabel` depending on the state of the `dock` (tabbed, floating, …). Extend to make sure toggleTitleBar is called for dependent plugins.

  updateTheme()

    Changes between dark and light themes. Most controls should update automatically as the color pallet is changed. Only update the remaining controls using style sheets. Extend to adjust colors to app theme.

  version: str = ''

    The version of the plugin. Plugins are independent programs that require independent versioning and documentation.

class esibd.plugins.Scan(*args: Any, **kwargs: Any)

  Base class for `scans` and other measurement plugins. Acquires arbitrary output channel values vs. arbitrary input channel values. The dimension of inputs and outputs is dynamic.

  class SignalCommunicate(*args: Any, **kwargs: Any)

    Object that bundles pyqtSignals.

    saveScanCompleteSignal

      Signal that confirms that scan data has been saved and a new scan can be started.

    scanUpdateSignal

      Signal that triggers update of the figure and, if True is passed, saving of data.

      alias of `bool`

    updateRecordingSignal

      Signal that allows to stop recording from an external thread.

      alias of `bool`

  addInputChannel(channelName, _from, to, step)

    Converting channel to generic input data. Returns True if channel is valid for scanning.

  display: Plugin

    The internal plugin used to display scan data.

  estimateScanTime()

    Estimates scan time. Will likely need to be adapted for custom scans.

  file: Path

    The scan file. Either existing file or file to be created when scan finishes.

  property finished

    True before and after scanning. Even when `recording` is set to False it will take time for the scan to complete and be ready to be started again.

  generatePythonPlotCode()

    Saves minimal code to create a plot which can be customized by the user.

  getChannelByName: callable

    Reference to `getChannelByName()`.

  getData(i, inout)

    Gets the data of a scan channel based on index and type.

    Parameters:

      - i (int) – Index of channel.

      - inout (`INOUT`) – Type of channel.

    Returns:

      The requested data.

    Return type:

      numpy.array

  getOutputIndex()

    Gets the index of the output channel corresponding to the currently selected display channel. See `useDisplayChannel`.

  getSteps(_from, to, step)

    Returns steps based on _from, to, and step parameters.

  initScan()

    Initializes all data and metadata. Returns True if initialization successful and scan is ready to start. Will likely need to be adapted for custom scans.

  inputs: [<class 'esibd.core.MetaChannel'>]

    List of input `meta channels`.

  loadDataInternal()

    Loads data from scan file. Data is stored in scan-neutral format of input and output channels. Extend to provide support for previous file formats.

  measurementsPerStep: int

    Number of measurements per step based on the average time and acquisition rate.

  outputs: [<class 'esibd.core.MetaChannel'>]

    List of output `meta channels`.

  plot(update=False, **kwargs)

    Plot showing a current or final state of the scan. Extend to add scan specific plot code.

    Parameters:

      update (bool, optional) – If update is True, only data will be updates, otherwise entire figure will be initialized, defaults to False

  pythonPlotCode()

    Defines minimal code to create a plot which can be customized by user. Accessible from context menu of scan files. Overwrite to add scan specific plot code here.

  property recording

    True if currently recording. Set to False to stop acquisition and save available data.

  run(recording)

    Steps through input values, records output values, and triggers plot update. Executed in runThread. Will likely need to be adapted for custom scans.

  runThread: Thread

    Parallel thread that updates the scan channel(s) and reads out the display channel(s).

  saveData(file)

    Writes generic scan data to hdf file.

  saveScanParallel(file)

    Keeps GUI interactive by saving scan data in external thread.

  toggleRecording()

    Handles start and stop of scan.

  useDisplayChannel: bool

    If True, a combobox will be created to allow to select for which channel data should be displayed.

class esibd.plugins.SettingsManager(*args: Any, **kwargs: Any)

  Bundles multiple `settings` into a single object to handle shared functionality.

  initSettingsContextMenuBase(setting, pos)

    General implementation of a context menu. The relevent actions will be chosen based on the type and properties of the setting.

  loadSettings(file=None, default=False)

    Loads settings from hdf or ini file.

  pluginType: PluginManager.TYPE = 'Internal'

    The type defines the location of the plugin in the user interface and allows to run operations on a group of plugins with the same type.

  saveSettings(file=None, default=False)

    Saves settings to hdf or ini file.

  updateSettings(items, file)

    Scans for changes and shows change log before overwriting old channel configuraion.

  version: str = '1.0'

    The version of the plugin. Plugins are independent programs that require independent versioning and documentation.

class esibd.plugins.StaticDisplay(*args: Any, **kwargs: Any)

  Displays `Device` data from file.

  copyClipboard()

    Extends matplotlib based version to add support for pyqtgraph.

  loadDataInternal(file)

    Load data in standard format. Overwrite in derived classes for legacy versions.

  plot()

    Plots channels from file, using real channel information (color, linewidth, …) if available.

  pluginType: PluginManager.TYPE = 'Display'

    The type defines the location of the plugin in the user interface and allows to run operations on a group of plugins with the same type.

esibd.plugins.providePlugins()

  Returns list of `plugins` that are available for activation in the `PluginManager` user interface accessible from Settings.

  Returns:

    Plugin list

  Return type:

    [`Plugin`]

## 5.2. The core module

This module contains internally used constants, functions and classes Generally all objects that are used accross multiple modules should be defined here to avoid circular imports and keep things consistent. Whenever it is possible to make definitions only locally where they are needed, this is preferred. Keep this file as compact as possible. This helps to keep things consistent and avoid errors to typos in strings etc. In principle, different versions of this file could be used for localization For now, English is the only supported language and use of hard coded error messages etc. in other files is tolerated if they are unique.

class esibd.core.Action(*args: Any, **kwargs: Any)
  class SignalCommunicate(*args: Any, **kwargs: Any)
    setValueFromThreadSignal

      alias of `bool`

class esibd.core.BetterDockWidget(*args: Any, **kwargs: Any)

  Allows to intercept the closeEvent and update title when floating or tabbing.

  class SignalCommunicate(*args: Any, **kwargs: Any)
  toggleTitleBar()

    Updates titlebar as dock is changing from floating to docked states.

class esibd.core.BetterIcon(*args: Any, **kwargs: Any)

  QIcon that allows to save the icon file name. Allows to reuse icon elsewhere, e.g., for html about dialog.

class esibd.core.BetterPlotWidget(*args: Any, **kwargs: Any)

  PlotWidget providing xyLabel.

class esibd.core.Channel(*args: Any, **kwargs: Any)

  A `Channel` represents a virtual or real parameter and manages all data and metadata related to that parameter. Each `Device` can only have one type of `Channel`, but channels have dynamic interfaces that allow to account for differences in the physical backend.

  class SignalCommunicate(*args: Any, **kwargs: Any)
    updateValueSignal

      alias of `float`

  asDict()

    Returns a dictionary containing all channel parameters and their values.

  backgrounds: DynamicNp

    List of backgrounds. Only defined if corresponding device uses backgrounds.

  device: any

    The `Device` containing this channel.

  displayedParameters: [<class 'str'>]

    List of parameters that determines which parameters are shown in the user interface and in what order. Compare `insertDisplayedParameter()`. If your custom parameter is not in this list it will not be visible in the user interface.

  enabledChanged()

    Extend as needed. Already linked to enabled checkbox.

  getDefaultChannel()

    Defines parameter(s) of the default channel. This is also use to assign widgetTypes and if settings are visible outside of advanced mode. See `parameterDict()`. If parameters do not exist in the settings file, the default parameter will be added. Overwrite in dependent classes as needed.

  getSortedDefaultChannel()

    Returns default channel sorted in the order defined by `displayedParameters`.

  getValues(length=None, _min=None, _max=None, n=1, subtractBackground=None)

    Returns plain Numpy array of values. Note that background subtraction only affects what is displayed, the raw signal and background curves are always retained.

  initGUI(item)

    call after itemWidget has been added to treeWidget itemWidget needs parent for all graphics operations

  inout: INOUT

    Reference to `inout()`.

  insertDisplayedParameter(parameter, before)

    Inserts your custom parameter before an existing parameter in `displayedParameters`.

    Parameters:

      - parameter (`Parameter`) – The new parameter to insert.

      - before (`Parameter`) – The existing parameter before which the new one will be placed.

  lastAppliedValue: any

    Reference to last value. Allows to decide if hardware update is required.

  parameters: Parameter

    List of channel parameters.

  plotCurve: pyqtgraph.PlotCurveItem

    The plotCurve in the corresponding `LiveDisplay`.

  print: callable

    Reference to `print()`.

  setDisplayedParameters()

    Used to determine which parameters to use and in what order. Extend using insertParameter to add more parameters

  tempParameters()

    List of parameters, such as live signal or status, that will not be saved and restored.

  tree: PyQt6.QtWidgets.QTreeWidget

    TreeWidget containing the channel widgets.

  updateColor()

    Apply new color to all controls.

  values: DynamicNp

    The history of values shown in the `LiveDisplay`. Use `getValues()` to get a plain numpy.array.

class esibd.core.CheckBox(*args: Any, **kwargs: Any)
  class SignalCommunicate(*args: Any, **kwargs: Any)
    setValueFromThreadSignal

      alias of `bool`

class esibd.core.CloseDialog(*args: Any, **kwargs: Any)

  Dialog to confirm closing the program.

class esibd.core.Colors

  Provides dark mode dependant defaul colors

class esibd.core.CompactComboBox(*args: Any, **kwargs: Any)

  Combobox that stays small while showing full content in dropdown

class esibd.core.ControlCursor(*args: Any, **kwargs: Any)

  Extending implementation given here https://matplotlib.org/3.5.0/gallery/misc/cursor_demo.html cursor only moves when dragged

  setPosition(x, y)

    emulated mouse event to set position

class esibd.core.DeviceController(*args: Any, **kwargs: Any)

  Each `Device` or `Channel` comes with a `DeviceController`. The `DeviceController` is not itself a `Plugin`. It only abstracts the direct hardware communication from `plugins` allowing them to use minimal and consistent code that can be adjusted and reused independently of the hardware. It should do all resource or time intensive communication work in parallel threads to not slow down the main software. Following the producer consumer logic, the `DeviceController` reads values and assigns them to the corresponding `Channel`. The `devices` will collect data from the `Channel` independently. In case you work with time sensitive experiments this concept will need to be adapted. Feel free to use the basic functionality provided by `DeviceController` or implement your own from scratch. As the `DeviceController` only interacts with your custom `Channel` or `Device`, there are no general requirements for its implementation.

  class SignalCommunicate(*args: Any, **kwargs: Any)

    Object that bundles pyqtSignals for the `DeviceController`. Extend to add additional events.

    initCompleteSignal

      Signal that is emitted after successful initialization of device communication.

    stopSignal

      Signal that triggers the acquisition to stop after communication errors.

    updateValueSignal

      Signal that transfers new data from the `acquisitionThread` to the corresponding channels.

  acquiring: bool = False

    True, while acquisitionThread is running. AcquisitionThread terminates if set to False.

  acquisitionThread: Thread = None

    A parallel thread that regularly reads values from the device.

  close()

    Terminates acquisition and closes all open ports. Extend to add hardware specific code.

  init()

    Starts the `initThread()`.

  initComplete()

    Called after successful initialization to start acquisition.

  initThread: Thread = None

    A parallel thread used to initialize communication.

  initialized: bool = False

    Indicates if communications has been initialized successfully and not yet terminated.

  initializing: bool = False

    Indicates if communications is beeing initialized.

  lock: allocate_lock

    Lock used to avoid race conditions when communicating with the hardware.

  parent: any

    Reference to the associated class.

  port: serial.Serial = None

    Port for serial communication.

  print: callable

    Reference to `print()`.

  runAcquisition(acquiring)

    Runs acquisitoin loop. Executed in acquisitionThread. Overwrite with hardware specific acquisition code.

  runInitialization()

    Hardware specific initialization of communication. Executed in initThread.

  serialRead(port, encoding='utf-8')

    Reads a string from a serial port. Takes care of decoding messages from bytes and catches common exceptions.

    Parameters:

      - port (serial.Serial) – Serial port.

      - encoding (str, optional) – Encoding used for sending and receiving messages, defaults to ‘utf-8’

    Returns:

      message

    Return type:

      str

  serialWrite(port, message, encoding='utf-8')

    Writes a string to a serial port. Takes care of decoding messages to bytes and catches common exceptions.

    Parameters:

      - port (serial.Serial) – Serial port.

      - message (str) – Message.

      - encoding (str, optional) – Encoding used for sending and receiving messages, defaults to ‘utf-8’

  startAcquisition()

    Starts data acquisition from physical device.

  stop()

    Overwrite to stop recording and acquisition in case a communication error occured. This should free up all resources and allow for clean reinitialization.

  stopAcquisition()

    Terminates acquisition but leaves communication initialized by default.

  updateValue()

    Called from acquisitionThread to update the value of the channel(s) in the main thread. Overwrite with specific update code.

class esibd.core.DynamicNp(initialData=None, max_size=None, dtype=<class 'numpy.float32'>)

  A numpy.array that dynamically increases its size in increments to prevent frequent memory allocation while growing.

  add(x, lenT=None)

    Adds the new data point and adjusts the data array as required.

  get(length=None, _min=None, _max=None, n=1)

    Returns actual values.

    Parameters:

      - length (int) – will return last ‘length’ values.

      - _min (int) – Index of lower limit.

      - _max (int) – Index of upper limit.

      - n (int, optional) – Will only return every nth value, defaults to 1

    Returns:

      Values in specified range.

    Return type:

      numpy.array

class esibd.core.EsibdExplorer(*args: Any, **kwargs: Any)

  ESIBD Explorer: A comprehensive data acquisition and analysis tool for Electrospray Ion-Beam Deposition experiments and beyond.

  Contains minimal code to start, initialize, and close the program. All high level logic is provided by `core`, `plugins` and additional `plugins`.

  closeEvent(event)

    Triggers `PluginManager` to close all plugins and all related communication.

  loadPlugins()

    Loads `plugins` in main thread.

  restoreUiState()

    Restores size and location of main window.

  saveUiState()

    Saves size and location of main window.

  toggleFullscreen()

    Toggles full screen mode.

class esibd.core.INOUT(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Used to specify if a function affects only input, only output, or all channels.

  BOTH = 2

    Both input and output.

  IN = 0

    Input

  OUT = 1

    Output

class esibd.core.LedIndicator(*args: Any, **kwargs: Any)

  Simple custom LED indicator

  paintEvent(QPaintEvent)

    an event that paints

class esibd.core.Logger(*args: Any, **kwargs: Any)

  Redicrects stderr and stdout to logfile while still sending them to Console as well. Also shows messages on Status bar. Use `print()` of `Plugin` to send messages to the logger.

  close()

    Disables logging and restores stdout and stderr

  flush()

    Flushes content to log file

  open()

    Activates logging of Plugin.print statements, stdout, and stderr to the log file.

  openLog()

    Opens the log file in an external program.

  print(message, sender='ESIBD Explorer 0.6', flag=PRINT.MESSAGE)

    Augments messages and redirects to log file, console, statusbar, and console.

    Parameters:

      - message (str) – A short and descriptive message.

      - sender (str, optional) – The name of the sending plugin, defaults to f’{PROGRAM_NAME} {VERSION_MAYOR}.{VERSION_MINOR}’

      - flag (`PRINT()`, optional) – Signals the status of the message, defaults to PRINT.MESSAGE

  printFromThreadSignal

    alias of `str`

  write(message)

    Directs messages to terminal, log file, and Console. Called directly from stdout or stderr or indirectly via Plugin.print.

class esibd.core.MZCaculator(parentPlugin, ax=None)

  Add to a class derived from Scan. Allows to mark mz locations within a chargestate distrubution, calculates absolute mass, and displays it on the axis. Use Ctrl + Left Mouse to mark and Ctrl + Right Mouse to reset

  determine_mass_to_charge()

    estimates charge states based on m/z values provided by user by minimizing standard deviation of absolute mass within a charge state series. Provides standard deviation for neightbouring series to allow for validation of the result.

class esibd.core.MetaChannel(name, data, initial=None, background=None, unit='', channel=None)

  Manages metadata associated with a channel by a `Scan` or `LiveDisplay`. Allows to restore data even if corresponding channels do not exist anymore.

  namestr

    The scan channel name is usualy the same as the name of the corresponding `Channel`.

  datanumpy.array

    Scan data is saved and restored automatically. Each scan is free to define its data with arbitrary dimensions.

  initialvar

    Initial value. Used to restore all conditions after scan has completed.

  backgroundnumpy.array

    If used, has to be of same dimension as data.

  unitstr

    The channel unit.

  channel: `PluginManager`

    The actual channel, if it exists.

class esibd.core.NumberBar(*args: Any, **kwargs: Any)

  based on https://gist.github.com/Axel-Erfurt/8c84b5e70a1faf894879cd2ab99118c2

  paintEvent(event)

class esibd.core.PRINT(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Used to specify if a function affects only input, only output, or all channels.

  DEBUG = 3

    Only show if debug flag is enabled.

  ERROR = 2

    Tag message as error and highlight using color.

  MESSAGE = 0

    A standard message.

  WARNING = 1

    Tag message as warning and highlight using color.

class esibd.core.Parameter(name, _parent=None, default=None, widgetType=None, index=1, items=None, widget=None, internal=False, tree=None, itemWidget=None, toolTip=None, event=None, _min=None, _max=None, indicator=False, instantUpdate=True)

  Parameters are used by settings and channels. They take care of providing consistent user controls, linking events, input validation, context menus, and restoring values. Typically they are not initialized directly but via a `parameterDict()` from which settings and channels take the relevant information.

  namestr

    The parameter name.

  valuevar

    The default value of the parameter in any supported type.

  minfloat

    Minimum limit for numerical properties.

  maxfloat

    Maximum limit for numerical properties.

  toolTipstr

    Tooltip used to describe the parameter.

  items[str]

    List of options for parameters with a combobox.

  widgetType`TYPE()`

    They type determines which widget is used to represent the parameter in the user interface.

  advancedbool

    If True, parameter will only be visible in advanced mode. Only applies to channel parameters.

  headerstr

    Header used for the corresponding column in list of channels. The parameter name is used if not specified. Only applies to channel parameters.

  widgetQWidget

    A custom widget that will be used instead of the automatically provided one.

  eventmethod

    A function that will be triggered when the parameter value changes.

  internalbool

    Set to True to save parameter value in the registry (using QSetting) instead of configuration files. This can help to reduce clutter in configuration files and restore essential parameters even if configuration files get moved or lost.

  attrstr
    Allows direct access to the parameter. Only applies to channel and settings parameters.

      E.g. The color parameter of a channel specifies attr=’color’ and can thus be accessed via channel.color.

      E.g. The Session path parameter in `Settings` specifies attr=’sessionPath’ and can thus be accessed via Settings.sessionPath.

      E.g. The interval parameter of a device specifies attr=’interval’ and can thus be accessed via device.interval.

      E.g. The notes parameter of a scan specifies attr=’notes’ and can thus be accessed via scan.notes.

  indicatorbool

    Indicators cannot be edited by the user.

  instantUpdatebool

    By default, events are triggered as soon as the value changes. If set to False, certain events will only be triggered if editing is finished by the enter key or if the widget loses focus.

  printmethod

    Reference to `print()`.

  class TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

    Specifies what type of widget should be used to represent the parameter in the user interface.

    BOOL = 'BOOL'

      A boolean flag, represented by a checkbox.

    COLOR = 'COLOR'

      A ColorButton that allows to select a color.

    COMBO = 'COMBO'

      A combobox providing text options.

    EXP = 'EXP'

      An spinbox with scientific format.

    FLOAT = 'FLOAT'

      An floating point spinbox.

    FLOATCOMBO = 'FLOATCOMBO'

      A combobox providing floating point options.

    INT = 'INT'

      An integer spinbox.

    INTCOMBO = 'INTCOMBO'

      A combobox providing integer options.

    LABEL = 'LABEL'

      A label that displays information.

    PATH = 'PATH'

      A path to a file or directory.

    TEXT = 'TEXT'

      An editable text field.

  applyWidget()

    create UI widget depending on widget type Linking dedicated widget if provided

  equals(value)

    Returns True if a representation of value matches the value of the parameter

  validateComboInput(value)

    Validates input for comboboxes

  property value

    returns value in correct format, based on widgetType

class esibd.core.PluginManager

  The `PluginManager` is responsible for loading all internal and external Plugins. It catches errors or incompatibilities while loading, initializing, and closing plugins. Users will only see the plugin selection interface accessed from the Settings plugin. The `PluginManager` can be accessed from the Console as PluginManager. It allows plugins to interact by using unique plugin names as attributes, e.g. self.pluginManager.ISEG or self.pluginManager.DeviceManager.

  class SignalCommunicate(*args: Any, **kwargs: Any)
  class TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

    Each plugin must be of one of the following types to define its location and behavior.

    CONSOLE = 'Console'

      The internal Console.

    CONTROL = 'Generic Control'

      Any control plugin, will be placed next to Settings, Explorer, Devices, and Scans.

    DEVICEMGR = 'DeviceManager'

      Device manager, will be placed below live displays.

    DISPLAY = 'Display'

      Any display plugin, will be places next to scan displays and static displays.

    INPUTDEVICE = 'Input Device'

      Device plugin sending user input to hardware.

    INTERNAL = 'Internal'

      A plugin without user interface.

    LIVEDISPLAY = 'LiveDisplay'

      Live display associated with a device.

    OUTPUTDEVICE = 'Output Device'

      Device plugin sending hardware output to user.

    SCAN = 'Scan'

      Scan plugin, will be placed with other controls.

  addPluginTreeWidgetItem(tree, name, enabled, version_, pluginType, previewFileTypes, description, optional=True)

    Adds a row for given plugin. If not a core plugin it can be enabled or disabled using the checkbox.

  closePlugins(reload=False)

    close all open connections and leave hardware in save state (voltage off)

  finalizeInit()

    Finalize initalization after all other plugins have been initialized.

  getMainPlugins()

    Returns all plugins found in the control section, including devices, controls, and scans.

  getPluginsByType(pluginTypes)

    Returns all plugins of the specified type.

    Parameters:

      pluginTypes (`TYPE()`) – A single type or list of types.

    Returns:

      _description_

    Return type:

      _type_

  loadPlugin(Plugin, dependencyPath=None)

    Load a single plugin. Plugins must have a static name and pluginType. ‘mainWindow’ is passed to enable flexible integration, but should only be used at your own risk. Enabled state is saved and restored from an independent file and can also be edited using the plugins dialog.

  loadPlugins(reload=False)

    Loads all enabled plugins.

  loadPluginsFromModule(Module, dependencyPath)

    Loads plugins from a module.

  property loading

    Flag that can be used to suppress events while plugins are loading, initializing, or closing.

  managePlugins()

    A dialog to select which plugins should be enabled

  plugins = []

    A central plugin list that allows plugins to interact with each other.

  provideDocks()

    creates docks and positions them as defined by plugintype

  runTestParallel()

    Runs test of all plugins from parallel thread.

  test()

    Calls `runTestParallel()` to test most features of for all plugins.

  updateTheme()

    Updates application theme while showing a splash screen if necessary.

class esibd.core.QLabviewDoubleSpinBox(*args: Any, **kwargs: Any)

  Implements handling of arrow key events based on curser position as in LabView

  stepBy(step)

    Handles stepping value depending con caret position. This implementation works with negative numbers and of number of digets before the dot.

class esibd.core.QLabviewSciSpinBox(*args: Any, **kwargs: Any)

  Spinbox for scientific notation

  class FloatValidator(*args: Any, **kwargs: Any)

    Validates input for correct scientific notation.

  stepBy(step)

    Handles stepping value depending con caret position. This implementation works with negative numbers and of number of digets before the dot.

class esibd.core.QLabviewSpinBox(*args: Any, **kwargs: Any)

  Implements handling of arrow key events based on curser position as in LabView

  stepBy(step)

    Handles stepping value depending con caret position.

class esibd.core.RestoreFloatComboBox(*args: Any, **kwargs: Any)

class esibd.core.SciAxisItem(*args: Any, **kwargs: Any)

  Based on original logTickStrings from https://pyqtgraph.readthedocs.io/en/latest/_modules/pyqtgraph/graphicsItems/AxisItem.html Only difference to source code is 0.1g -> .0e and consistend use of 1 = 10⁰

class esibd.core.Setting(*args: Any, **kwargs: Any)

  Parameter to be used as general settings with dedicated UI controls instead of being embedded in a device channel.

  resetWidget()

    Returns widget back to the Settigs tree.

  setWidget(widget)

    Allows to change to custom widget after initialization. E.g. to move a setting to a more logical position outside the Settings tree.

  settingEvent()

    Executes internal validation based on setting type. Saves parameters to file or qSet to make sure they can be restored even after a crash. Finally executes setting specific event if applicable.

class esibd.core.SplashScreen(*args: Any, **kwargs: Any)

  Program splash screen indicates start process before main window is ready.

class esibd.core.StateAction(*args: Any, **kwargs: Any)

  Extends QActions to show different icons depending on a state. Values are restored using QSettings if name is provided.

class esibd.core.TextEdit(*args: Any, **kwargs: Any)

  from https://gist.github.com/Axel-Erfurt/8c84b5e70a1faf894879cd2ab99118c2

  keyPressEvent(e)

class esibd.core.ThemedConsole(*args: Any, **kwargs: Any)

  pyqtgraph.console.ConsoleWidget with colors adjusting to theme

  setStack(frame=None, tb=None)

    Display a call stack and exception traceback.

    This allows the user to probe the contents of any frame in the given stack.

    frame may either be a Frame instance or None, in which case the current frame is retrieved from `sys._getframe()`.

    If tb is provided then the frames in the traceback will be appended to the end of the stack list. If tb is None, then sys.exc_info() will be checked instead.

  write(strn, html=False, scrollToBottom='auto')

    Write a string into the console.

    If scrollToBottom is ‘auto’, then the console is automatically scrolled to fit the new text only if it was already at the bottom.

class esibd.core.ThemedNavigationToolbar(*args: Any, **kwargs: Any)

  Provides controls to interact with the figure. Adds light and dark theme support to NavigationToolbar2QT.

  updateNavToolbarTheme(dark)

    Changes color of icons in matplotlib navigation toolBar to match theme.

class esibd.core.ToolButton(*args: Any, **kwargs: Any)
  class SignalCommunicate(*args: Any, **kwargs: Any)
    setValueFromThreadSignal

      alias of `bool`

esibd.core.makeSettingWrapper(name, settingsMgr, docstring=None)

  Neutral setting wrapper for convenient access to the value of a setting. If you need to handle events on value change, link these directly to the events of the corresponding control.

esibd.core.makeStateWrapper(stateAction, docstring=None)

  State wrapper for convenient access to the value of a StateAction.

esibd.core.makeWrapper(name, docstring=None)

  Neutral property wrapper for convenient access to the value of a parameter inside a channel. If you need to handle events on value change, link these directly to the events of the corresponding control in the finalizeInit method.

esibd.core.parameterDict(name=None, value=None, default=None, _min=None, _max=None, toolTip=None, items=None, tree=None, widgetType=None, advanced=False, header=None, widget=None, event=None, internal=False, attr=None, indicator=False, instantUpdate=True)

  Provides default values for all properties of a parameter. See `Parameter` for definitions.