Metadata-Version: 2.1
Name: Opti_HPLC_Handler
Version: 0.5.0
Summary: Simplified proxy API for interacting with the Waters Empower Web API.
Author-email: Søren Furbo <srfu@novonordisk.com>
License: BSD 3-Clause License
        
        Copyright (c) 2023, novonordisk-research
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Repository, https://github.com/novonordisk-research/OptiHPLCHandler.git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Provides-Extra: test
Provides-Extra: lint
Provides-Extra: release
License-File: LICENSE

# OptiHPLCHandler

Simplified proxy API for interacting with the Waters Empower Web API. It aims to make
putting data into and getting data out of Empower easy. It will not feature changing
data already in Empower, with the aim of automating running samples. 

## Using the package

The package can be installed into a Python environment with the command

```
pip install Opti-HPLC-Handler
```

You can then import packge and start an `EmpowerHandler`. You need to select the Empower
project to log in to. Note that the user logging in needs to have access to both that
project, and the project `Mobile`.

```
from OptiHPLCHandler import EmpowerHandler
handler=EmpowerHandler(project="project", address="https://API_url.com:3076")
```

your username will be auto-detected. Add the argument `username` to use another account.

EmpowerHandler will first try to find a password for Empower for the `username` in the
OS's system keyring, e.g. Windows Credential Locker. If it can't access a system
keyring, or the keyring does not contain the relevant key, you will be prompted you for
the password. The password will only be used to get a token from the Empower Web API.
When the token runs out, you will have to input your password again.

You can now get a list of the methodset methods in the project:

```
method_list = handler.GetMethodList()
```

You can also get the plate types that can be used in the project, the method
`handler.GetPlateTypeNames` is used. If you run it without arguments, it returns all
possible plate type names. You can also give it a `filter_string`. In that case, only
the plate types with names that contain the filter string are returned. You can then
define the plate setup of your HPLC:

```
plate_type_name_list = handler.GetPlateTypeNames(filter_string="48")
plates = {"1": plate_type_name_list[0], "2": plate_type_name_list[1]}
```

You can also have the plate list be empty, but you will then have to fill it out in
Empower before you can run the SampleSetMethod:

```
plates = {}
```

To create a new sampleset method, first create its sample list as a list of
dictionaries. Each dictionary must have the keys `SampleName`. The key `Method` is
intepreted as the Empower field `MethodSetOrReportMethod`, the key `SamplePos` as the
Empower field `Vial`, and the key `Injectionvolume` as the Empower field `InjVol`. Note
that if the dictionary contains both of one of these pairs, it is not predictable which
will be used. Additional keys are interpreted as Empower fields with the key value
as its name.

```
sample_list = [
    {
        "Method": method_list[0],
        "SamplePos": "1:A,1",
        "SampleName": "test_sample_name_1",
        "InjectionVolume": 1,
    },
    {
        "Method": method_list[1],
        "SamplePos": "2:A,1",
        "SampleName": "test_sample_name_2",
        "InjectionVolume": 2,
        "test_field_1": "test_value",
        "test_field_2" 2.3,
    },
]
```

At the moment, only Injection Sampleset lines are supported, but the injection volume
can be set to 0.

At the moment, `components` can only be an empty list.

You can then use the handler to create the sampleset:

```
handler.PostExperiment(
    sample_set_method_name="test_sampleset_method_name",
    sample_list=sample_list,
    plates=plates,
    audit_trail_message="test_audit_trail_message",
)
```

To run the a SampleSetmethod, you need to provide a node name and a chromatograpic
system name. If you don't know them, you can find them with `handler.GetNodeName()` and
`handler.GetSystemName(node = "node_name")`.

You can now run a sampleset method to create a sampleset:

```
handler.RunExperiment(
    sample_set_method="test_sampleset_method_name",
    sample_set_name="test_sample_set",
    node="node_name",
    hplc="test_hplc",
)
```

## Getting started with developing the package

You can get the repo by cloning it from github at the URL
`https://github.com/novonordisk-research/OptiHPLCHandler.git`.

If you can't clone the repo on a Windows machine, you might need to set the SSL backend.
Run the following command in a terminal:
`git config --global http.sslbackend schannel`

It is recommended to make and activate a virtual environment by running the following
commands

```
pip install venv
python -m venv .env
.\.env\Scripts\activate
```

You need to run the last command every time you restart the computer.

When the virtual environment is activated, install the package locally as an editable
installation:

```
pip install -e .[dev]
```

If this doesn't work, you might need to upgrade pip and/or setuptools:

```
.\.env\scripts\python.exe -m pip install --upgrade pip
.\.env\scripts\python.exe -m pip install --upgrade setuptools
```

You should then be able to install the package locally as an editable installation.

## Releasing

To release a new version, get all of the changes you want into the branch `main`.
Then manually run the
[release GitHub action](https://github.com/novonordisk-research/OptiHPLCHandler/actions/workflows/release.yml)
by clicking `Run workflow`. Select what type of release it is by typing in `--patch`, `--minor`, or `--major` in `The type of release to perform`, and then click `Run workflow`.

Fetch the new branch `release`. Run the commands

```
rm -r -fo dist
py -m build
py -m twine upload dist/*
```

you will be prompted for your pipy.org username and password.

In GitHub, a pull request will have been made. Merge the pull request.
