updated docs and tests

Author: bbcho

CLAUDE.md

@@ -42,15 +42,15 @@ ggplotly/
 │   ├── ggplot.py       # Core ggplot class
 │   ├── aes.py          # Aesthetic mappings
 │   ├── layer.py        # Layer abstraction
-│   ├── geoms/          # 44+ geometric objects
+│   ├── geoms/          # 46 geometric objects
 │   ├── stats/          # 13 statistical transformations
-│   ├── scales/         # 17+ scales
-│   ├── coords/         # Coordinate systems
+│   ├── scales/         # 19 scales
+│   ├── coords/         # 5 coordinate systems
 │   ├── themes.py       # 9 built-in themes
 │   ├── facets.py       # facet_wrap, facet_grid
-│   └── data/           # Built-in datasets (CSV)
+│   └── data/           # 16 built-in datasets (CSV)
 ├── pytest/             # Test suite (39 files)
-├── examples/           # Jupyter notebooks (43)
+├── examples/           # Jupyter notebooks
 └── docs/               # MkDocs documentation
 ```
 
@@ -107,11 +107,11 @@ Optional:
 
 | Component | Count | Location |
 |-----------|-------|----------|
-| Geoms | 44+ | `ggplotly/geoms/` |
+| Geoms | 46 | `ggplotly/geoms/` |
 | Stats | 13 | `ggplotly/stats/` |
-| Scales | 17+ | `ggplotly/scales/` |
+| Scales | 19 | `ggplotly/scales/` |
 | Themes | 9 | `ggplotly/themes.py` |
-| Coords | 4 | `ggplotly/coords/` |
+| Coords | 5 | `ggplotly/coords/` |
 | Datasets | 16 | `ggplotly/data/` |
 
 ## Testing Patterns
@@ -254,6 +254,7 @@ aes(y=after_stat('count / count.sum()'))  # Proportions
 |------|----------|
 | `geom_point()` | Scatter plots |
 | `geom_line()` | Line charts |
+| `geom_path()` | Connect points in data order |
 | `geom_bar()` | Bar charts (stat='count' default) |
 | `geom_col()` | Bar charts (stat='identity') |
 | `geom_histogram()` | Histograms |
@@ -262,20 +263,38 @@ aes(y=after_stat('count / count.sum()'))  # Proportions
 | `geom_density()` | Density curves |
 | `geom_smooth()` | Trend lines with CI |
 | `geom_area()` | Area charts |
+| `geom_ribbon()` | Confidence bands (ymin/ymax) |
 | `geom_tile()` | Heatmaps |
+| `geom_rect()` | Rectangles (highlight regions) |
 | `geom_text()` | Text labels |
+| `geom_label()` | Text with background |
 | `geom_errorbar()` | Error bars |
+| `geom_segment()` | Line segments (with optional arrows) |
 | `geom_vline()`, `geom_hline()` | Reference lines |
+| `geom_abline()` | Slope/intercept lines |
+| `geom_jitter()` | Jittered points |
+| `geom_rug()` | Marginal tick marks |
+| `geom_qq()`, `geom_qq_line()` | Q-Q plots |
+| `geom_contour()` | Contour lines |
 | `geom_candlestick()` | Financial OHLC |
+| `geom_waterfall()` | Waterfall charts |
 | `geom_map()` | Choropleth maps |
 
 ## Built-in Datasets
 
 ```python
-from ggplotly import diamonds, mpg, iris, mtcars, economics, msleep, faithfuld
+from ggplotly import data
+
+# List all datasets
+data()
+
+# Load a specific dataset
+mpg = data('mpg')
+diamonds = data('diamonds')
+iris = data('iris')
 ```
 
-Available: diamonds, mpg, iris, mtcars, economics, msleep, faithfuld, seals, txhousing, midwest, and more in `ggplotly/data/`
+Available: diamonds, mpg, iris, mtcars, economics, economics_long, msleep, faithfuld, seals, txhousing, midwest, presidential, commodity_prices, luv_colours, us_flights (network data)
 
 ## Themes
 
@@ -285,9 +304,9 @@ theme_minimal()    # Clean, minimal
 theme_classic()    # Classic ggplot2 style
 theme_dark()       # Dark background
 theme_ggplot2()    # R ggplot2 style
-theme_bw()         # Black and white
 theme_nytimes()    # NYT style
 theme_bbc()        # BBC News style
+theme_custom()     # Custom theme builder
 ```
 
 ## Position Adjustments
