Metadata-Version: 2.4
Name: gbdraw
Version: 0.14.3
Summary: A genome diagram generator for microbes and organelles
Author-email: Satoshi Kawato <kawato@kaiyodai.ac.jp>
License-Expression: MIT
Project-URL: Homepage, https://github.com/satoshikawato/gbdraw/
Project-URL: Documentation, https://github.com/satoshikawato/gbdraw/
Project-URL: Repository, https://github.com/satoshikawato/gbdraw/
Project-URL: Web App, https://gbdraw.app/
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: LICENSE_LIBERATION_FONTS.txt
Requires-Dist: numpy>=1.23
Requires-Dist: pandas
Requires-Dist: svgwrite
Requires-Dist: biopython
Requires-Dist: fonttools
Requires-Dist: bcbio-gff
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: export
Requires-Dist: cairosvg; extra == "export"
Provides-Extra: typecheck
Requires-Dist: mypy==2.4.0; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: cairosvg; extra == "dev"
Requires-Dist: gbdraw[typecheck]; extra == "dev"
Requires-Dist: Pillow; extra == "dev"
Requires-Dist: playwright==1.61.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6; extra == "dev"
Requires-Dist: ruff==0.15.12; extra == "dev"
Requires-Dist: setuptools>=61.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/satoshikawato/gbdraw/main/gbdraw/web/assets/gbdraw-logo-title.png" alt="gbdraw" width="420">
</p>

