Explore the documentation to get up and running!

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 (no separate Python installation required):

uv tool install pycircdb

Alternatively, install from PyPI using pip:

pip install pycircdb

Usage

Quickstart

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

pycircdb init-demo

pycircdb -c test_config.json -v 2 annotate -d 'arraystar,circbase' fasta -d 'arraystar,circbase' mirna -a 'miRanda,TargetScan' rbp

The demo will produce the following output directory:

/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 for a full description of the config file.

{
  "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.

Citation

Please consider citing pycircdb if you use it in your analysis

pycircdb: integrated circRNA database annotation for computational workflows
Barry Digby, Stephen Finn, Pilib Ó Broin
Pending (2026)
doi: pending)
PMID: pending

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