@@ -304,6 +323,7 @@ position_nudge()   # Shift by fixed amount
 
 ```python
 coord_cartesian(xlim=(0, 10))  # Zoom without clipping data
+coord_fixed(ratio=1)           # Fixed aspect ratio (1:1 scaling)
 coord_flip()                    # Swap x and y axes
 coord_polar()                   # Polar coordinates (pie charts)
 coord_sf()                      # Geographic projections
@@ -340,6 +360,9 @@ facet_wrap('category', scales='free')  # 'free_x', 'free_y'
 ```python
 # Axis transforms
 scale_x_log10()                    # Log scale
+scale_y_log10()                    # Log scale (y-axis)
+scale_x_reverse()                  # Reversed x-axis
+scale_y_reverse()                  # Reversed y-axis
 scale_x_continuous(limits=(0,100)) # Set range
 scale_x_date(date_labels='%Y-%m')  # Date formatting
 
@@ -369,11 +392,14 @@ scale_x_rangeselector()            # Add range buttons
 | `stat_bin` | Bin data | `geom_histogram` |
 | `stat_density` | Kernel density | `geom_density` |
 | `stat_smooth` | Smoothed line + CI | `geom_smooth` |
-| `stat_boxplot` | Boxplot stats | `geom_boxplot` |
 | `stat_ecdf` | Empirical CDF | - |
 | `stat_summary` | Summary statistics | - |
 | `stat_function` | Apply function | - |
 | `stat_qq` | Q-Q plot points | `geom_qq` |
+| `stat_qq_line` | Q-Q reference line | `geom_qq_line` |
+| `stat_contour` | Contour computation | `geom_contour` |
+| `stat_stl` | STL decomposition | `geom_stl` |
+| `stat_fanchart` | Fan chart percentiles | `geom_fanchart` |
 
 ## Specialized Features
 
