plotnado/docs/cli.qmd at main · alsmith151/plotnado · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# CLI

PlotNado's CLI is a YAML-template workflow:

1. `plotnado init` infers a template from data files.
2. `plotnado validate` checks the template before plotting.
3. `plotnado plot` renders one or more regions.

Run commands through `uv` in the source tree:

```bash
uv run plotnado --help
```

## `plotnado init`

```bash
uv run plotnado init sample1.bw sample2.bw peaks.narrowpeak --auto --output template.yaml
```

Useful options:

| Option | Purpose |
|---|---|
| `--output`, `-o` | Write the YAML file to a specific path. |
| `--genome`, `-g` | Set a default genome such as `hg38` or `mm10`. |
| `--group-by` | Group files by a built-in strategy or regex. |
| `--auto` | Use inferred defaults without interactive prompts. |
| `--no-genes` | Do not add the genes guide track. |

Example template:

```yaml
genome: hg38
guides:
  genes: true
tracks:
  - path: sample1.bw
    type: bigwig
    title: sample1
    group: sample
  - path: peaks.narrowpeak
    type: narrowpeak
    title: peaks
```

## `plotnado validate`

```bash
uv run plotnado validate template.yaml
```

Validation checks YAML parsing, local file existence, group references, and template compilation.

## `plotnado plot`

```bash
uv run plotnado plot template.yaml --region chr1:1,000,000-1,100,000 --output output.png
```

Useful options:

| Option | Purpose |
|---|---|
| `--region`, `-r` | Genomic region or gene name; repeat for multiple outputs. |
| `--output`, `-o` | Explicit output path for a single region. |
| `--format`, `-f` | Output format such as `png`, `pdf`, `svg`, or `jpg`. |
| `--width`, `-w` | Override template width in inches. |
| `--dpi` | Output resolution. |

Examples:

```bash
uv run plotnado plot template.yaml --region chr1:1,000,000-2,000,000
uv run plotnado plot template.yaml --region GNAQ
uv run plotnado plot template.yaml --region chr1:1,000,000-2,000,000 --region chr2:5,000,000-6,000,000
uv run plotnado plot template.yaml --region chr1:1,000,000-2,000,000 --output plot.pdf --dpi 300
```

Gene-name resolution requires `genome` in the template.

## Python bridge

The template format is shared with the Python API:

```python
from plotnado import GenomicFigure

fig = GenomicFigure.from_template("template.yaml")
fig.save("output.png", region="chr1:1,000,000-1,100,000")
```

See [Template Schema](template_schema.qmd) for the compact field reference.