Welcome to OptiHPLCHandler’s documentation!

PyPI Version Zenodo DOI License PyPI Downloads Source code on GitHub

OptiHPLCHandler is a software development kit (SDK) for interacting with the Waters Empower Web API. It aims to make putting data into and getting data out of Empower easy, with the aim of automating running samples. It will not feature changing data already in Empower.

Installation

The easiest way to install OptiHPLCHandler is using pip:

pip install Opti-HPLC-Handler

The source code is currently hosted on GitHub at: https://github.com/novonordisk-research/OptiHPLCHandler

Basic Usage

The main class is EmpowerHandler. This class is used to connect to Empower and perform actions. The class is initialised with the an address, a project, and optionally a username. project is the name of the Empower project that you want to log in to. address is the address of the Empower Web API. The address should be in the format https://<address>:<port>/. username is the Empower username you want to use to log in. If no username is provided, the username will be inferred from the user running the script. For more information, see the __init__ method.

When an EmpowerHandler has been initialised, you should use it with a context manager to ensure that the connection is closed properly. The context manager will also log you in and out of Empower. If no password is given, EmpowerHandler will first try to use the password stored in the keyring. If no password is stored in the keyring, it will prompt the user for a password.

from OptiHPLCHandler import EmpowerHandler

handler = EmpowerHandler(address, project)

with handler:
   # Do stuff with empower

The EmpowerHandler class has a number of methods for interacting with Empower. You can get the available nodes, plate type names, a list of sample set methods, and a list of method set methods without any arguments.

With the names of plate types and methodset methods, you can post sample set methods.

Once you have a node name, you can get the systems on that node, and with the system name, you can get the status of the system, and start running samples if a sample set has been defined.

Detailed Usage

In general, properties that the user could be intercting with are exposed in EmpowerHandler. An example would be project, which the user could set to change which Empower project to log in to. Properties only exposed in EmpowerHandler.connection, like verify, require more consideration to set.

Class EmpowerHandler

EmpowerHandler class diagram

class OptiHPLCHandler.EmpowerHandler(address: str, project: str | None = None, service: str = None, username: str | None = None, allow_login_without_context_manager: bool = False, auto_login: bool = True, api_version: str | None = None, **kwargs)

Bases: object

Handler for Empower. It allows you to post experiments to Empower and run them. It also allows you to get the information necessary to create an experiment, that is, list of nodes, systems, plate types, and methods.

This handler is stateful, meaning that you can save methods to the HPLC and run them later, and make runs based on the methods that are already on the HPLC.

Variables:

  • project – Name of the project to connect to.

  • address – Address of the Empower server.

  • username – Username to use to connect to Empower.

  • synonym_dict – Dictionary with the synonyms for the fields in SampleSetLine. The keys are the synonyms, the values are the actual field names that the API accepts.

GetEmpowerProjects() → list[dict[str, str]]

Assuming that the user has logged in in one project for example project = Mobile, this method fetches all available projectName that the user has access to and returns them as a list.

GetFieldNames(field_type: str, refresh: bool = False) → list[dict]

Get the available field names and their data type for a given field type.

The result is cached per field type until the project is changed.

Parameters:

  • field_type – Type of field to get names for. Must be one of self.allowed_field_types (“AuditTrail”, “Peak”, “Result”, “SampleSet”, “SampleSetLine”, “SSQEntry”).

  • refresh – If True, get the field names from Empower even if they are cached, e.g. after adding a custom field. Default False.

GetInstrumentMethod(method_name: str, use_sample_manager_oven: bool = False) → EmpowerInstrumentMethod

Get a method set method.

Parameters:

  • method_name – Name of the method set method to get.

  • use_sample_manager_oven – If True, both sample manager oven and column manager oven will be used. If False, only column manager oven will be used.

GetMethodList(method_type: str = 'MethodSetMethod') → list[str]

Get the list of methods.

Parameters:

method_type – Type of methods to get. If it doesn’t end with “Method”, it will be added. Default: “MethodSetMethod”.

GetMethodSetMethod(method_name: str)

Get a method set method.

Parameters:

method_name – Name of the method set method to get.

GetNodeNames() → list[str]

Get the list of node names.

GetPeaks(result_ids: list[int], returned_fields: Sequence[str] | None = ('Area', 'PctArea', 'StartTime', 'EndTime', 'Height', 'Name', 'RetentionTime', 'AsymAt10', 'WidthAt50Pct', 'WidthAtBaseline')) → list[dict[str, Any]]

