VisualDNA

VisualDNA renders DNA and IUPAC sequences as reproducible Genomic Visual Documents (GVDs) and converts user-supplied sequence tables into sharded image datasets.

Version 0.1.0 is the first public release. Its deliberately narrow public surface contains:

• visualdna.render for text, color-pixel, and grayscale-pixel rendering;
• visualdna.data.BaseBuilder and visualdna.data.ShardedBuilder for CSV/Parquet dataset construction;
• the visualdna render command-line interface.

Model architectures, training code, weights, dataset initializers, benchmark preprocessing, and private research components are not distributed.

Requirements

• Python 3.10 or newer
• Linux, macOS, or Windows

Installation

python -m pip install visualdna

The standard installation includes Parquet support because the public dataset builders accept both CSV and Parquet input.

Verify the installation:

visualdna --version

Expected output:

visualdna 0.1.0

Render one sequence

Python API

from visualdna.render import NaiveImageGenerator

sequence = "ATCGN" * 500

generator = NaiveImageGenerator(
    img_width=512,
    img_height=512,
    font_size=14,
    line_spacing=1.6,
)

result = generator.generate(
    text=sequence,
    output_dir="outputs/example",
    merge_pages=True,
    save_bbox=True,
)

print(result["num_pages"])

Command line

visualdna render \
  --sequence ATCGATCGNNNN \
  --output outputs/cli-demo \
  --mode text \
  --merge-pages \
  --save-bbox

A plain-text or FASTA file can be supplied with --input:

visualdna render \
  --input example.fa \
  --output outputs/from-fasta \
  --mode text

Rendering modes

Representation	Python class	CLI value
Text GVD	NaiveImageGenerator	text
Color pixels	ColorPixelGenerator	pixel-color
Grayscale pixels	GrayPixelGenerator	pixel-gray

from visualdna.render import ColorPixelGenerator, GrayPixelGenerator

ColorPixelGenerator(
    img_width=256,
    img_height=256,
    use_default_color_map=True,
).generate("ATCGN" * 1000, "outputs/color")

GrayPixelGenerator(
    img_width=256,
    img_height=256,
).generate("ATCGN" * 1000, "outputs/gray")

Build a sharded rendered dataset

The public builders consume a table that you prepare yourself. They do not download or initialize reference genomes or benchmark datasets.

For the following example, create this file first:

/path/to/visualdna_datasets/
└── hg38-2048/
    └── raw/
        └── hg38-2048.parquet

The Parquet table must contain:

• a unique, non-null index column that is integer-convertible when the default shard_key="index" is used;
• a non-null seq column containing DNA/IUPAC strings;
• optional columns beginning with label and an optional split column, which are copied into the generated index.

from visualdna.data import ShardedBuilder
from visualdna.render import BaseRenderConfig

config = BaseRenderConfig(
    img_width=640,
    img_height=640,
    font_size=14,
    line_spacing=1.6,
    merge_pages=True,
    save_bbox=True,
)

builder = ShardedBuilder(
    dataroot="/path/to/visualdna_datasets",
    dataset="hg38-2048",
    render_config=config,
    seq_columns=["seq"],
    raw_csv_url=None,
    force_generate=False,
    shard_size="auto",
    raw_format="parquet",
)

print(builder.render_dir)
print(builder.index_csv)

ShardedBuilder performs validation and rendering during construction; no additional run() call is required. Here, hg38-2048 is only the name of a user-prepared dataset. VisualDNA does not download or initialize hg38.

The generated data are stored under:

/path/to/visualdna_datasets/
└── hg38-2048/
    ├── raw/
    │   └── hg38-2048.parquet
    └── processed/
        └── render_text_w640_h640_.../
            ├── render_config.json
            ├── index.csv
            └── seq/
                └── image/
                    └── <shard directories>/
                        └── <index>/
                            ├── <index>.png
                            └── bbox.npz

CSV input follows the same layout, using raw/hg38-2048.csv and raw_format="csv".

Important builder behavior

• dataroot is the directory that contains dataset folders.
• dataset determines both the dataset folder and raw filename.
• With raw_format="parquet", the exact expected path is dataroot/dataset/raw/dataset.parquet.
• Existing complete render directories are reused when force_generate=False.
• A unique index is required because it determines output paths and shard placement.
• shard_size="auto" chooses a multi-level directory layout based on dataset size.

Public package boundary

Included:

• rendering configurations and generators;
• bounding-box reading and visualization;
• batch and multiprocessing rendering;
• generic CSV/Parquet builders and sharded storage;
• minimal utilities, type marker, tests, documentation, and release automation.

Excluded:

• all dataset initializers;
• dataset-specific readers and split definitions;
• models, layers, adapters, losses, metrics, optimizers, and trainers;
• pretrained weights and checkpoints;
• training/evaluation scripts and experiment configurations;
• benchmark-specific preprocessing and unpublished datasets;
• notebooks, generated images, caches, logs, and private Git history.

Documentation

Extended guides are included in the source repository under docs/.

python -m pip install -e ".[docs]"
mkdocs serve

Development and release validation

python -m pip install -e ".[dev]"
pytest
mkdocs build --strict
python -m build
python -m twine check --strict dist/*
python scripts/check_distribution.py dist/*

Versioning

• 0.1.0: first public rendering and builder release;
• 0.1.1: backward-compatible fixes;
• 0.2.0: new functionality or planned pre-1.0 API evolution;
• 1.0.0: first stable public API.

License

VisualDNA code is released under the MIT License. The bundled DejaVu Sans Mono font is distributed under its own license; see licenses/DejaVu-LICENSE.txt.

Citation

A machine-readable software citation is included in CITATION.cff. A paper citation can be added after the associated work becomes public.