@page hexplot_cli Hexplot CLI

# Hexplot Command-Line Interface Update

## Summary

Updated both `hexplot` and `hexplot_interactive` binaries to accept command-line arguments for flexible plotting of eigenvalue CSV data.

## Changes Made

### 1. `hexplot` (Static PNG Plots)

**Previous Behavior:**
- Hardcoded directory paths
- Iterated over predefined combinations of dendrite/node/quadric types
- No command-line arguments

**New Behavior:**
- Fully command-line driven
- Accepts single CSV file input
- Flexible coloring by any metadata column
- Configurable output path, dimensions, and metrics

**Usage:**
```bash
hexplot <csv_file> [options]

Options:
  -o, --output <path>       Output PNG file path (default: output.png)
  -c, --color-by <column>   Column name to color by (default: column index 4)
  -t, --title <title>       Plot title (default: derived from filename)
  -m, --metric <metric>     Metric to use: L1, L2, or both (default: both)
  -w, --width <pixels>      Plot width in pixels (default: 2400 for both, 1200 for single)
  -h, --height <pixels>     Plot height in pixels (default: 1200)
  --help                    Show help message
```

**Examples:**
```bash
# Basic usage with defaults
hexplot data.csv

# Custom output and coloring
hexplot data.csv -o my_plot.png -c species -t "Neural Data"

# Single metric with custom dimensions
hexplot data.csv -m L1 -w 800 -h 800

# Color by different metadata column
hexplot data.csv -c cell_type -o cells.png
```

### 2. `hexplot_interactive` (Interactive HTML Plots)

**Previous Behavior:**
- Hardcoded directory paths
- Generated separate L1 and L2 HTML files for all combinations
- No command-line arguments

**New Behavior:**
- Command-line driven
- Generates interactive Plotly visualizations
- Hover highlighting for point groups
- Flexible coloring and metadata display

**Usage:**
```bash
hexplot_interactive <csv_file> [options]

Options:
  -o, --output <path>       Output HTML file path (default: output.html)
  -c, --color-by <column>   Column name to color by (default: column index 4)
  -t, --title <title>       Plot title (default: derived from filename)
  -m, --metric <metric>     Metric to use: L1, L2, or both (default: L1)
  -w, --width <pixels>      Plot width in pixels (default: 800)
  -h, --height <pixels>     Plot height in pixels (default: 800)
  --help                    Show help message
```

**Note:** When using `-m both`, two separate files are created: `output_L1.html` and `output_L2.html`

**Examples:**
```bash
# Basic usage
hexplot_interactive data.csv

# Custom settings
hexplot_interactive data.csv -o plot.html -c species -t "My Analysis"

# Generate both metrics
hexplot_interactive data.csv -m both -w 1000 -h 1000

# Color by cell type
hexplot_interactive data.csv -c cell_type -m L2
```

## Key Features

### Flexible Coloring

Both tools now support:
- **Column-based coloring**: Specify any metadata column name with `-c/--color-by`
- **Automatic color assignment**: Uses predefined colors for common values (Human, Mouse, Rat, CA1, CA3, etc.)
- **Color palette**: Automatically assigns colors from a 10-color palette for new values
- **Legend grouping**: Points with the same category are grouped in the legend

### CSV Format

Both tools expect CSV files with the following format:
```
eigenvalue_1, eigenvalue_2, eigenvalue_3, [metadata_columns...]
```

- First 3 columns: Eigenvalues (required)
- Remaining columns: Metadata for coloring and hover text
- Headers are used for column name matching

### Interactive Features (hexplot_interactive)

- **Hover tooltips**: Display all metadata for each point
- **Point highlighting**: Hover over one point to enlarge all 6 permutations
- **Legend interaction**: Click legend items to toggle visibility
- **Responsive**: Works in any modern web browser

## Build Commands

```bash
# Build hexplot (requires plotting feature)
make build-hexplot
# OR
cargo build --bin hexplot --features plotting

# Build hexplot_interactive (requires interactive feature)
cargo build --bin hexplot_interactive --features interactive

# Build both
make build-hexplot

# Release builds
make release-hexplot
```

## Backward Compatibility

The old behavior of iterating over directories can be replicated with a simple shell script:

```bash
#!/bin/bash
# Process all CSV files in a directory

DATA_DIR="/path/to/dataframes/"
OUTPUT_DIR="/path/to/output/"

for csv in "$DATA_DIR"/*.csv; do
    basename=$(basename "$csv" .csv)
    hexplot "$csv" -o "${OUTPUT_DIR}/${basename}.png"
done
```

## Technical Improvements

1. **HashMap-based metadata**: All CSV columns beyond eigenvalues are stored as metadata
2. **Flexible column indexing**: Color-by column found by name, not hardcoded position
3. **Error handling**: Clear error messages for missing files, columns, or invalid arguments
4. **Default values**: Sensible defaults for all options
5. **Help system**: Built-in help with `--help` flag

## Files Modified

- `src/bin/hexplot.rs` - Complete rewrite with CLI argument parsing
- `src/bin/hexplot_interactive.rs` - Complete rewrite with CLI argument parsing
- `Makefile` - Updated build targets (already includes these binaries)

## Testing

Both executables compile successfully and are ready for use:

```bash
# Test help
./target/debug/hexplot --help
./target/debug/hexplot_interactive --help

# Test with sample data
./target/debug/hexplot sample_data.csv -o test.png
./target/debug/hexplot_interactive sample_data.csv -o test.html
```

## Migration Guide

### Old Workflow
```bash
# Edit source code to change paths
# Recompile
cargo build --bin hexplot --features plotting
# Run
./target/debug/hexplot
```

### New Workflow
```bash
# No code changes needed
# Compile once
cargo build --bin hexplot --features plotting
# Use with any data
./target/debug/hexplot mydata.csv -c species -o myplot.png
./target/debug/hexplot otherdata.csv -c cell_type -m L1
```

## Future Enhancements

Potential additions:
- [ ] Color map customization via config file
- [ ] Batch processing mode for multiple files
- [ ] Export legend as separate file
- [ ] SVG output option for hexplot
- [ ] Configurable marker sizes
- [ ] Filter data by metadata values

---

**Status**: [DONE] Complete
**Date**: December 19, 2025
**Binaries**: `hexplot`, `hexplot_interactive`
**Features Required**: `plotting`, `interactive`