Get peak data for results, with one flat dict per peak.

Parameters:

  • result_ids – List of result IDs to get peak data for.

  • returned_fields – List of peak fields to return. Defaults to DEFAULT_PEAK_FIELDS (“Area”, “PctArea”, “StartTime”, “EndTime”, “Height”, “Name”, “RetentionTime”, “AsymAt10”, “WidthAt50Pct”, “WidthAtBaseline”). If None, all available peak fields are returned.

Returns:

One dict per peak, with a value per returned field and None for fields without a value.

GetPeaksRaw(result_ids: list[int], returned_fields: list[str]) → list[dict]

Get peak data for results, as returned by Empower.

Parameters:

  • result_ids – List of result IDs to get peak data for.

  • returned_fields – List of peak fields to return.

Returns:

One record per peak. Its “id” is the ID of the result the peak belongs to.

GetPlateTypeNames(filter_string: str | None = None) → list[str]

Get the list of names of available plate types

Parameters:

filter_string – String to filter the list of plate types on. Only plate types whose name contains this string will be returned.

GetResult(result_id: int) → dict[str, Any]

Get all available fields of a result.

Parameters:

result_id – ID of the result to get.

Returns:

A dict with the result “id” and every result field, with None for fields without a value.

GetResults(search_field: str, operator: str, condition: str, returned_fields: Sequence[str] | None = ('SampleName', 'ResultId', 'InjectionId', 'ChannelName', 'DateAcquired', 'DateProcessed', 'ProcessingMethod'), order_by: str = 'OrderNone', page_number: int = 1, page_size: int = 50) → list[dict[str, Any]]

Search result records, with one flat dict per result.

Takes the same parameters as GetResultsRaw, except returned_fields defaults to DEFAULT_RESULT_FIELDS (“SampleName”, “ResultId”, “InjectionId”, “ChannelName”, “DateAcquired”, “DateProcessed”, “ProcessingMethod”). If None, all available result fields are returned.

Returns:

One dict per result, with its “id” and a value per returned field, and None for fields without a value.

GetResultsRaw(search_field: str, operator: str, condition: str, returned_fields: Sequence[str], order_by: str = 'OrderNone', page_number: int = 1, page_size: int = 50) → list[dict]

Search result records, as returned by Empower.

Parameters:

  • search_field – Result field to search on, used the same way as the ViewFilter cells in the Project window, together with operator and condition.

  • operator – Logical operator to use with condition. Must be one of self.allowed_result_operators (“EQ”, “NEQ”, “LT”, “LTE”, “GT”, “GTE”).

  • condition – Condition to filter search_field on. Must evaluate to a number for numeric fields. Dates can be given as e.g. “15 April 2025” or “15/04/2025”. Use “*” to ignore the condition, so order_by alone determines the results.

  • returned_fields – List of result fields to return. search_field is added if not already in the list.

  • order_by – Sort order of the results. Must be one of self.allowed_order_by_options (“OrderNone”, “Ascending”, “Descending”). Default “OrderNone”.

  • page_number – Page of results to return, starting at 1. Default 1.

  • page_size – Number of results per page. Default 50.

GetSampleSet(sample_set_name: str) → list[dict[str, Any]]

Get all available fields of the sample sets with a given name.

Parameters:

sample_set_name – Name of the sample set to get.

Returns:

One dict per sample set with that name, as names are not unique in Empower. Each dict has the sample set “id” and every sample set field, with None for fields without a value.

GetSampleSetMethod(sample_set_method_name: str, component_key: str = 'Components') → tuple[list[dict[str, Any]], dict[str, str]]

Get a sample set method in the format used by PostExperiment.

Parameters:

  • sample_set_method_name – Name of the sample set method to get.

  • component_key – Key to put the components of each sample under.

Returns:

A tuple of the sample list and the plates dict, which can be passed to PostExperiment as sample_list and plates. Sample keys are the Empower field names, and fields without a value are left out.

GetSampleSetMethodList() → list[str]

Get the list of sample set methods in project.

GetSampleSetMethodRaw(method_name: str) → dict

Get a sample set method.

Parameters:

method_name – Name of the sample set method to get.

GetSampleSetMethods() → list[str]

Deprecated. Get the list of sample set methods in project.

GetSampleSets(search_field: str, operator: str, condition: str, returned_fields: Sequence[str] | None = ('SampleSetName', 'SampleSetId', 'SampleSetMethod', 'SampleSetStartDate', 'SampleSetFinishDate', 'SystemName', 'Node'), order_by: str = 'OrderNone') → list[dict[str, Any]]

