Installation
System requirements
Software dependency
python >= 3.10 (raised in v1.0.9; 3.9 is EOL and the networkx>=3.3 dependency requires >=3.10)
numpy >= 1.22.0
gffutils >= 0.10.1
biopython>=1.76
parasail>=1.2.4
intervaltree>=3.1.0
networkx>=3.3
interlap>=0.2.6
miniprot >= 0.10.0 (external binary — see below)
minimap2 >= 2.17 (external binary — see below)
pyfaidx>=0.5.8
pysam>=0.19.1
ujson>=3.2.0
duckdb>=1.0,!=1.5.3,!=1.5.4
pyarrow>=14
mappy (optional; install
lifton[native]or a prebuilt Conda package)
Pip resolves LiftOn's Python dependencies. It does not install the external
minimap2 and miniprot executables. Fresh standard lifts require both on
PATH: minimap2 supplies Liftoff's DNA alignment and miniprot supplies protein
alignment. LiftOn checks the tools it will use before starting a run. Evaluation
and valid precomputed -L/-M inputs do not require the corresponding aligner.
Install the executables through Conda as shown below, or follow their upstream
minimap2 and
miniprot installation guides.
Version warning
LiftOn requires Python >= 3.10 (v1.0.9 raised the floor from 3.6 to 3.10; 3.9 is EOL and the networkx>=3.3 dependency requires >=3.10).
DuckDB 1.5.3 and 1.5.4 have an upstream GEOMETRY append bug that can
affect large --stream miniprot results. Pip will avoid those releases.
In an existing environment, use DuckDB 1.5.2 or set
LIFTON_DISABLE_RTREE=1; LiftOn's results are unchanged because region
queries fall back to the standard B-tree index.
A target containing any sequence at least 2^31 bases long requires miniprot >= 0.14. LiftOn v1.0.12 fails preflight for a parseable older version rather than risk the known long-sequence limitation. Other targets retain the general miniprot >= 0.10 minimum.
Check out the scientific python ecosystem coordination guideline SPEC 0 — Minimum Supported Versions to configure the package version compatibility.
Compiled Python dependencies and macOS
Dependencies such as parasail, pysam, duckdb and pyarrow contain
compiled code. Wheels are available on common Linux platforms. When a wheel
is unavailable, particularly on macOS / Apple Silicon, use prebuilt Conda
packages rather than relying on a local source build:
$ conda create -n lifton -y --override-channels -c conda-forge -c bioconda \
--strict-channel-priority python=3.11 pip numpy biopython \
parasail-python pysam pyfaidx gffutils intervaltree interlap \
networkx ujson 'python-duckdb>=1.0,!=1.5.3,!=1.5.4' 'pyarrow>=14' \
minimap2 miniprot
$ conda activate lifton
$ python -m pip install lifton
The vendored gffbase backend runs pure-Python by default (no
pre-built .so ships in the package), so no Rust toolchain is required to
install or run LiftOn.
There are three ways that you can install LiftOn:
Install through pip
Install the Python runtime from PyPI, then install the two external aligners. Activate the intended environment first:
$ python -m pip install lifton
$ conda install --override-channels -c conda-forge -c bioconda \
--strict-channel-priority minimap2 miniprot
$ minimap2 --version
$ miniprot --version
$ lifton -V
Optional experimental mappy binding
Standard runs and --native compatibility hooks do not require mappy. Only
--native together with LIFTON_NATIVE_LIFTOFF_ALIGN=1 activates the
experimental in-process Liftoff alignment path. To supply its optional binding:
$ python -m pip install 'lifton[native]'
Mappy often builds from source, requiring a C compiler and zlib development
headers (for example, build-essential and zlib1g-dev on Debian/Ubuntu).
These build tools are unnecessary for a standard LiftOn install on a platform
with wheels for its compiled dependencies. A prebuilt alternative is:
$ conda install --override-channels -c conda-forge -c bioconda \
--strict-channel-priority mappy
Installing mappy does not install the miniprot executable or activate the experimental path. If the binding is absent, an explicitly requested path falls back to subprocess minimap2 with a warning; minimap2 must then be available.
Install through conda
A bioconda recipe for LiftOn has been submitted and is under review. Once it is merged, the command below will install LiftOn together with all of its dependencies:
$ conda create -n lifton --override-channels -c conda-forge -c bioconda \
--strict-channel-priority python=3.11 lifton
$ conda activate lifton
The recipe includes prebuilt mappy, minimap2 and miniprot. Check the available LiftOn version before relying on this command; a submitted recipe is not yet an installable channel package.
Install from source
You can also install LiftOn from source. Check out the latest version on GitHub !
$ git clone https://github.com/Kuanhao-Chao/LiftOn
$ cd LiftOn
$ python -m pip install .
Seqera Containers / Wave
A pip-only container installs Python packages but lacks the aligner executables. For a complete standard environment, select Conda Python, minimap2 and miniprot, plus pip LiftOn. Pin Python explicitly instead of accepting Wave's latest default. The equivalent environment specification for the packaging release is:
channels:
- conda-forge
- bioconda
dependencies:
- python=3.11
- pip
- minimap2
- miniprot
- pip:
- lifton==1.0.14
Use the v1.0.14 pin after its PyPI publication. v1.0.13 already excludes mappy
from a standard pip install; v1.0.12 and older can require GCC/zlib headers.
Once the updated Bioconda
recipe is published, use Conda lifton=1.0.14 instead of the pip subsection.
No compiler package is needed to install its prebuilt dependencies.
Check lifton -V, minimap2 --version and miniprot --version in the
container, then execute a representative lift. Help output alone does not confirm
that an annotation container is ready. Retain Wave's build report, environment
lockfile and image digest with workflow results.
Check LiftOn installation
Run the following command to make sure LiftOn is properly installed:
$ lifton -h
Now, you are ready to go !
Please continue to the Quick Start Guide.
