Metadata-Version: 2.4
Name: agct
Version: 0.2.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Intended Audience :: Science/Research
Requires-Dist: wags-tails
Requires-Dist: maturin ; extra == 'dev'
Requires-Dist: ruff==0.14.10 ; extra == 'dev'
Requires-Dist: prek>=0.2.23 ; extra == 'dev'
Requires-Dist: pytest ; extra == 'tests'
Requires-Dist: pytest-cov ; extra == 'tests'
Provides-Extra: dev
Provides-Extra: tests
License-File: LICENSE
Summary: Another Genome Conversion Tool: Python frontend to Rust chainfile crate
Author: James Stevenson, Kori Kuzma
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/genomicmedlab/agct/issues
Project-URL: Changelog, https://github.com/genomicmedlab/agct/releases
Project-URL: Documentation, https://github.com/genomicmedlab/agct
Project-URL: Homepage, https://github.com/genomicmedlab/agct
Project-URL: Source, https://github.com/genomicmedlab/agct

# agct: Another Genome Conversion Tool

[![image](https://img.shields.io/pypi/v/agct.svg)](https://pypi.python.org/pypi/agct)
[![image](https://img.shields.io/pypi/l/agct.svg)](https://pypi.python.org/pypi/agct)
[![image](https://img.shields.io/pypi/pyversions/agct.svg)](https://pypi.python.org/pypi/agct)
[![Actions status](https://github.com/genomicmedlab/agct/actions/workflows/checks.yaml/badge.svg)](https://github.com/genomicmedlab/agct/actions/checks.yaml)

<!-- description -->
Lift over positions between genomic reference assemblies, using the St. Jude's [chainfile](https://docs.rs/chainfile/latest/chainfile/) crate.
<!-- description -->

Enables significantly faster chainfile loading from cold start (see `analysis/`).

## Installation

Install from [PyPI](https://pypi.org/project/agct/):

```shell
python3 -m pip install agct
```

## Usage

Initialize a class instance:

```python3
from agct import Converter, Assembly, Strand

c = Converter(Assembly.HG19, Assembly.HG38)
```

> If a chainfile is unavailable locally, it's downloaded from UCSC and saved using the `wags-tails` package -- see the [wags-tails configuration instructions](https://github.com/GenomicMedLab/wags-tails?tab=readme-ov-file#configuration) for information on how to designate a non-default storage location.

Call ``convert_coordinate()``:

```python3
c.convert_coordinate("chr7", 140453136, 140453137, Strand.POSITIVE)
# returns [LiftoverResult(chrom='chr7', start=140753336, end=140753337, strand=<Strand.POSITIVE: '+'>, score=14633688187)]
```

## Development

The [Rust toolchain](https://www.rust-lang.org/tools/install) must be installed.

Create a virtual environment and install developer dependencies:

```shell
python3 -m virtualenv venv
source venv/bin/activate
python3 -m pip install -e '.[dev,tests]'
```

This installs Python code as editable, but after any changes to Rust code, run ``maturin develop`` to rebuild the Rust binary:

```shell
maturin develop
```

Be sure to install pre-commit hooks:

```shell
pre-commit install
```

Check Python style with `ruff`:

```shell
python3 -m ruff format . && python3 -m ruff check --fix .
```

Use `cargo fmt` to check Rust style (must be run from within the `rust/` subdirectory):

```shell
cd rust/
cargo fmt
```

Run tests with `pytest`:

```shell
pytest
```