@@ -405,6 +431,42 @@ geom_edgebundle()  # Edge bundling
 geom_sankey()      # Sankey diagrams
 ```
 
+### Time Series Analysis
+```python
+geom_stl()         # STL decomposition (trend, seasonal, residual)
+geom_acf()         # Autocorrelation function
+geom_pacf()        # Partial autocorrelation function
+geom_fanchart()    # Fan charts for uncertainty
+geom_range()       # Historical range plots (5-year range)
+```
+
+### Recent Feature Additions
+
+#### New Geoms
+- `geom_rect` - Draw rectangles (highlight regions, backgrounds)
+- `geom_label` - Text labels with background boxes
+
+#### New Scales
+```python
+scale_x_reverse()  # Reversed x-axis
+scale_y_reverse()  # Reversed y-axis
+```
+
+#### New Parameters
+| Geom | Parameter | Description |
+|------|-----------|-------------|
+| `geom_point` | `stroke` | Marker border width |
+| `geom_segment` | `arrow`, `arrow_size` | Add arrows to segments |
+| `geom_errorbar` | `width` | Error bar cap width |
+| `geom_text` | `parse` | Enable LaTeX/MathJax rendering |
+| `geom_col` | `width` | Bar width control |
+| `geom_smooth` | `fullrange` | Extend line to full x-axis |
+| `geom_area` | `position` | Stacking support |
+
+#### Parameter Aliases (ggplot2 compatibility)
+- `linewidth` → `size` (ggplot2 3.4+)
+- `colour` → `color` (British spelling)
+
 ## Adding New Features
 
 ### New Geom

ROADMAP.md

@@ -102,20 +102,29 @@
 
 | Item | Type | Description | Status |
 |------|------|-------------|--------|
+| `geom_pointrange` | Geom | Point with error bars | TODO |
+| `geom_linerange` | Geom | Vertical line ranges | TODO |
+| `geom_raster` | Geom | High-performance rectangular tiles | TODO |
 | `geom_polygon` | Geom | Arbitrary polygons | TODO |
 | `geom_dotplot` | Geom | Dot plots | TODO |
 | `geom_freqpoly` | Geom | Frequency polygons | TODO |
 | `geom_spoke` | Geom | Line segments by angle | TODO |
 | `geom_curve` | Geom | Curved line segments | TODO |
+| `stat_spoke` | Stat | Spoke statistics | TODO |
+| `stat_bin_2d` | Stat | 2D binning | TODO |
+| `stat_boxplot` | Stat | Boxplot statistics | TODO |
+| `stat_unique` | Stat | Remove duplicates | TODO |
 | `scale_alpha` | Scale | Alpha/transparency scaling | TODO |
 | `scale_linetype` | Scale | Linetype scaling | TODO |
 | `scale_x_sqrt` | Scale | Square root x-axis | TODO |
 | `scale_y_sqrt` | Scale | Square root y-axis | TODO |
 | `scale_color_viridis_c` | Scale | Viridis for color aesthetic | TODO |
+| `scale_fill_viridis_d` | Scale | Viridis discrete for fill | TODO |
 | `scale_color_distiller` | Scale | ColorBrewer continuous for color | TODO |
+| `theme_bw` | Theme | Black and white theme | TODO |
+| `theme_void` | Theme | Empty theme | TODO |
+| `xlab` / `ylab` | Label | Axis label shortcuts | TODO |
 | `coord_trans` | Coord | Transformed coordinates | TODO |
-| `stat_boxplot` | Stat | Boxplot statistics | TODO |
-| `stat_unique` | Stat | Remove duplicates | TODO |
 
 ---
 
@@ -149,27 +158,29 @@
 
 ## Completed Features
 
-### Geoms (46+)
-- Basic: `geom_point`, `geom_line`, `geom_path`, `geom_bar`, `geom_col`, `geom_area`, `geom_ribbon`
-- Distribution: `geom_histogram`, `geom_density`, `geom_boxplot`, `geom_violin`, `geom_qq`
-- Statistical: `geom_smooth`, `geom_errorbar`, `geom_pointrange`, `geom_linerange`
+### Geoms (46)
+- Basic: `geom_point`, `geom_line`, `geom_lines`, `geom_path`, `geom_bar`, `geom_col`, `geom_area`, `geom_ribbon`
+- Distribution: `geom_histogram`, `geom_density`, `geom_boxplot`, `geom_violin`, `geom_qq`, `geom_qq_line`, `geom_norm`
+- Statistical: `geom_smooth`, `geom_errorbar`
 - Annotation: `geom_text`, `geom_label`, `geom_rect`, `geom_hline`, `geom_vline`, `geom_abline`, `geom_segment`
-- Specialized: `geom_tile`, `geom_raster`, `geom_contour`, `geom_contour_filled`
-- Financial: `geom_candlestick`, `geom_ohlc`, `geom_waterfall`
+- Specialized: `geom_tile`, `geom_contour`, `geom_contour_filled`
+- Financial: `geom_candlestick`, `geom_ohlc`, `geom_waterfall`, `geom_fanchart`
+- Time Series: `geom_stl`, `geom_acf`, `geom_pacf`, `geom_range`
 - 3D: `geom_point_3d`, `geom_surface`, `geom_wireframe`
 - Geographic: `geom_map`, `geom_sf`, `geom_searoute`
 - Network: `geom_edgebundle`, `geom_sankey`
-- Other: `geom_step`, `geom_jitter`, `geom_rug`, `geom_range`
+- Other: `geom_step`, `geom_jitter`, `geom_rug`
 
 ### Stats (13)
-`stat_identity`, `stat_count`, `stat_bin`, `stat_density`, `stat_smooth`, `stat_summary`, `stat_ecdf`, `stat_function`, `stat_qq`, `stat_stl`, `stat_spoke`, `stat_bin_2d`, `stat_contour`
+`stat_identity`, `stat_count`, `stat_bin`, `stat_density`, `stat_smooth`, `stat_summary`, `stat_ecdf`, `stat_function`, `stat_qq`, `stat_qq_line`, `stat_stl`, `stat_fanchart`, `stat_contour`
 
-### Scales (19+)
+### Scales (19)
 - Continuous: `scale_x_continuous`, `scale_y_continuous`, `scale_x_log10`, `scale_y_log10`
 - Reversed: `scale_x_reverse`, `scale_y_reverse`
 - Date/Time: `scale_x_date`, `scale_x_datetime`
-- Color: `scale_color_manual`, `scale_color_gradient`, `scale_color_brewer`, `scale_fill_*` variants
-- Viridis: `scale_fill_viridis_c`, `scale_fill_viridis_d`
+- Color: `scale_color_manual`, `scale_color_gradient`, `scale_color_brewer`
+- Fill: `scale_fill_manual`, `scale_fill_gradient`, `scale_fill_brewer`, `scale_fill_viridis_c`
+- Other: `scale_shape_manual`, `scale_size`
 - Interactive: `scale_x_rangeslider`, `scale_x_rangeselector`
 
 ### Coords (5)
@@ -179,14 +190,15 @@
 `position_identity`, `position_dodge`, `position_dodge2`, `position_stack`, `position_fill`, `position_jitter`, `position_nudge`
 
 ### Themes (9)
-`theme_default`, `theme_minimal`, `theme_classic`, `theme_dark`, `theme_ggplot2`, `theme_bw`, `theme_void`, `theme_bbc`, `theme_nytimes`
+`theme_default`, `theme_minimal`, `theme_classic`, `theme_dark`, `theme_ggplot2`, `theme_bbc`, `theme_nytimes`, `theme_custom`, `theme`
 
 ### Other
-- Faceting: `facet_wrap`, `facet_grid` with labellers
+- Faceting: `facet_wrap`, `facet_grid` with labellers (`label_both`, `label_value`)
 - Guides: `guides`, `guide_legend`, `guide_colorbar`
-- Labels: `labs`, `ggtitle`, `xlab`, `ylab`
-- Utilities: `ggsave`, `ggsize`, `annotate`
-- 16 built-in datasets
+- Labels: `labs`, `ggtitle`, `annotate`
+- Limits: `xlim`, `ylim`, `lims`
+- Utilities: `ggsave`, `ggsize`
+- Data: `data` (16 built-in datasets), `map_data`, `aes`, `after_stat`, `layer`
 
 ---
 

docs/gallery/basic.ipynb

@@ -573,6 +573,104 @@
    "metadata": {},
    "outputs": [],
    "source": "df = pd.DataFrame({'x': np.random.randn(100), 'y': np.random.randn(100)})\n\n(ggplot(df, aes(x='x', y='y'))\n + geom_point(alpha=0.5)\n + geom_rug(sides='bl', alpha=0.3)\n + labs(title='Scatter with Marginal Rugs'))"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "uh0z6ntbh6",
+   "source": "## Point Borders (stroke)\n\nAdd borders to points with the `stroke` parameter:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "xarrrstguxr",
+   "source": "df = pd.DataFrame({\n    'x': [1, 2, 3, 4, 5],\n    'y': [2, 4, 3, 5, 4],\n    'category': ['A', 'B', 'A', 'B', 'A']\n})\n\n# Points with colored borders\n(ggplot(df, aes(x='x', y='y', color='category'))\n + geom_point(size=15, stroke=2)\n + labs(title='Points with Borders (stroke=2)'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "yutsck4pyx",
+   "source": "## Rectangles (geom_rect)\n\nHighlight regions with rectangles:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "039wi1wceyx3",
+   "source": "# Data for scatter plot\nscatter_df = pd.DataFrame({\n    'x': np.random.randn(100),\n    'y': np.random.randn(100)\n})\n\n# Rectangle to highlight a region\nrect_df = pd.DataFrame({\n    'xmin': [-1], 'xmax': [1],\n    'ymin': [-1], 'ymax': [1]\n})\n\n(ggplot(scatter_df, aes(x='x', y='y'))\n + geom_rect(data=rect_df, mapping=aes(xmin='xmin', xmax='xmax', ymin='ymin', ymax='ymax'),\n             fill='yellow', alpha=0.3)\n + geom_point(alpha=0.6)\n + labs(title='Scatter with Highlighted Region'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4r48c8bsylr",
+   "source": "## Labels with Background (geom_label)\n\nText labels with a background box for better readability:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "26pg8mh4j6u",
+   "source": "df = pd.DataFrame({\n    'x': [1, 2, 3, 4],\n    'y': [2, 4, 3, 5],\n    'label': ['Alpha', 'Beta', 'Gamma', 'Delta']\n})\n\n(ggplot(df, aes(x='x', y='y'))\n + geom_point(size=10, color='steelblue')\n + geom_label(aes(label='label'), fill='white', alpha=0.8)\n + labs(title='Points with Background Labels'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "j63h040isd",
+   "source": "## Segments with Arrows\n\nAdd arrows to line segments:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bo5o2bppuri",
+   "source": "df = pd.DataFrame({\n    'x': [1, 2, 3],\n    'y': [1, 2, 1],\n    'xend': [2, 3, 4],\n    'yend': [2, 1, 2]\n})\n\n(ggplot(df, aes(x='x', y='y', xend='xend', yend='yend'))\n + geom_segment(arrow=True, arrow_size=15, color='steelblue', size=2)\n + labs(title='Segments with Arrows'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ghbwtfx9hh7",
+   "source": "## Fixed Aspect Ratio (coord_fixed)\n\nEnsure equal scaling on both axes:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "24b4cl86b18",
+   "source": "# Circle should appear as a circle, not an ellipse\ntheta = np.linspace(0, 2*np.pi, 100)\ncircle = pd.DataFrame({\n    'x': np.cos(theta),\n    'y': np.sin(theta)\n})\n\n(ggplot(circle, aes(x='x', y='y'))\n + geom_path(size=2)\n + coord_fixed(ratio=1)\n + labs(title='Circle with coord_fixed(ratio=1)'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "xu783fl74ge",
+   "source": "## Reversed Axes\n\nFlip axis direction with `scale_x_reverse()` or `scale_y_reverse()`:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "998i04rrr5n",
+   "source": "df = pd.DataFrame({'x': range(1, 6), 'y': [2, 4, 3, 5, 4]})\n\n# Reversed y-axis (useful for rankings, depth charts)\n(ggplot(df, aes(x='x', y='y'))\n + geom_line(size=2)\n + geom_point(size=10)\n + scale_y_reverse()\n + labs(title='Reversed Y-Axis', y='Rank (1 = best)'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "muf3lcw2nz",
+   "source": "## LaTeX Labels (parse)\n\nRender mathematical notation with `parse=True`:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "2bkjxs2t6v5",
+   "source": "df = pd.DataFrame({\n    'x': [1, 2, 3],\n    'y': [1, 4, 9],\n    'label': [r'$x^2$', r'$\\sqrt{x}$', r'$\\frac{1}{x}$']\n})\n\n(ggplot(df, aes(x='x', y='y'))\n + geom_point(size=15)\n + geom_text(aes(label='label'), parse=True, vjust=-1.5, size=14)\n + labs(title='Mathematical Labels with LaTeX'))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
   }
  ],
  "metadata": {