Search sample sets, with one flat dict per sample set.

Takes the same parameters as GetSampleSetsRaw, except returned_fields defaults to DEFAULT_SAMPLE_SET_FIELDS (“SampleSetName”, “SampleSetId”, “SampleSetMethod”, “SampleSetStartDate”, “SampleSetFinishDate”, “SystemName”, “Node”). If None, all available sample set fields are returned.

Returns:

One dict per sample set, with its “id” and a value per returned field, and None for fields without a value.

GetSampleSetsRaw(search_field: str, operator: str, condition: str, returned_fields: Sequence[str], order_by: str = 'OrderNone') → list[dict]

Search sample sets, as returned by Empower.

Parameters:

  • search_field – Sample set field to search on, used the same way as the ViewFilter cells in the Project window, together with operator and condition.

  • operator – Logical operator to use with condition. Must be one of self.allowed_result_operators (“EQ”, “NEQ”, “LT”, “LTE”, “GT”, “GTE”).

  • condition – Condition to filter search_field on. Use “*” to ignore the condition and return all sample sets.

  • returned_fields – List of sample set fields to return. search_field is added if not already in the list, as the server requires it.

  • order_by – Sort order of the results. Must be one of self.allowed_order_by_options (“OrderNone”, “Ascending”, “Descending”). Default “OrderNone”.

GetStatus(node: str, system: str)
GetSystemNames(node: str) → list[str]

Get the list of names of chromatographic systems on a node.

Parameters:

node – Name of the node to get the systems from.

classmethod LogoutAllSessions(address: str, password: str, service: str | None = None, username: str | None = None)

Logout all sessions of the user.

Parameters:

  • project – Name of the project to connect to.

  • address – Address of the Empower server.

  • password – Password to use to connect to Empower.

  • service – Name of the service to use to connect to Empower. If not given, the first service in the list of services will be used.

  • username – Username to use to connect to Empower.

PostExperiment(sample_set_method_name: str, sample_list: Iterable[dict[str, Any]], plates: dict[str, str], audit_trail_message: str | None = None, component_key: str = 'Components')

Post the experiment to the HPLC.

Parameters:

  • sample_set_method_name – Name of the sample set method to create.

  • sample_list –

    List of samples to run. Each sample is a dictionary with the following keys:

    • Method: Name of the method to use for the sample.

    • SamplePos: Position of the sample in the autosampler, including plate

      and position on the plate.

    • SampleName: Name of the sample.

    • InjectionVolume: Volume of the sample to inject in micro liters.

    If the key “Components” is present, it should be a dict, with the keys being the names of the components, and the values being the concentration of the component in the sample.

    If you need to add a value to a custom field with the name “Components”, you can change the name of the key to use for filling in the Empower components with the component_key parameter.

    Any other keys will be added as fields to the sample, including custom fields. If the key Function does not exist, the Function is set to “Inject Sample” For all fields, the datatype will be autodetermined according the the type of the value.

  • plate_list – Dict of plates to use. The keys should be the position of the plate, the value should be the plate type.

  • audit_trail_message – Message to add to the audit trail of the sample set method.

PostInstrumentMethod(method: EmpowerInstrumentMethod) → None

Post a method set method to Empower.

Parameters:

method – The method set method to post.

PostMethodSetMethod(method: Mapping[str, Any]) → None

Post a method set method.

Parameters:

method – The method set method to post.

RunExperiment(sample_set_method: str, node: str, system: str, sample_set_name: str | None = None, run_mode: str = 'RunOnly') → None

Run the experiment on an instrument.

Parameters:

  • sample_set_method – Name of the sample set method to run.

  • node – Name of the node to run the experiment on.

  • system – Name of the chromatographic system to run the experiment on.

  • sample_set_name – Name of the sample set to run. If not given, the name of the sample set method will be used.

  • run_mode – The run mode. Must be one of “RunOnly”, “RunAndProcess”, or “RunAndReport”.

SetAllowedSamplesetLineFieldValues(field_name: str, allowed_values: list[str] | None = None, overwrite: bool = True) → list[str]

Set the list of allowed values for a field in SampleSetLine.

Parameters:

  • field_name – Name of the field to set the allowed values for. Can be either the actual field name or an excepted synonym, like the Empower display name.

  • allowed_values – List of values to set as enumerated values for the field. If None (default), the list of enumerated values will be retrieved from the API. To turn off validation for a field, set the values to an empty tuple.

  • overwrite – If True (default), the allowed values for the field will be overwritten, even if they are already set. If False, the values will only be set if they are not already set.

