HTML Reporting Standards Skill

Version: 1.0.0 Category: Standards Triggers: Creating reports, visualizations, interactive charts

Quick Reference

MANDATORY: Interactive Plots Only

✅ Allowed: Plotly, Bokeh, Altair, D3.js ❌ NOT Allowed: Static matplotlib PNG/SVG exports

Technology Selection

Use Case	Recommended	Why
General Analysis	Plotly	Easy, feature-rich, pandas integration
Statistical Viz	Altair	Grammar of graphics, declarative
Real-time Dashboards	Bokeh	Server capabilities, streaming
Custom Interactive	D3.js	Maximum flexibility
Time Series	Plotly	Excellent time series support
Large Datasets	Plotly (webGL) or Bokeh	Performance optimizations

Python Examples

Plotly (Recommended)

import plotly.express as px
import pandas as pd

# Load CSV with RELATIVE path
df = pd.read_csv('../data/processed/results.csv')

# Create interactive plot
fig = px.scatter(df, x='time', y='value',
                 color='category',
                 title='Interactive Results',
                 hover_data=['info'])

# Save as HTML
fig.write_html('../reports/analysis.html',
               include_plotlyjs='cdn',
               config={'responsive': True})

Bokeh

from bokeh.plotting import figure, output_file, save
import pandas as pd

df = pd.read_csv('../data/processed/results.csv')

p = figure(title='Interactive Dashboard')
p.circle(df['x'], df['y'], size=10, alpha=0.5)
p.sizing_mode = 'stretch_width'  # Responsive

output_file('../reports/dashboard.html')
save(p)

Altair

import altair as alt
import pandas as pd

df = pd.read_csv('../data/processed/results.csv')

chart = alt.Chart(df).mark_point().encode(
    x='time:T',
    y='value:Q',
    color='category:N',
    tooltip=['time', 'value', 'category']
).interactive()

chart.save('../reports/analysis.html')

Report Structure

Required HTML Sections

1. Header

   • Title, generation timestamp
   • Module/repository name
   • Author/generator info

2. Summary Statistics

   • Key metrics at glance
   • Record counts
   • Data quality indicators

3. Interactive Visualizations

   • Minimum 2-3 plots per report
   • Each plot MUST be interactive
   • Clear titles and labels

4. Data Table (optional)

   • Sortable/filterable
   • Show sample of data
   • Link to full CSV

5. Footer

   • Data source
   • Generation method
   • Contact info

Responsive Design

Reports must work on:

• Desktop (1920px+)
• Laptop (1366px)
• Tablet (768px)
• Mobile (375px)

Plotly responsive:

fig.update_layout(
    autosize=True,
    margin=dict(l=20, r=20, t=40, b=20),
)

CSV Data Handling

MANDATORY: Relative Paths

# ✅ CORRECT: Relative from report location
df = pd.read_csv('../data/processed/results.csv')

# ❌ WRONG: Absolute path
df = pd.read_csv('/mnt/github/workspace/data/results.csv')

# ❌ WRONG: Hardcoded path
df = pd.read_csv('C:/Users/user/data/results.csv')

Path Resolution Helper

from pathlib import Path

def get_data_path(filename, data_type='processed'):
    project_root = Path(__file__).parent.parent.parent
    return project_root / 'data' / data_type / filename

# Usage
df = pd.read_csv(get_data_path('analysis.csv'))

Multi-Plot Dashboard

from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(
    rows=2, cols=2,
    subplot_titles=('Time Series', 'Distribution',
                   'Correlation', 'Summary')
)

# Add plots
fig.add_trace(go.Scatter(...), row=1, col=1)
fig.add_trace(go.Histogram(...), row=1, col=2)
fig.add_trace(go.Scatter(...), row=2, col=1)

fig.update_layout(height=800, showlegend=True)
fig.write_html('../reports/dashboard.html', include_plotlyjs='cdn')

Best Practices

Performance Optimization

For large datasets (>10,000 points):

# Use WebGL rendering
fig = px.scatter(df, x='x', y='y', render_mode='webgl')

# Or sample for visualization
df_sample = df.sample(n=5000)
fig = px.scatter(df_sample, ...)

Accessibility

• Descriptive titles and labels
• Sufficient color contrast
• Keyboard navigation
• Readable font size (≥12pt)

Version Control

Don't commit: Generated HTML reports Do commit: Report generation scripts, templates, CSV data

# .gitignore
reports/*.html
!reports/index.html

Validation Checklist

• All plots are interactive (no static images)
• HTML report is generated
• CSV uses relative paths
• Report is responsive (tested mobile/desktop)
• Hover tooltips show data values
• Zoom/pan functionality works
• Legend is interactive
• Export options available
• Report loads in <3 seconds
• Works offline (embedded data or CDN fallback)

Full Reference

See: @docs/modules/standards/HTML_REPORTING_STANDARDS.md

---

Use this when creating reports, dashboards, or data visualizations.