Atomizer/atomizer-dashboard/frontend/src/components/plotly/README.md

# Plotly Chart Components

Interactive visualization components using Plotly.js for the Atomizer Dashboard.

## Overview

These components provide enhanced interactivity compared to Recharts:
- Native zoom, pan, and selection
- Export to PNG/SVG
- Hover tooltips with detailed information
- Brush filtering (parallel coordinates)
- 3D visualization support

## Components

### PlotlyParallelCoordinates

Multi-dimensional data visualization showing relationships between all variables.

```tsx
import { PlotlyParallelCoordinates } from '../components/plotly';

<PlotlyParallelCoordinates
  trials={allTrials}
  objectives={studyMetadata.objectives}
  designVariables={studyMetadata.design_variables}
  paretoFront={paretoFront}
  height={450}
/>
```

**Props:**
| Prop | Type | Description |
|------|------|-------------|
| trials | Trial[] | All trial data |
| objectives | Objective[] | Objective definitions |
| designVariables | DesignVariable[] | Design variable definitions |
| paretoFront | Trial[] | Pareto-optimal trials (optional) |
| height | number | Chart height in pixels |

**Features:**
- Drag on axes to filter data
- Double-click to reset filters
- Color coding: FEA (blue), NN (orange), Pareto (green)

### PlotlyParetoPlot

2D/3D scatter plot for Pareto front visualization.

```tsx
<PlotlyParetoPlot
  trials={allTrials}
  paretoFront={paretoFront}
  objectives={studyMetadata.objectives}
  height={350}
/>
```

**Props:**
| Prop | Type | Description |
|------|------|-------------|
| trials | Trial[] | All trial data |
| paretoFront | Trial[] | Pareto-optimal trials |
| objectives | Objective[] | Objective definitions |
| height | number | Chart height in pixels |

**Features:**
- Toggle between 2D and 3D views
- Axis selector for multi-objective problems
- Click to select trials
- Hover for trial details

### PlotlyConvergencePlot

Optimization progress over trials.

```tsx
<PlotlyConvergencePlot
  trials={allTrials}
  objectiveIndex={0}
  objectiveName="weighted_objective"
  direction="minimize"
  height={350}
/>
```

**Props:**
| Prop | Type | Description |
|------|------|-------------|
| trials | Trial[] | All trial data |
| objectiveIndex | number | Which objective to plot |
| objectiveName | string | Objective display name |
| direction | 'minimize' \| 'maximize' | Optimization direction |
| height | number | Chart height |
| showRangeSlider | boolean | Show zoom slider |

**Features:**
- Scatter points for each trial
- Best-so-far step line
- Range slider for zooming
- FEA vs NN differentiation

### PlotlyParameterImportance

Correlation-based parameter sensitivity analysis.

```tsx
<PlotlyParameterImportance
  trials={allTrials}
  designVariables={studyMetadata.design_variables}
  objectiveIndex={0}
  objectiveName="weighted_objective"
  height={350}
/>
```

**Props:**
| Prop | Type | Description |
|------|------|-------------|
| trials | Trial[] | All trial data |
| designVariables | DesignVariable[] | Design variables |
| objectiveIndex | number | Which objective |
| objectiveName | string | Objective display name |
| height | number | Chart height |

**Features:**
- Horizontal bar chart of correlations
- Sort by importance or name
- Color: Red (positive), Green (negative)
- Pearson correlation coefficient

## Bundle Optimization

To minimize bundle size, we use:

1. **plotly.js-basic-dist**: Smaller bundle (~1MB vs 3.5MB)
   - Includes: scatter, bar, parcoords
   - Excludes: 3D plots, maps, animations

2. **Lazy Loading**: Components loaded on demand
   ```tsx
   const PlotlyParetoPlot = lazy(() =>
     import('./plotly/PlotlyParetoPlot')
       .then(m => ({ default: m.PlotlyParetoPlot }))
   );
   ```

3. **Code Splitting**: Vite config separates Plotly into its own chunk
   ```ts
   manualChunks: {
     plotly: ['plotly.js-basic-dist', 'react-plotly.js']
   }
   ```

## Usage with Suspense

Always wrap Plotly components with Suspense:

```tsx
<Suspense fallback={<ChartLoading />}>
  <PlotlyParetoPlot {...props} />
</Suspense>
```

## Type Definitions

```typescript
interface Trial {
  trial_number: number;
  values: number[];
  params: Record<string, number>;
  user_attrs?: Record<string, any>;
  source?: 'FEA' | 'NN' | 'V10_FEA';
}

interface Objective {
  name: string;
  direction?: 'minimize' | 'maximize';
  unit?: string;
}

interface DesignVariable {
  name: string;
  unit?: string;
  min?: number;
  max?: number;
}
```

## Styling

Components use transparent backgrounds for dark theme compatibility:
- `paper_bgcolor: 'rgba(0,0,0,0)'`
- `plot_bgcolor: 'rgba(0,0,0,0)'`
- Font: Inter, system-ui, sans-serif
- Grid colors: Tailwind gray palette

## Export Options

All Plotly charts include a mode bar with:
- Download PNG
- Download SVG (via menu)
- Zoom, Pan, Reset
- Auto-scale

Configure export in the `config` prop:
```tsx
config={{
  toImageButtonOptions: {
    format: 'png',
    filename: 'my_chart',
    height: 600,
    width: 1200,
    scale: 2
  }
}}
```