Returns:

List of allowed values for the field after the operation.

SetSynonymsAndEnumeratedFields() → None

Set the synonyms and enumerated fields for SampleSetLines for the handler.

The synonymes and enumerated fields are added to the ones that are already in the handler. Enumerated fileds are set to not be validated, as it takes a long time to get the values from the API. If you want to validate the values, you can set the values manually with SetAllowedSamplesetLineFieldValues by not giving the allowed_values parameter.

__init__(address: str, project: str | None = None, service: str = None, username: str | None = None, allow_login_without_context_manager: bool = False, auto_login: bool = True, api_version: str | None = None, **kwargs)

Create a handler for Empower.

Parameters:

  • address – Address of the Empower server.

  • project – Name of the project to connect to.

  • service – Name of the service to use to connect to Empower. If not given, the first service in the list of services will be used.

  • username – Username to use to connect to Empower. If not given, the name of the user running the script will be used.

  • allow_login_without_context_manager – If False (default), an error will be raised when logging in without a context manager. If True, logging in without a context manager will merely raise a warning. This is not recommended, as it can lead to forgetting logging out.

  • auto_login – If True (default), the handler will log in automatically when you start a context manager. If False, you will have to call login() manually. This will allow you to give the password manually.

  • api_version – Version of the Empower Web API to use. If not given (default), the version starts at “1.0” and is automatically upgraded to the newest version the server reports supporting once you log in. If given explicitly, that version is used as-is and never auto-upgraded.

login(username: str | None = None, password: str | None = None)

Log into Empower.

Parameters:

  • password – The password to use for logging in. If None, the password is retrieved from the keyring if available, otherwise it is asked for every time.

  • username – The username to use for logging in. If None, the username of the default user is used. When EmpowerHandler is initialized, the username of the user running the script is set to the default username. If login is called with a different username, the default username is changed to the given username.

logout() → None

Log out of Empower.

Empower instrument method

Instrument class diagram

class OptiHPLCHandler.EmpowerInstrumentMethod(method_definition: dict | list, use_sample_manager_oven: bool = False)

Bases: object

A class to handle Empower instrument methods.

Variables:

  • original_method – The original method definition.

  • current_method – The current method definition.

  • column_oven_list – A list of column ovens in the instrument method.

  • module_method_list – A list of module methods in the instrument method.

  • solvent_handler_method – The solvent manager module method.

  • column_temperature – The column temperature. If multiple column ovens are found, the temperature is only returned if all column ovens have the same temperature. Otherwise, a ValueError is raised. If no column ovens are found, a ValueError is raised. When setting the column temperature, all column ovens will be set to the same temperature, regardless of the original temperatures. If no column ovens are found, a ValueError is raised.

  • gradient_table – The gradient table. If no solvent manager is found, a ValueError is raised. When setting the gradient table, the gradient table of the solvent manager will be set to the provided gradient table. If no solvent manager is found, a ValueError is raised.

  • valve_position – The valve position. If no solvent manager is found, a ValueError is raised. When setting the valve position, the valve position of the solvent manager will be set to the provided valve position. If no solvent manager is found, a ValueError is raised.

__init__(method_definition: dict | list, use_sample_manager_oven: bool = False)

Initialize the EmpowerInstrumentMethod.

Parameters:

  • method_definition – A method definition from Empower. If the entire result is passed, the instrument method definition will be extracted.

  • use_sample_manager_oven – If True, both sample manager oven and column manager oven will be used. If False, only column manager oven will be used.

Empower module methods

class OptiHPLCHandler.empower_module_method.BSMMethod(method_definition: Mapping[str, str])

Class for module methods that control a binary solvent manager (BSM).

copy()

Return a copy of the EmpowerModuleMethod.

property gradient_table: list[dict[str, str]]

The gradient table for the method. It is a list of dicts, one for each row.

The dicts have the following keys:

  • Time: The time in minutes (or Initial).

  • Flow: The flow in mL/min.

  • CompositionX: The composition of solvent line X (A, B, C, D) in %.

  • Curve: The curve type (Initial, or 1-11, 6 is linear and default).

When setting, values can be strings or numbers. Floats will be rounded to 3 decimals, as Empower has problems with too many decimals. The exception is value(s) for ‘Curve’, which is assumed to be integers and will not be rounded.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

property valve_position: list[str]

