Metadata-Version: 2.4
Name: visualdna
Version: 0.1.0
Summary: Render DNA sequences as genomic visual documents and build reproducible image datasets.
Author: Hongxin Xiang
License-Expression: MIT
Keywords: genomics,DNA,genomic visual documents,visualization,rendering,bioinformatics
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 :: Multimedia :: Graphics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: licenses/DejaVu-LICENSE.txt
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: pillow>=9.0
Requires-Dist: pyarrow>=12
Requires-Dist: requests>=2.28
Requires-Dist: tqdm>=4.64
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mkdocs<2,>=1.6; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

```bash
visualdna --version
```

Expected output:

```text
visualdna 0.1.0
```

## Render one sequence

### Python API

```python
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

```bash
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`:

```bash
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` |

```python
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:

```text
/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.

```python
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:

```text
/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/`.

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

## Development and release validation

```bash
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.
