Metadata-Version: 2.4
Name: pycircdb
Version: 1.0.3
Summary: pycircdb: integrated circRNA database annotation for computational workflows.
Author-email: Barry Digby <b.digby237@gmail.com>
Requires-Python: >=3.10.1
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apache-hamilton>=1.90.0
Requires-Dist: boto3>=1.42.89
Requires-Dist: click>=8.3.2
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: polars>=1.39.3
Requires-Dist: rich-click>=1.9.7
Dynamic: license-file

<h1>
<picture>
  <source media="(prefers-color-scheme: light)" srcset="https://github.com/BarryDigby/pycircdb/raw/main/assets/pycircdb.png">
  <img src="https://github.com/BarryDigby/pycircdb/raw/main/assets/pycircdb.png" alt="pycircdb">
</picture>
</h1>

##### Explore the [documentation](https://pycircdb.readthedocs.io/en/latest/) to get up and running!
![Database Version](https://img.shields.io/badge/database-v1.0-blue)
[![PyPI Version](https://img.shields.io/pypi/v/pycircdb)](https://pypi.python.org/pypi/pycircdb/)
[![DOI](https://img.shields.io/badge/DOI-pending-red.svg)](#)

---

pycircdb is a CLI tool to annotate circular RNAs output by circRNA quantification tools by integrating multiple public circRNA databases into a reproducible set of outputs across samples.

Annotations are generated by reading one-column text files of circRNA coordinates in `chr:start-end|strand` format (strand optional). Coordinates are mapped using a tolerant coordinate matching strategy that accepts both 0-based and 1-based genomic positions, which are then queried against curated circRNA databases. For each sample, pycircdb produces annotation tables, FASTA sequences, and miRNA and RBP interaction files.

> pycircdb is designed to bring traditional GUI 'point-and-click' circRNA databases to the command line, facilitating its use in computational workflows. pycircdb is lightweight - requiring only 3.6 GB of disk space when the full parquet database is downloaded.  

A range of circRNA databases are supported, including Arraystar, circAtlas, circBank, circBase, CircNet, CIRCpedia, circRNADb, CSCD, and exoRBase.

Please refer to the pycircdb documentation for a complete description of the databases and outputs.

 ## Installation

You can install pycircdb using [uv](https://docs.astral.sh/uv/) (no separate Python installation required):

```bash
uv tool install pycircdb
```

Alternatively, install from [PyPI](https://pypi.python.org/pypi/multiqc/) using `pip`:

```bash
pip install pycircdb
```

## Usage

### Quickstart

Once installed, you can perform a minimal test-run to ensure the tool works as expected:

```bash
pycircdb init-demo
```

<picture>
  <source media="(prefers-color-scheme: light)" srcset="https://github.com/BarryDigby/pycircdb/raw/main/assets/pycircdb-init-demo.png">
  <img src="https://github.com/BarryDigby/pycircdb/raw/main/assets/pycircdb-init-demo.png" alt="pycircdb">
</picture>


```bash
pycircdb -c test_config.json -v 2 annotate fasta mirna rbp
```

<picture>
  <source media="(prefers-color-scheme: light)" srcset="https://github.com/BarryDigby/pycircdb/raw/main/assets/pycircdb-demo-run.png">
  <img src="https://github.com/BarryDigby/pycircdb/raw/main/assets/pycircdb-demo-run.png" alt="pycircdb">
</picture>


The demo will produce the following output directory:

```bash
/home/barry/pycircdb_demo/results/
results/
└── demo
    ├── demo_sample
    │   ├── arraystar_hg19.fasta
    │   ├── arraystar_hits.txt
    │   ├── circatlas_hits.txt
    │   ├── circbank_hg19.fasta
    │   ├── circbank_hits.txt
    │   ├── circbase_hg19.fasta
    │   ├── circbase_hits.txt
    │   ├── circpedia_hg38.fasta
    │   ├── circpedia_hits.txt
    │   ├── circRNADb_hg19.fasta
    │   ├── circRNADb_hits.txt
    │   ├── cscd_hg38.fasta
    │   ├── cscd_hits.txt
    │   ├── exorbase_hits.txt
    │   ├── hg38_chr1_mirna_hits.txt.gz
    │   └── hg38_chr1_rbp_hits.txt.gz
    └── execution_report_YYYY-mm-dd_HH:MM:SS.txt

2 directories, 17 files
```

### Configuration

pycircdb requires an input configuration JSON file in order to locate input samples and define global and per-sample configuration settings.

Please see the [documentation](https://pycircdb.readthedocs.io/en/latest/) for a full description of the config file.

```json
{
  "global_parameters": {
    "max_tasks": 1,
    "output_dir": "results/",
    "tmp_dir": "tmp/"
  },
  "samples": {
    "SRR5133906_circexplorer2": {
      "file_path": "reformatted/SRR5133906/SRR5133906_circexplorer2.txt",
      "reference": "hg19"
    },
    "SRR5133906_ciriquant": {
      "file_path": "reformatted/SRR5133906/SRR5133906_ciriquant.txt",
      "reference": "hg19"
    }
  }
}
```

### Commands

For a full description of pycircdb commands and their options, please refer to the [documentation](https://pycircdb.readthedocs.io/en/latest/).


## Citation

Please consider citing pycircdb if you use it in your analysis

> **pycircdb: integrated circRNA database annotation for computational workflows** <br> _Barry Digby, Stephen Finn, Pilib Ó Broin_ <br>
> Pending (2026) <br>
> doi: [pending](pending)) <br>
> PMID: [pending](pending)

```BibTeX
@article{pending,
 author = {Digby, Barry and Finn, Stephen and Ó Broin, Pilib},
 title = {pycircdb: integrated circRNA database annotation for computational workflows},
 journal = {pending},
 volume = {pending},
 number = {pending},
 pages = {pending},
 year = {pending},
 doi = {pending},
 URL = {pending},
 eprint = {pending}
}
```

## Contributions & Support

Contributions, particularly new circRNA database resources are welcome, as are bug reports!
Please create a new [issue](https://github.com/BarryDigby/pycircdb/issues) for any of these, preferably with the `-v 2` flag enabled for richer logs.
Pull-requests for fixes and additions are very welcome.

## Funding

This work was funded by Science Foundation Ireland, grant number 18/CRT/6214.