The current valve position for each solvent line. When setting, the value can be a list of strings. Each string should should be of the form XY, where X is the solvent line (A, B, C, D) and Y is the position (0-6).

class OptiHPLCHandler.empower_module_method.ColumnManagerMethod(method_definition: Mapping[str, str])

Class for module methods that control a column manager.

property column_temperature: str

The column temperature. If a float is given, it will be rounded to 1 decimal.

copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

class OptiHPLCHandler.empower_module_method.EmpowerModuleMethod(method_definition: Mapping[str, str])

Generic module method class that can be used for any Empower module method. For specific modules, a subclass should be created that inherits from this class.

Specific parameters for the method can be set and retrieved using the [] operator, e.g method[“ColumnTemperature”] = “50.03”. This will replace the current value of ColumnTemperature with the new value in the underlying xml. The current value can be retrieved in the same way. This only works if there is exactly one instance of the key in the xml. If there are multiple instances, a ValueError will be raised. If the key is not present, a KeyError will be raised. If more than one key is present, use the xml key to retrieve the xml and make changes to it through the replace method. This will replace all instances of the original string with the new string in the xml.

If no xml key is present in the method definition, no changes can be made to the method, but the original method definition can still be retrieved.

Variables:

  • original_method – The original method definition.

  • current_method – The current method definition, including the changes that have been made.

copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

class OptiHPLCHandler.empower_module_method.QSMMethod(method_definition: Mapping[str, str])

Class for module methods that control a quaternary solvent manager (QSM).

copy()

Return a copy of the EmpowerModuleMethod.

property gradient_table: list[dict[str, str]]

The gradient table for the method. It is a list of dicts, one for each row.

The dicts have the following keys:

  • Time: The time in minutes (or Initial).

  • Flow: The flow in mL/min.

  • CompositionX: The composition of solvent line X (A, B, C, D) in %.

  • Curve: The curve type (Initial, or 1-11, 6 is linear and default).

When setting, values can be strings or numbers. Floats will be rounded to 3 decimals, as Empower has problems with too many decimals. The exception is value(s) for ‘Curve’, which is assumed to be integers and will not be rounded.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

property valve_position: list[str]

The current valve position for each solvent line. When setting, the value can be a list of strings. Each string should should be of the form XY, where X is the solvent line (A, B, C, D) and Y is the position (0-6).

class OptiHPLCHandler.empower_module_method.SampleManagerMethod(method_definition: Mapping[str, str])

Class for module methods that control a sample manager.

property column_temperature: str

The column temperature. If a float is given, it will be rounded to 1 decimal.

copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

property sample_temperature: str

The sample temperature.

undo() → None

Undo the last change made to the method.

class OptiHPLCHandler.empower_detector_module_method.Detector(method_definition: Mapping[str, str])
copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

class OptiHPLCHandler.empower_detector_module_method.FLRChannel(excitation: str, emission: str, channel_name: str = '', enable: bool = True, datamode: str = 'Emission_1F')
class OptiHPLCHandler.empower_detector_module_method.FLRMethod(method_definition: Mapping[str, str])
copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

exception OptiHPLCHandler.empower_detector_module_method.NoWavelengthError
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class OptiHPLCHandler.empower_detector_module_method.PDAChannel(wavelength1: str, wavelength2: str = '254', resolution: str = 'Resolution_48', datamode: str = 'DataModeAbsorbance_0', ratio2dminimumau: str = '0.01')
class OptiHPLCHandler.empower_detector_module_method.PDAMethod(method_definition: Mapping[str, str])
copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

class OptiHPLCHandler.empower_detector_module_method.PDASpectralChannel(start_wavelength: str, end_wavelength: str, resolution: str = 'Resolution_12')
class OptiHPLCHandler.empower_detector_module_method.TUVChannel(wavelength: str, datarate: str = 'SingleDataRate_20A', datamode: str = 'SingleMode_1A', filtertype: str = 'Filter_2', timeconstant: str = '0.1000', ratiominimum: str = '0.0001', autozerowavelength: str = 'Az_3', autozeroinjectstart: bool = True, autozeroeventorkey: bool = True)
class OptiHPLCHandler.empower_detector_module_method.TUVMethod(method_definition: Mapping[str, str])
copy()

Return a copy of the EmpowerModuleMethod.

replace(original: str, new: str) → None

Replace all instances of a string in the xml of the current method.

Parameters:

  • original – The string to replace.

  • new – The string to replace it with.

undo() → None

Undo the last change made to the method.

Indices and tables