# Changelog

## Version 1.2 (2026-01-29)

### New Feature: Comparison Visualization

#### Added
- **`plot_hierarchical_heatmap_comparison()`** - New function for side-by-side matrix comparison
  - Compare N matrices horizontally (CT1, CT2, ..., CTN)
  - Shared row labels on the left (displayed once)
  - Independent CT labels on top of each matrix
  - All filtering and styling options supported

#### Why?
Enables direct visual comparison of:
- Different citation topics (CT1 vs CT2)
- Different normalizations (Coverage vs Max Row vs Hill)
- Production vs Impact
- Before/After time periods
- Regional or institutional differences

#### Usage

```python
from hierarchical_heatmap import plot_hierarchical_heatmap_comparison
import pandas as pd

# Compare two matrices
ct1 = pd.read_csv('ct1_matrix.csv', index_col=0)
ct2 = pd.read_csv('ct2_matrix.csv', index_col=0)
taxonomy = pd.read_csv('taxonomy.csv')

fig = plot_hierarchical_heatmap_comparison(
    evolution_matrices=[ct1, ct2],
    ct_labels=["CT1", "CT2"],
    classification_df=taxonomy,
    title="CT1 vs CT2 Comparison",
    output_html="comparison.html"
)
```

#### Changes to Code
1. Added `plot_hierarchical_heatmap_comparison()` function (~350 lines)
2. Added `create_comparison_example_data()` helper function
3. Enhanced subplot layout for multi-column comparisons
4. Implemented shared y-axis labels with independent colorbars

#### Files Added
- `COMPARISON_DOCS.md` - Complete documentation
- `COMPARISON_QUICK_REF.md` - Quick reference guide
- `test_comparison.py` - Test suite with 5 examples

#### Requirements
- All matrices must have identical index and columns
- Number of matrices must match number of CT labels
- Values should be normalized to [0, 1]

#### Backward Compatibility
✅ **Fully backward compatible** - Existing code using `plot_hierarchical_heatmap()` unchanged.

---

## Version 1.1 (2026-01-29)

### New Feature: Label Orientation Control

#### Added
- **`label_orientation`** parameter in `figure_kwargs` to control macro label display
  - `'vertical'` (default): Labels rotated 90° - traditional view
  - `'horizontal'`: Labels displayed horizontally - better for small traces

#### Why?
When `filter_zero_rows=True` removes many rows, some macro topics end up with only 1-3 visible rows. Vertical labels become hard to read in these compact traces. Horizontal labels solve this readability issue.

#### Usage

```python
# Horizontal labels (new feature)
fig = plot_hierarchical_heatmap(
    evolution_matrix=data,
    classification_df=taxonomy,
    title="Compact View",
    filter_zero_rows=True,
    figure_kwargs={
        'label_orientation': 'horizontal',  # NEW!
    }
)
```

#### Changes to Code
1. Added `'label_orientation': 'vertical'` to `DEFAULT_FIGURE_CONFIG`
2. Updated `StackedHeatmapBuilder.__init__` to validate orientation
3. Modified `_position_colorbars_and_labels()` to support both angles
4. Updated docstring with examples and parameter documentation

#### Files Modified
- `hierarchical_heatmap.py` - Core implementation

#### Files Added
- `LABEL_ORIENTATION.md` - Feature documentation
- `test_label_orientation.py` - Test script with examples

#### Backward Compatibility
✅ **Fully backward compatible** - Default is `'vertical'`, matching previous behavior.

---

## Version 1.0 (2026-01-29)

### Initial Release

#### Features
- Single-file hierarchical heatmap package
- Supports pre-normalized evolution matrices
- Hierarchical visualization (macro → meso → time)
- Natural sorting of labels
- Square cell sizing with auto-dimensions
- Macro filtering
- Zero-row filtering
- Customizable styling
- HTML export with Plotly
- Dash/Streamlit/Jupyter integration

#### Files Included
- `hierarchical_heatmap.py` - Main package
- `README.md` - Full documentation
- `SUMMARY.md` - Quick start guide
- `INSTALLATION.md` - Setup instructions
- `demo.py` - 7 demonstration scripts
- `usage_example.py` - Migration examples
- `requirements.txt` - Dependencies