`plot`

Generate data visualizations from data files. Supports histograms, bar charts, scatter plots, and line plots for quick data exploration.

# Generate histogram for numerical field
undatum plot data.csv --field age --type histogram --output age_dist.png

# Generate bar chart for categorical field
undatum plot data.csv --field status --type bar

# Generate scatter plot for two fields
undatum plot data.csv --field x,y --type scatter --output scatter.png

# Generate line plot
undatum plot data.csv --field value --type line --output trend.png

# Auto-detect plot type based on field type
undatum plot data.csv --field age --output age_plot.png

# Multiple fields in subplots
undatum plot data.csv --field age,income,score --type histogram --output distributions.png

# Customize plot appearance
undatum plot data.csv --field age --title "Age Distribution" \
  --xlabel "Age (years)" --ylabel "Frequency" \
  --width 12 --height 8 --dpi 150 --output age_plot.png

# Filter before plotting, keep the top categories
undatum plot data.csv --field city --type bar --filter '`status` == "active"' \
  --top-n 10 --output cities.png

# Bar chart of summed amounts by category
undatum plot data.csv --field city --type bar --aggregate sum --value-field amount \
  --output totals.png
undatum plot workbook.xlsx --table Sheet2 --field city --type bar --output cities.png
undatum plot nested.jsonl --field capital_city.lat --flatten-nested --type histogram --output lats.png

Plot Types:

histogram - Distribution of numerical values (default for numerical fields)
bar - Frequency of categorical values (default for categorical fields)
scatter - Relationship between two numerical fields
line - Time series or sequential data
auto - Auto-detect based on field type (default)

Output Formats:

PNG (default) - Raster image format
SVG - Vector image format
PDF - Print-ready document format

Features:

Auto-detection: Automatically suggests appropriate plot type based on field data type
Multiple fields: Generate multiple subplots for multiple fields
Customizable: Control titles, labels, colors, size, and resolution
Multiple formats: Save as PNG, SVG, or PDF
Display mode: Show plot interactively if no output file specified

Options:

--field: Field name(s) to plot (comma-separated for multiple)
--type: Plot type (histogram, bar, scatter, line, or auto)
--output: Output file path (if not specified, displays plot)
--format: Output format (png, svg, or pdf)
--title: Plot title
--xlabel: X-axis label
--ylabel: Y-axis label
--width: Figure width in inches (default: 10)
--height: Figure height in inches (default: 6)
--dpi: Resolution for raster formats (default: 100)
--color: Color scheme name (matplotlib colormap)
--style: Matplotlib style name (e.g. ggplot)
--filter: Filter expression applied before plotting
--aggregate: Bar-chart aggregation (count, sum, mean, or none)
--value-field: Numeric field to sum/mean when --aggregate is sum or mean
--top-n: Keep the top N aggregated groups for bar charts

Requirements:

Install the plot extra: pip install "undatum[plot]" (includes matplotlib)

Reference

Reads: any readable format · Writes: a chart image (PNG, SVG, PDF) · Memory: loads the plotted fields · Engines: python

undatum plot [OPTIONS] INPUT_FILE

Argument	Description
`INPUT_FILE`	Path to input file. (required)

Option	Description	Default
`--field` TEXT	Field name(s) to plot (comma-separated for multiple fields). (required)
`--type` TEXT	Plot type: 'histogram', 'bar', 'scatter', 'line', or 'auto' (default: auto).	`auto`
`-o`, `--output` TEXT	Output file path. If not specified, displays plot.
`-O`, `--format-out` TEXT	Output format: 'png', 'svg', or 'pdf' (default: auto-detect from output file).
`--title` TEXT	Plot title.
`--xlabel` TEXT	X-axis label.
`--ylabel` TEXT	Y-axis label.
`--width` FLOAT	Figure width in inches (default: 10).	`10`
`--height` FLOAT	Figure height in inches (default: 6).	`6`
`--dpi` INTEGER	Resolution for raster formats (default: 100).	`100`
`--color` TEXT	Color scheme name (matplotlib colormap).
`--style` TEXT	Matplotlib style name (e.g. 'ggplot', 'seaborn-v0_8').
`--filter`, `--filter-expr` TEXT	Filter expression applied before plotting.
`--aggregate` TEXT	Aggregation for bar charts: count (default), sum, mean, or none.	`count`
`--value-field` TEXT	Numeric field to sum/mean when --aggregate is sum or mean.
`--top-n` INTEGER	Keep the top N aggregated groups for bar charts.
`--verbose` / `--no-verbose`	Enable verbose logging output.	`--no-verbose`
`--table`, `--sheet` TEXT	Table or sheet name for multi-table sources (Excel, SQLite, lakehouse).
`--quotechar` TEXT	CSV quote character (iterabledata default '"' when omitted).
`--start-page` INTEGER	Sheet index (0-based) for Excel files.	`0`
`--trust`	Acknowledge pickle deserialization risk when reading pickle sources.
`--on-error` TEXT	Parse-error policy: raise (default), skip, or warn.
`--error-log` TEXT	Append parse errors as JSONL (use with --on-error skip or warn).
`--flatten-nested`	Unfold nested dict / array-of-dict fields into dotted paths (e.g. city.lat).
`--max-nested-depth` INTEGER	With --flatten-nested, maximum nest depth to unfold (engine default 5).
`--keep-nested-parents` / `--no-keep-nested-parents`	With --flatten-nested, keep parent dict/array fields alongside dotted children.	`--keep-nested-parents`

Deprecated spellings (removed in 2.0): --format → --format-out.

Reference​

Reference