Metadata-Version: 2.1
Name: ont-pyguppy-client-lib
Version: 5.0.7
Summary: Python bindings for the GuppyClient library.
Home-page: http://www.nanoporetech.com
Author: Oxford Nanopore Technologies, Limited
Author-email: unknown@unknown.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: numpy

ont-pyguppy-client-lib
======================

``ont-pyguppy-client-lib`` provides python bindings for connecting to
a Guppy basecall server. It allows you to interact with the server to
do anything you could normally do using the guppy basecall
client. This includes:

- Basecalling
- Barcoding / demultiplexing
- Alignment

For example::

  >>> from pyguppy_client_lib.pyclient import PyGuppyClient
  >>> caller = PyGuppyClient(
      "127.0.0.1:5555",
      "dna_r9.4.1_450bps_fast",
      alignment_index_file="/path/to/index.mmi",
      bed_file="/path/to/targets.bed"
  )
  >>> caller.connect()

Getting started
===============

``ont-pyguppy-client-lib`` is available on PyPI and may be installed via pip::

   pip install ont-pyguppy-client-lib

``ont-pyguppy-client-lib`` requires an instance of the Guppy basecall
server is running. Guppy may be obtained from the
`Oxford Nanopore Community
<https://community.nanoporetech.com/downloads>`_

The version of ``ont-pyguppy-client-lib`` should exactly match the
version of Guppy being used. You can find your Guppy version like
this::

  $ <location of guppy_basecall_server>/guppy_basecall_server --version

For example, this Guppy basecall server is version 4.2.2::

  $ ./ont-guppy/bin/guppy_basecall_server --version
  : Guppy Basecall Service Software, (C) Oxford Nanopore Technologies,  Limited. Version 4.2.2+effbaf8, client-server API version 3.2.0

Install a specific version of ``ont-pyguppy-client-lib`` like this::

  pip install ont-pyguppy-client-lib==<version>

Dependencies
------------

``ont-pyguppy-client-lib`` requires ``numpy`` in order to run. In
order to use included helper functions for reading data from fast5
files it is also necessary to manually install ``ont-fast5-api``::

  pip install ont-fast5-api

Documentation and help
----------------------

Information on the methods available may be viewed through Python's
help command:::

  >>> from pyguppy_client_lib import pyclient
  >>> help(pyclient)
  >>> from pyguppy_client_lib import client_lib
  >>> help(client_lib)

Interface / Examples
====================

``ont-pyguppy-client-lib`` comprises three Python modules:

#. **pyclient** A user-friendly wrapper around **guppy_client**. This
   is what you should use to interact with a Guppy basecall server.
#. **guppy_client** A compiled library which provides direct Python
   bindings to Guppy's C++ API.
#. **helper_functions** A set of functions for running a Guppy basecall
   server and loading reads from fast5 files.

Starting a basecall server
--------------------------

There must be a Guppy basecall server running in order to communicate
with it. On most Oxford Nanopore devices a basecall server is always
running on port 5555. On other devices, or if you want to run a
separate basecall server, you must start one yourself::

  from pyguppy_client_lib import helper_functions

  # A basecall server requires:
  #  * A location to put log files (on your PC)
  #  * An initial config file to load
  #  * A port to run on
  server_args = ["--log_path", "/home/myuser/guppy_server_logs",
                 "--config", "dna_r9.4.1_450bps_fast.cfg",
                 "--port", 5556]
  # The second argument is the directory where the
  # guppy_basecall_server executable is found. Update this as
  # appropriate.
  helper_functions.run_server(server_args, "/home/myuser/ont-guppy/bin")

See the `Guppy protocol
<https://community.nanoporetech.com/protocols/Guppy-protocol/v/gpb_2003_v1_revu_14dec2018/guppy-basecall-server>`_
for more information on server arguments.

Create a client and connect to a server
---------------------------------------

::

  from pyguppy_client_lib.pyclient import PyGuppyClient

  client = PyGuppyClient(
      "127.0.0.1:5555",
      "dna_r9.4.1_450bps_fast"
  )
  client.connect()

Basecall all the reads in a folder
----------------------------------

Note that the helper_functions module requires that ``ont-fast5-api``
is installed.::

   from pyguppy_client_lib import helper_functions

   # Using the client generated in the previous example
   results = helper_functions.basecall_with_pyguppy(
       caller,
       <input_folder>
   )

Glossary of Terms:
==================

**Guppy** - Oxford Nanopore Technologies' production basecaller, which
translates electrical signals measured from nanopores into DNA or RNA
bases.

**Fast5** - an implementation of the HDF5 file format, with specific data
schemas for Oxford Nanopore Technologies sequencing data.


