If you are anything like us (Matt), reading a README is the last thing you do when running code. PLEASE DON'T DO THAT FOR READFISH. This will effect changes to your sequencing and - if you use it incorrectly - cost you money. We have added a list of GOTCHAs at the end of this README. We have almost certainly missed some... so - if something goes wrong, let us know so we can add you to the GOTCHA hall of fame!

[!NOTE]
We also have more detailed documentation for your perusal at https://looselab.github.io/readfish

[!NOTE]
Now also see our cool FAQ.

[!WARNING] Breaking for any version of MinKNOW <= 6.0.0 As of readfish >=2024.3.0 we no longer support guppy.

readfish is a Python package that integrates with the Read Until API.

The Read Until API provides a mechanism for an application to connect to a MinKNOW server to obtain read data in real-time. The data can be analysed in the way most fit for purpose, and a return call can be made to the server to unblock the read in progress and so direct sequencing capacity towards reads of interest.

This implementation of readfish requires Dorado server version >= 7.3.9 and MinKNOW version core >= 6.0.0 . It will not work on earlier versions.

To run with earlier versions of MinKNOW please use an earlier version of readfish.

The code here has been tested with Dorado in GPU mode using GridION Mk1 and NVIDIA RTX4090s on live sequencing runs and on MacOSX M2Max using playback on a simulated run (see below for how to test this). This code is run at your own risk as it DOES affect sequencing output. You are strongly advised to test your setup prior to running (see below for example tests).

Supported Sequencing Platforms

The following platforms are supported:

PromethION Big Boy
P2Solo Smol Big Boy
P2i Not so Smol Big Boy
GridION Box
MinION Smol Boy

[!WARNING] PromethION support is currently only available using the Mappy-rs plugin only. See here for more information.

Supported OS's

The following OSs are supported:

Linux yay
MacOS boo (Apple Silicon Only)

[!NOTE]
Note - MacOS supports is on MinKNOW 5.7 and greater using Dorado basecaller on Apple Silicon devices only.

Citation

The paper is available at nature biotechnology and bioRxiv

If you use this software please cite: 10.1038/s41587-020-00746-x

Readfish enables targeted nanopore sequencing of gigabase-sized genomes Alexander Payne, Nadine Holmes, Thomas Clarke, Rory Munro, Bisrat Debebe, Matthew Loose Nat Biotechnol (2020); doi: https://doi.org/10.1038/s41587-020-00746-x

Other works

An update preprint is available at bioRxiv

Barcode aware adaptive sampling for Oxford Nanopore sequencers Alexander Payne, Rory Munro, Nadine Holmes, Christopher Moore, Matt Carlile, Matthew Loose bioRxiv (2021); doi: https://doi.org/10.1101/2021.12.01.470722

Installation

Our preferred installation method is via conda.

The environment is specified as:

name: readfish
channels:
  - bioconda
  - conda-forge
  - defaults
dependencies:
  - python=3.10
  - pip
  - pip:
    - readfish[all]

Saving the snippet above as readfish_env.yml and running the following commands will create the environment.

conda env create -f readfish_env.yml
conda activate readfish

Apple Silicon

Some users may encounter an issue with grpcio on apple silicon. This can be fixed by reinstalling grpcio as follows:

pip uninstall grpcio
GRPC_PYTHON_LDFLAGS=" -framework CoreFoundation" pip install grpcio --no-binary :all:

Installing with development dependencies

A conda yaml file is available for installing with dev dependencies - development.yml

curl -LO https://raw.githubusercontent.com/LooseLab/readfish/e30f1fa8ac7a37bb39e9d8b49251426fe1674c98/docs/development.yml?token=GHSAT0AAAAAACBZL42IS3QVM4ZGPPW4SHB6ZE67V6Q
conda env create -f development.yml
conda activate readfish_dev

| <h2>‼️ Important !! </h2> | |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MinKNOW has now transitioned from Guppy to Dorado. Until MinKNOW version 5.9 both Guppy and Dorado used ont-pyguppy-client-lib.<br/>As of MinKNOW version 5.9 and Dorado server version 7.3.9 and greater Dorado required an alternate library, ont-pybasecall-client-lib, but guppy could still be used. <br/> As of MinKNOW 6.0 Guppy support has been deprecated and only Dorado support is provided. It is important to ensure the correct library is installed for your specific configuration and the listed ont-pyguppy-client-lib or ont-pybasecaller-client-lib version may not match the versions installed on your system. To fix this, Please see this issue, using the appropriate library. |

ONT's Dorado Basecall Server GPU should be installed and running as a server.

<details style="margin-top: 10px"> <summary><span id="py-ve">Alternatively, install readfish into a python virtual-environment</span></summary>

# Make a virtual environment
python3 -m venv readfish
. ./readfish/bin/activate
pip install --upgrade pip

# Install our readfish Software
pip install readfish[all]

# Install ont_pybasecall_client that matches your dorado basecall server version. E.G.
pip install ont_pybasecall_client_lib==7.1.2

</details> <details style="margin-top: 10px" open> <summary id="usage"><h3 style="display: inline;">Usage</h3></summary>

usage: readfish [-h] [--version]  ...

positional arguments:
                   Sub-commands
    targets        Run targeted sequencing
    barcode-targets
                   Run targeted sequencing
    unblock-all    Unblock all reads
    validate       readfish TOML Validator

options:
  -h, --help       show this help message and exit
  --version        show program's version number and exit

See '<command> --help' to read about a specific sub-command.

</details>

TOML File

For information on the TOML files see TOML.md. There are several example TOMLS, with comments explaining what each field does, as well as the overall purpose of the TOML file here .

<details style="margin-top: 10px; margin-bottom: 10px" open><summary id="testing"><h1 style="display: inline">Testing</h1></summary>  To test readfish on your configuration we recommend first running a playback experiment to test unblock speed and then selection.

The following steps should all happen with a configuration (test) flow cell inserted into the target device. A simulated device can also be created within MinKNOW, following these instructions. This assumes that you are runnning MinKNOW locally, using default ports. If this is not the case a developer API token is required on the commands as well, as well as setting the correct port.

If no test flow cell is available, a simulated device can be created within MinKNOW, following the below instructions.

<details style="margin-top: 10px; margin-bottom: 10px"><summary id="testing"><h3 style="display: inline">Adding a simulated position for testing</h3></summary>

Linux

In the readfish virtual environment we created earlier:

See help

python -m minknow_api.examples.manage_simulated_devices --help

Add Minion position

python -m minknow_api.examples.manage_simulated_devices --add MS00000

Add PromethION position

python -m minknow_api.examples.manage_simulated_devices --prom --add S0

Mac

In the readfish virtual environment we created earlier:
- See help
```
python -m mink
```

Readfish

Install / Use

README