Metadata-Version: 2.4
Name: pycircdb
Version: 0.1.4
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: 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!

[![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, integrating multiple public circRNA databases into a reproducible set of outputs across many 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 fuzzy search that tolerates 0-based and 1-based genomic positions, then queried against curated circRNA databases. For each sample, pycircdb produces per-database annotation tables, predicted FASTA sequences, and miRNA and RBP interaction files.

pycircdb is designed to bring traditional GUI circRNA databases to the CLI facilitating its use in computational workflows. pycircdb is lightweight - a minimal 4.2 GB cached database size designed to be re-used across multiple runs. 

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

Please see 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 -d 'arraystar,circbase' fasta -d 'arraystar,circbase' mirna -a 'miRanda,TargetScan' 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/
└── demo
    └── demo_sample
        ├── arraystar.fasta
        ├── arraystar_hits.txt
        ├── circbase.fasta
        ├── circbase_hits.txt
        ├── hg38_chr10_mirna_hits.txt.gz
        ├── hg38_chr10_rbp_hits.txt.gz
        ├── hg38_chr13_mirna_hits.txt.gz
        ├── hg38_chr13_rbp_hits.txt.gz
        ├── hg38_chr19_mirna_hits.txt.gz
        └── hg38_chr19_rbp_hits.txt.gz

2 directories, 10 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": 4,
    "output_dir": "results/",
    "tmp_dir": "tmp/"
  },
  "samples": {
    "vromann": {
      "file_path": "test/vromann.txt",
      "reference": "hg38"
    },
    "glioblastoma_plus_dcc": {
      "file_path": "test/rnase_plus/glioblastoma_RNase_plus_dcc.txt",
      "reference": "hg38"
    },
    "glioblastoma_plus_ciriquant": {
      "file_path": "test/rnase_plus/glioblastoma_RNase_plus_ciriquant.txt",
      "reference": "hg38"
    }
  }
}
```

### 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.
