Metadata-Version: 2.1
Name: pytximport
Version: 0.4.0
Summary: A python implementation of tximport to transform transcript into gene counts
Author-email: Malte Kuehl <malte.kuehl@clin.au.dk>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Dist: anndata
Requires-Dist: click
Requires-Dist: dask
Requires-Dist: flox
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tqdm
Requires-Dist: xarray
Requires-Dist: bandit ; extra == "dev"
Requires-Dist: black[jupyter] ; extra == "dev"
Requires-Dist: certifi ; extra == "dev"
Requires-Dist: coverage ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: flake8-comprehensions ; extra == "dev"
Requires-Dist: flake8-docstrings ; extra == "dev"
Requires-Dist: flit ; extra == "dev"
Requires-Dist: furo ; extra == "dev"
Requires-Dist: ipykernel ; extra == "dev"
Requires-Dist: isort ; extra == "dev"
Requires-Dist: jupyter-client ; extra == "dev"
Requires-Dist: jupyter-core ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: myst-parser ; extra == "dev"
Requires-Dist: nbsphinx ; extra == "dev"
Requires-Dist: pandoc ; extra == "dev"
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: pybiomart ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: sphinx ; extra == "dev"
Requires-Dist: sphinx-autoapi ; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints ; extra == "dev"
Requires-Dist: sphinx-copybutton ; extra == "dev"
Requires-Dist: sphinx-design ; extra == "dev"
Requires-Dist: sphinx-rtd-theme ; extra == "dev"
Requires-Dist: virtualenv ; extra == "dev"
Project-URL: Documentation, https://pytximport.readthedocs.io/en/latest/
Project-URL: Home, https://github.com/complextissue/pytximport
Project-URL: Source, https://github.com/complextissue/pytximport
Provides-Extra: dev

# pytximport

[![Version](https://img.shields.io/pypi/v/pytximport)](https://pypi.org/project/pytximport/)
[![Code Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/complextissue/pytximport/ci.yml)
[![Documentation Status](https://readthedocs.org/projects/pytximport/badge/?version=latest)](https://pytximport.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/complextissue/pytximport/graph/badge.svg?token=M9JEHJVXYI)](https://codecov.io/gh/complextissue/pytximport)
![PyPI - Downloads](https://img.shields.io/pypi/dm/pytximport)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Python Version Required](https://img.shields.io/pypi/pyversions/pytximport)](https://pypi.org/project/pytximport/)
[![License](https://img.shields.io/pypi/l/pytximport)](https://github.com/complextissue/pytximport)

`pytximport` is a Python package for fast gene count estimation based on transcript quantification files produced by pseudoalignment/quasi-mapping tools such as `kallisto` or `salmon`. `pytximport` is a port of the popular [tximport Bioconductor R package](https://bioconductor.org/packages/release/bioc/html/tximport.html).

## Documentation

Detailled documentation is made available at: [https://pytximport.readthedocs.io](https://pytximport.readthedocs.io/en/latest/start.html).

## Development status

`pytximport` is still in development and has not yet reached version 1.0.0 in the [SemVer](https://semver.org/) versioning scheme. While it should work for most use cases and we regularly compare outputs against the R implementation, expect breaking changes. If you encounter any problems, please open a GitHub issue. If you are a Python developer, we welcome pull requests implementing missing features, adding more extensive unit tests and bug fixes.

## Motivation

The `tximport` package has become a main stay in the bulk RNA sequencing community and has been used in hundreds of scientific publications. However, its accessibility has remained limited since it requires the R programming language and cannot be used from within Python scripts or the command line. Other tools of the bulk RNA sequencing analysis stack, like `DESeq2` (in the form of `PyDESeq2`), `decoupler`, `liana` and others all have Python versions. Additionally, pseudoalignment tools like `salmon` and `kallisto` can be installed via `conda` and can be used from the command line.
`tximport` thus constitutes the missing link in many common analysis workflows. `pytximport` fills this gap and allows these workflows to be entirely done in Python, which is preinstalled on most development machines, and from the command line.

## Installation

```bash
pip install pytximport
```

## Quick Start

You can either use it from the command line:

```bash
pytximport -i ./sample_1.sf -i ./sample_2.sf -t salmon -m ./tx2gene_map.tsv -o ./output_counts.csv
```

Common options are:
- `-i`: The input files.
- `-t`: The input type, e.g., `salmon`, `kallisto` or `tsv`.
- `-m`: The map to match transcript ids to their gene ids. Expected column names are `transcript_id` and `gene_id`.
- `-o`: The output path.
- `-c`: The count transform to apply. Leave out for none, other options include `scaled_tpm`, `length_scaled_tpm` and `dtu_scaled_tpm`.
- `-tx`: Whether to return transcript-level counts without gene summarization.
- `-id`: The column name containing the transcript ids, in case it differs from the typical naming standards for the configured input file type.
- `-counts`: The column name containing the transcript counts, in case it differs from the typical naming standards for the configured input file type.
- `-length`: The column name containing the transcript lenghts, in case it differs from the typical naming standards for the configured input file type.
- `-tpm`: The column name containing the transcript abundance, in case it differs from the typical naming standards for the configured input file type.

Or import the `tximport` function in your Python files:

```python
from pytximport import tximport
results = tximport(
    file_paths,
    "salmon",
    transcript_gene_mapping,
)
```

## Citation

Please cite both the original publication as well as this Python implementation:
- Charlotte Soneson, Michael I. Love, Mark D. Robinson. Differential analyses for RNA-seq: transcript-level estimates improve gene-level inferences, F1000Research, 4:1521, December 2015. doi: 10.12688/f1000research.7563.1
- Kuehl, M., & Puelles, V. (2024). pytximport: Fast gene count estimation from transcript quantification files in Python (Version 0.4.0) [Computer software]. https://github.com/complextissue/pytximport


## License

The software is provided under the GNU General Public License version 3. Please consult `LICENSE` for further information.

## Differences

Generally, outputs from `pytximport` correspond to the outputs from `tximport` within the accuracy allowed by multiple floating point operations and small implementation differences in its dependencies when using the same configuration. If you observe larger discrepancies, please open an issue.

While the outputs are roughly identical for the same configuration, there remain some differences between the packages:
- `pytximport` can be used from the command line.
- `pytximport` supports `AnnData` format outputs (set `output_type` to `anndata`), enabling seamless integration with the `scverse`.
- `pytximport` currently does not support inferential replicates. If these are valuable to your workflow, we appreciate pull requests to add support.
- `pytximport` currently does not support gene-level inputs. If these are valuable to your workflow, we appreciate pull requests to add support.
- Argument order and argument defaults may differ between the implementations.
- Additional features:
    - When `ignore_transcript_version` is set, the transcript version will not only be scrapped from the quantization file but also from the provided transcript to gene mapping.
    - When `biotype_filter` is set, all transcripts that do not contain any of the provided biotypes will be removed prior to all other steps.
    - When `save_path` is configured, a count matrix will be saved as a .csv file.

## Building the documentation locally

The documentation can be build locally by navigating to the `docs` folder and running: `make html`.
This requires that the development requirements of the package as well as the package itself have been installed in the same virtual environment and that `pandoc` has been added, e.g. by running `brew install pandoc` on macOS operating systems.

