<!--
SPDX-FileCopyrightText: 2021 - 2023 Constantine Evans <qslib@mb.costi.net>

SPDX-License-Identifier: EUPL-1.2
-->

[![Documentation Status](https://readthedocs.org/projects/qslib/badge/?version=latest)](https://qslib.readthedocs.io/en/latest/?badge=latest)
![Codecov](https://img.shields.io/codecov/c/github/cgevans/qslib)
![GitHub Workflow
Status](https://img.shields.io/github/actions/workflow/status/cgevans/qslib/python-tests.yml?branch=main)
![PyPI](https://img.shields.io/pypi/v/qslib)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5512/badge)](https://bestpractices.coreinfrastructure.org/projects/5512)
[![DOI](https://zenodo.org/badge/393710481.svg)](https://zenodo.org/badge/latestdoi/393710481)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/qslib)](https://pypi.org/project/qslib/)


[Our DNA 28 poster is available here.](https://costi.eu/dna28/qslib-poster.pdf)

Documentation: [Stable](https://qslib.readthedocs.io/en/stable/), [Latest](https://qslib.readthedocs.io/en/latest/)


# qslib

QSLib is a package for interacting with Applied Biosystems' QuantStudio
qPCR machines, primarily intended for non-qPCR uses, such as DNA computing and
molecular programming systems. It allows the creation, processing, and
handling of experiments and experiment data, and interaction with
machines through their network connection and SCPI interface.

The package was originally written for 96-well-block QuantStudio 5 machines.
However, it has some support for other machines, particularly for reading
EDS files: it supports v1.3 and (partially) v2.0 specification EDS files,
and should be able to read at least some data from files generated by
Viia7, QuantStudio 3, QuantStudio 5, QuantStudio 6 Flex, and QuantStudio 6 Pro
machines, with 96-well and 384-well blocks.  If you have problems reading EDS files,
or have found that it works with other machines, please let me know.

Amongst other features that it has:

-   Direct fluorescence data ("filter data") as Pandas dataframes, with
    times and temperature readings.

-   Running-experiment data access, status information, and control.

-   Protocol creation and manipulation, allowing functions outside of
    AB's software. Protocols can be modified and updated mid-run.

-   Temperature data at one-second resolution during experiments.

-   Machine control functions: immediate pauses and resumes, drawer
    control, power, etc.

-   With qslib-monitor: live monitoring of machine state information,
    with Matrix notifications, InfluxDB storage, and Grafana dashboards.

## Installation and Setup

QSLib is pure Python, and can be installed via pip:

    pip3 install -U qslib

Or, for the current Github version:

    pip3 install -U --pre git+https://github.com/cgevans/qslib

It requires at least version 3.10 of Python. While it uses async code at
its core for communication, it can be used conveniently in Jupyter or
IPython.

To use the library for communication with machines, you'll need a
machine access password with Observer (for reading data and statuses)
and/or Controller (for running experiments and controlling the machine)
access.  You will also need access to the machine on port 7443 (machine
software versions 1.3.4 and higher), or port 7000 (earlier software versions).

In machine software versions 1.3.4 and higher, you can set a password using
the "OEM Connection Only" option in "Settings".  Earlier software versions
must have passwords set by other methods.  Regardless of version, I strongly
recommend against having the machines be accessible online: use a restricted VPN
connection or port forwarding. See the documentation for more information.

## Contributing and issue reporting

Issue reports and enhancement requests can be submitted via Github.

Potential contributions can be submitted via Github.  These should include pytest tests, preferably
both tests that can be run without outside resources, and, if applicable, tests that directly test
any communication with a QuantStudio SCPI server.  They will also need a Contributor Licence Agreement.

Private vulnerability reports can be sent to me by
email, PGP-encrypted, or via Matrix to [@cge:matrix.org](https://matrix.to/#/@cge:matrix.org).

## Disclaimer

This package was developed for my own use. It may break your machine or
void your warranty. Data may have errors or be incorrect. When used to
send raw commands at high access levels, the machine interface could
render your machine unusable or be used to send commands that would
physically/electrically damage the machine or potentially be hazardous
to you or others.

I am not any way connected with Applied Biosystems.  I have developed this
package using the machine's documentation system and standard file formats.
