Explore the documentation to get up and running!

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 (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 fasta mirna rbp

The demo will produce the following output directory:

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

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

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.