[![Static Badge](https://img.shields.io/badge/gbdraw%20webapp-8A2BE2)](https://gbdraw.app/)
[![DOI](https://img.shields.io/badge/DOI-10.64898/2026.04.07.716863-blue)](https://doi.org/10.64898/2026.04.07.716863)
[![Dimensions citations](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fmetrics-api.dimensions.ai%2Fdoi%2F10.64898%2F2026.04.07.716863&query=%24.times_cited&label=Dimensions%20citations&color=blue)](https://doi.org/10.64898/2026.04.07.716863)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/gbdraw/badges/version.svg)](https://anaconda.org/bioconda/gbdraw)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/gbdraw/badges/platforms.svg)](https://anaconda.org/bioconda/gbdraw)
[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/gbdraw/README.html)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/gbdraw/badges/latest_release_date.svg)](https://anaconda.org/bioconda/gbdraw)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/gbdraw/badges/downloads.svg)](https://anaconda.org/bioconda/gbdraw)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/gbdraw/badges/license.svg)](https://anaconda.org/bioconda/gbdraw)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/satoshikawato/gbdraw)

# gbdraw

![gbdraw](https://raw.githubusercontent.com/satoshikawato/gbdraw/main/examples/gbdraw_social_preview.png)

`gbdraw` is a command-line and browser-based tool for publication-quality genome diagrams. It accepts GenBank/DDBJ flatfiles or GFF3 + FASTA pairs and produces circular or linear plots in SVG, PNG, PDF, EPS, or PS.

[Interactive SVG output gallery](https://gbdraw.app/gallery/)
## Features

- Circular and linear genome diagrams from annotated sequence files
- Comparison tracks from LOSAT searches run by gbdraw or from BLAST outfmt 6 or 7 tables
- Reusable coordinate- and feature-targeted annotation tracks
- Browser-based GUI at [gbdraw.app](https://gbdraw.app/) and local GUI via `gbdraw gui`
- Fine-grained control over colors, labels, legends, and track layout
- Export to SVG, PNG, PDF, EPS, and PS (PNG, PDF, EPS, and PS require CairoSVG)

## Documentation

| Route | Use it for |
| --- | --- |
| [Tutorials](https://github.com/satoshikawato/gbdraw/blob/main/docs/TUTORIALS/README.md) | Build complete, reproducible figures in the web app, on the command line, or from Python. |
| [Technical documentation](https://github.com/satoshikawato/gbdraw/blob/main/docs/REFERENCE/README.md) | Look up controls, options, schemas, APIs, compatibility, outputs, and source provenance. |
| [FAQ](https://github.com/satoshikawato/gbdraw/blob/main/docs/FAQ.md) | Choose a layout, interface, or comparison method and resolve common problems. |
| [Gallery](https://github.com/satoshikawato/gbdraw/blob/main/docs/GALLERY.md) | Inspect finished static and interactive figures before choosing a workflow. |

The [documentation home](https://github.com/satoshikawato/gbdraw/blob/main/docs/DOCS.md) links the four routes above. Supporting
pages cover [installation](https://github.com/satoshikawato/gbdraw/blob/main/docs/INSTALL.md), [tutorial
inputs](https://github.com/satoshikawato/gbdraw/blob/main/docs/GETTING_TUTORIAL_DATA.md), [citation and project
background](https://github.com/satoshikawato/gbdraw/blob/main/docs/ABOUT.md), and the [changelog](https://github.com/satoshikawato/gbdraw/blob/main/CHANGELOG.md).
See the [0.14.3 release notes](https://github.com/satoshikawato/gbdraw/blob/main/docs/RELEASE_NOTES_0.14.3.md)
for the latest fixes, the [0.14.2 release notes](https://github.com/satoshikawato/gbdraw/blob/main/docs/RELEASE_NOTES_0.14.2.md), the [0.14.1 release notes](https://github.com/satoshikawato/gbdraw/blob/main/docs/RELEASE_NOTES_0.14.1.md), and the [0.14.0 release notes](https://github.com/satoshikawato/gbdraw/blob/main/docs/RELEASE_NOTES_0.14.0.md)
for changes and migration from 0.13.
See [Contributing](https://github.com/satoshikawato/gbdraw/blob/main/CONTRIBUTING.md) to report a bug, set up a development
environment, or submit a pull request.

## Use without local installation

The hosted web app runs entirely in your browser:

[https://gbdraw.app/](https://gbdraw.app/)

Uploaded genomic data stays on your machine. The hosted site uses Google Analytics 4 for aggregate page-usage metrics; gbdraw does not send uploaded genome files or generated diagrams to Google Analytics.

## Local installation

For regular use, Bioconda is the main installation path:

```bash
mamba create -n gbdraw -c conda-forge -c bioconda gbdraw
conda activate gbdraw
gbdraw -h
gbdraw gui
```

For development from source:

```bash
git clone https://github.com/satoshikawato/gbdraw.git
cd gbdraw
python -m pip install -e ".[dev]"
```

If you need PNG/PDF/EPS/PS export from a source install, add the optional export dependency:

```bash
python -m pip install -e ".[dev,export]"
```

Local GUI/Web assets have no hosted Google Analytics injection.
See [Installation](https://github.com/satoshikawato/gbdraw/blob/main/docs/INSTALL.md) for details, supported Python versions,
platform notes, and the PyPI route. The source version is `0.14.3`; check
[PyPI](https://pypi.org/project/gbdraw/) for available packages and
[GitHub Releases](https://github.com/satoshikawato/gbdraw/releases) for publication
dates. If the desired package is unavailable, use a source install.

## Draw your first figures

The gbdraw package ships small inputs in `gbdraw/web/tutorial-data/`: the
human mitochondrial genome (NCBI `NC_012920.1`), the phage Lambda
(`NC_001416.1`) and DE3 (`NC_042057.1`) genomes, and a LOSATN comparison table
of the two phages. These commands find that folder in the installed package, so
they work after `pip install gbdraw` and in a source checkout; run them in any
directory where you want the SVG files:

```bash
data=$(python -c "import gbdraw, pathlib; print(pathlib.Path(gbdraw.__file__).parent / 'web' / 'tutorial-data')")
gbdraw circular \
  --gbk "$data/human-mitochondrion/HmmtDNA.gbk" \
  --separate_strands \
  --track_type middle \
  --labels out \
  --species "<i>Homo sapiens</i>" \
  -o human_mitochondrion \
  -f svg
gbdraw linear \
  --gbk "$data/lambda/NC_001416.gb" "$data/de3/NC_042057.1.gb" \
  --blast "$data/lambda-de3-comparison/lambda-de3.losatn.tsv" \
  --separate_strands \
  --show_labels first \
  -o lambda_de3 \
  -f svg
```

gbdraw writes `human_mitochondrion.svg`, a labeled circular map, and
`lambda_de3.svg`, the two phage genomes joined by six comparison ribbons. The
[Quickstart](https://github.com/satoshikawato/gbdraw/blob/main/docs/QUICKSTART.md)
links the first Tutorials, which download the same records from NCBI and build
each figure step by step.

## Bug reports and suggestions

Please open an issue if you find a bug or want to propose an improvement:

https://github.com/satoshikawato/gbdraw/issues

## How to cite

If you use `gbdraw` in your research, please cite the preprint:
[![Dimensions citations](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fmetrics-api.dimensions.ai%2Fdoi%2F10.64898%2F2026.04.07.716863&query=%24.times_cited&label=Dimensions%20citations&color=blue)](https://doi.org/10.64898/2026.04.07.716863)

```text
Kawato, S. (2026). gbdraw: a genome diagram generator for microbes and organelles. bioRxiv. https://doi.org/10.64898/2026.04.07.716863
```
