maidr 1.5.0__tar.gz → 1.6.1__tar.gz

{maidr-1.5.0 → maidr-1.6.1}/CHANGELOG.md

@@ -1,6 +1,46 @@
 # CHANGELOG
 
 
+## v1.6.1 (2025-08-13)
+
+### Bug Fixes
+
+- Add new selector logic for candlestick plots
+  ([#231](https://github.com/xability/py-maidr/pull/231),
+  [`66cd73a`](https://github.com/xability/py-maidr/commit/66cd73adb04f77c0b83fd6e2d9cf757ee909bd69))
+
+### Continuous Integration
+
+- Remove virtualenv dependecny ([#228](https://github.com/xability/py-maidr/pull/228),
+  [`b8e1423`](https://github.com/xability/py-maidr/commit/b8e1423c2ecd073bd1037466f68577242872df6b))
+
+### Documentation
+
+- Update user manual to reflect all supported plot types with proper technical descriptions
+  ([#230](https://github.com/xability/py-maidr/pull/230),
+  [`bae1163`](https://github.com/xability/py-maidr/commit/bae116322cb580f5c528da2857a7ca3ec2a655a7))
+
+Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
+
+Co-authored-by: jooyoungseo <19754711+jooyoungseo@users.noreply.github.com>
+
+Co-authored-by: JooYoung Seo <jseo1005@illinois.edu>
+
+
+## v1.6.0 (2025-08-04)
+
+### Continuous Integration
+
+- Update uv.lock ([#227](https://github.com/xability/py-maidr/pull/227),
+  [`f162971`](https://github.com/xability/py-maidr/commit/f162971f4e2585e055de3c837ce9342b292cb378))
+
+### Features
+
+- Add WSL compatibility for opening HTML files
+  ([#224](https://github.com/xability/py-maidr/pull/224),
+  [`2f2a899`](https://github.com/xability/py-maidr/commit/2f2a899b1df4137db94aeb843099ee6f0df952f0))
+
+
 ## v1.5.0 (2025-08-04)
 
 ### Features

{maidr-1.5.0 → maidr-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.5.0
+Version: 1.6.1
 Summary: Multimodal Access and Interactive Data Representations
 Project-URL: Homepage, https://xability.github.io/py-maidr
 Project-URL: Repository, https://github.com/xability/py-maidr
@@ -28,7 +28,6 @@ Requires-Dist: htmltools>=0.5
 Requires-Dist: lxml>=5.1.0
 Requires-Dist: mplfinance>=0.12.10b0
 Requires-Dist: numpy>=1.26
-Requires-Dist: virtualenv<21,>=20.26.6
 Requires-Dist: wrapt<2,>=1.16.0
 Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.0.0; extra == 'jupyter'

{maidr-1.5.0 → maidr-1.6.1}/docs/examples.qmd

@@ -49,6 +49,33 @@ plt.ylabel("Body Mass (g)")
 maidr.show(bar_plot)  #<<
 ```
 
+
+### Count Plots
+
+```{python}
+#| warning: false
+#| fig-alt: Count plot showing frequency of categorical data
+
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+import maidr #<<
+
+# Load the Titanic dataset
+titanic = sns.load_dataset("titanic")
+
+# Create a count plot
+plt.figure(figsize=(6, 6))
+count_plot = sns.countplot(x="class", data=titanic, palette="viridis") #<<
+
+plt.title("Passenger Class Distribution on the Titanic")
+plt.xlabel("Passenger Class")
+plt.ylabel("Count")
+
+# plt.show()
+maidr.show(count_plot) #<<
+```
+
 #### Vertical Stacked Bar Plot
 
 ```{python}
@@ -163,6 +190,33 @@ plt.ylabel("Frequency")
 maidr.show(hist_plot) #<<
 ```
 
+### KDE (Kernel Density Estimation) Plots
+
+```{python}
+#| warning: false
+#| fig-alt: KDE plot showing probability density distribution
+
+import matplotlib.pyplot as plt
+import seaborn as sns
+import numpy as np
+
+import maidr #<<
+
+# Generate sample data
+np.random.seed(42)
+data = np.random.randn(500)
+
+# Create a KDE plot
+plt.figure(figsize=(6, 6))
+kde_plot = sns.kdeplot(data, fill=True, color="blue") #<<
+
+plt.title("KDE Plot of Random Data")
+plt.xlabel("Value")
+plt.ylabel("Density")
+
+# plt.show()
+maidr.show(kde_plot) #<<
+```
 
 ### Line Plots
 
@@ -270,8 +324,6 @@ maidr.show(heatmap) #<<
 
 ### Box Plot
 
-* **Note**: Visual highlight feature has not been implemented in the box plot yet.
-
 ```{python}
 #| fig-alt: Box plot of petal length by species from the Iris dataset
 
@@ -321,6 +373,40 @@ plt.ylabel("Sepal Width")
 maidr.show(scatter_plot) #<<
 ```
 
+### Regression Plots
+
+```{python}
+#| warning: false
+#| fig-alt: Regression plot with scatter points and fitted line
+
+import matplotlib.pyplot as plt
+import seaborn as sns
+import numpy as np
+
+import maidr #<<
+
+# Generate sample data
+np.random.seed(42)
+x = np.linspace(0, 10, 50)
+y = 2 * x + 1 + np.random.normal(0, 2, 50)
+
+# Create a regression plot
+plt.figure(figsize=(6, 6))
+reg_plot = sns.regplot(
+    x=x,
+    y=y,
+    scatter_kws={"s": 50, "alpha": 0.7},
+    line_kws={"color": "red", "lw": 2},
+) #<<
+
+plt.title("Regression Plot with Fitted Line")
+plt.xlabel("X values")
+plt.ylabel("Y values")
+
+# plt.show()
+maidr.show(reg_plot) #<<
+```
+
 ### Multi-Layered Plots
 
 ```{python}

{maidr-1.5.0 → maidr-1.6.1}/docs/index.qmd

@@ -40,7 +40,7 @@ The following summarizes the key features and design principles of Py maidr:
 
 7. Reproducibility: maidr supports the generation of accessible data visualizations as part of the reproducible data science workflow with [Quarto scientific publishing system](https://quarto.org/). You can easily create accessible data representations within your reproducible reports, website blogs, slides, e-books, dashboards, and more.
 
-8. Scalability: maidr supports a wide range of data visualization types, including bar plots, histograms, line plots, box plots, heatmaps, scatter plots, and more. maidr is designed to be extensible to support new visualization types. [Multi-figure and multi-layer visualizations are underway to support complex data visualizations.]
+8. Scalability: maidr supports a wide range of data visualization types, including bar plots, histograms, line plots, box plots, heatmaps, scatter plots, and more. maidr is designed to be extensible to support new visualization types. Multi-figure and multi-layer visualizations are also supported.
 
 Our core philosophy is to make data science accessible to everyone, regardless of their visual dis/abilities. We believe that by making data visualizations accessible, we can empower blind and sighted users to work together on data science projects, share insights, and make data-driven decisions collaboratively.
 
@@ -52,10 +52,18 @@ We currently support the following data visualization libraries in Python:, and
 
 * One-factor bar plot having one x (categorical) and one y (numerical/count) axis.
 
+* Stacked bar plot having one x (categorical) and one y (numerical/count) axis with multiple data series stacked vertically.
+
+* Dodged (grouped) bar plot having one x (categorical) and one y (numerical/count) axis with multiple data series displayed side-by-side.
+
 * One distribution histogram having one x (numerical) and y (numerical/frequency) axis.
 
+* KDE (Kernel Density Estimation) plot having one x (numerical) and one y (density) axis showing probability density curves.
+
 * Single line plot having one x (numerical) and one y (numerical) axis.
 
+* Multi-line plot having one x (numerical) and one y (numerical) axis with multiple data series on the same axes.
+
 * Vertical box plot having one x (categorical) and one y (numerical) axis.
 
 * Horizontal box plot having one x (numerical) and one y (categorical) axis.
@@ -66,15 +74,27 @@ We currently support the following data visualization libraries in Python:, and
 
 * Scatter plot having one x (numerical) and one y (numerical) axis.
 
+* Regression plot having one x (numerical) and one y (numerical) axis with scatter points and fitted regression line.
+
+* Candlestick chart having one x (time/date) and four y (numerical) axes (open, high, low, close) for financial data visualization (using mplfinance).
+
+* Multi-layered plots combining different plot types on the same figure with shared axes.
+
+* Multi-panel plots (subplots) with multiple charts in a grid layout having independent axes.
+
+* Facet plots showing the same chart type across different data subsets with shared axis scales.
+
 
 ### Seaborn
 
 * `sns.barplot()`: One-factor bar plot having one x (categorical) and one y (numerical/count) axis.
 
-    * Note: We also support `sns.countplot()`
+* `sns.countplot()`: Count plot having one x (categorical) and one y (count) axis showing the frequency of categorical data.
 
 * `sns.histplot()`: One distribution histogram having one x (numerical) and y (numerical/frequency) axis.
 
+* `sns.kdeplot()`: KDE (Kernel Density Estimation) plot having one x (numerical) and one y (density) axis showing probability density curves.
+
 * `sns.lineplot()`: Single line plot having one x (numerical) and one y (numerical) axis.
 
 * `sns.boxplot(..., orient="v")`: Vertical box plot having one x (categorical) and one y (numerical) axis.
@@ -87,6 +107,12 @@ We currently support the following data visualization libraries in Python:, and
 
 * `sns.scatterplot()`: Scatter plot having one x (numerical) and one y (numerical) axis.
 
+* `sns.regplot()`: Regression plot having one x (numerical) and one y (numerical) axis with scatter points and fitted regression line.
+
+### Additional Libraries
+
+* **mplfinance**: Candlestick charts having one x (time/date) and four y (numerical) axes (open, high, low, close) for financial data with support for moving averages and volume data.
+
 
 ## Installation
 

{maidr-1.5.0 → maidr-1.6.1}/maidr/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.5.0"
+__version__ = "1.6.1"
 
 from .api import close, render, save_html, show, stacked
 from .core import Maidr

{maidr-1.5.0 → maidr-1.6.1}/maidr/core/maidr.py

@@ -7,6 +7,8 @@ import os
 import tempfile
 import uuid
 import webbrowser
+import subprocess
+from pathlib import Path
 from typing import Any, Literal, cast
 
 import matplotlib.pyplot as plt
@@ -137,7 +139,48 @@ class Maidr:
         html_file_path = self.save_html(
             temp_file_path
         )  # This will use use_iframe=False
-        webbrowser.open(f"file://{html_file_path}")
+        if Environment.is_wsl():
+            wsl_distro_name = Environment.get_wsl_distro_name()
+
+            # Validate that WSL distro name is available
+            if not wsl_distro_name:
+                raise ValueError(
+                    "WSL_DISTRO_NAME environment variable is not set or is empty. "
+                    "Cannot construct WSL file URL. Please ensure you are running in a WSL environment."
+                )
+
+            # Ensure html_file_path is an absolute POSIX path for proper WSL URL construction
+            html_file_path = Path(html_file_path).resolve().as_posix()
+
+            url = f"file://wsl$/{wsl_distro_name}{html_file_path}"
+
+            # Try to open the file in Windows using explorer.exe with robust path detection
+            explorer_path = Environment.find_explorer_path()
+            if explorer_path:
+                try:
+                    result = subprocess.run(
+                        [explorer_path, url],
+                        capture_output=True,
+                        text=True,
+                        timeout=10
+                    )
+
+                    if result.returncode == 0:
+                        return
+                    else:
+                        # Fall back to webbrowser.open() if explorer.exe fails
+                        webbrowser.open(url)
+
+                except subprocess.TimeoutExpired:
+                    webbrowser.open(url)
+                except Exception:
+                    # Fall back to webbrowser.open() if explorer.exe fails
+                    webbrowser.open(url)
+            else:
+                webbrowser.open(url)
+
+        else:
+            webbrowser.open(f"file://{html_file_path}")
 
     def _create_html_tag(self, use_iframe: bool = True) -> Tag:
         """Create the MAIDR HTML using HTML tags."""

maidr-1.6.1/maidr/core/plot/candlestick.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import uuid
+from typing import Union, Dict
+from matplotlib.axes import Axes
+from matplotlib.patches import Rectangle
+import numpy as np
+
+from maidr.core.enum import PlotType
+from maidr.core.plot import MaidrPlot
+from maidr.core.enum.maidr_key import MaidrKey
+from maidr.exception import ExtractionError
+from maidr.util.mplfinance_utils import MplfinanceDataExtractor
+
+
+class CandlestickPlot(MaidrPlot):
+    """
+    Specialized candlestick plot class for mplfinance OHLC data.
+
+    This class handles the extraction and processing of candlestick data from mplfinance
+    plots, including proper date conversion and data validation.
+    """
+
+    def __init__(self, axes: list[Axes], **kwargs) -> None:
+        """
+        Initialize the CandlestickPlot.
+
+        Parameters
+        ----------
+        axes : list[Axes]
+            A list of Matplotlib Axes objects. Expected to contain at least
+            one Axes for OHLC data, and optionally a second for volume data.
+        **kwargs : dict
+            Additional keyword arguments.
+        """
+        self.axes = axes
+        # Ensure there's at least one axis for the superclass init
+        if not axes:
+            raise ValueError("Axes list cannot be empty.")
+        super().__init__(axes[0], PlotType.CANDLESTICK)
+
+        # Store custom collections passed from mplfinance patch
+        self._maidr_wick_collection = kwargs.get("_maidr_wick_collection", None)
+        self._maidr_body_collection = kwargs.get("_maidr_body_collection", None)
+        self._maidr_date_nums = kwargs.get("_maidr_date_nums", None)
+        self._maidr_original_data = kwargs.get("_maidr_original_data", None)  # Store original data
+
+        # Store the GID for proper selector generation (legacy/shared)
+        self._maidr_gid = None
+        # Modern-path separate gids for body and wick
+        self._maidr_body_gid = None
+        self._maidr_wick_gid = None
+        if self._maidr_body_collection:
+            self._maidr_gid = self._maidr_body_collection.get_gid()
+            self._maidr_body_gid = self._maidr_gid
+        elif self._maidr_wick_collection:
+            self._maidr_gid = self._maidr_wick_collection.get_gid()
+            self._maidr_wick_gid = self._maidr_gid
+
+    def _extract_plot_data(self) -> list[dict]:
+        """
+        Extract candlestick data from the plot.
+
+        This method processes candlestick plots from both modern (mplfinance.plot) and
+        legacy (original_flavor) pipelines, extracting OHLC data and setting up
+        highlighting elements and GIDs.
+
+        Returns
+        -------
+        list[dict]
+            List of dictionaries containing candlestick data with keys:
+            - 'value': Date string
+            - 'open': Opening price (float)
+            - 'high': High price (float)
+            - 'low': Low price (float)
+            - 'close': Closing price (float)
+            - 'volume': Volume (float, typically 0 for candlestick-only plots)
+        """
+
+        # Get the custom collections from kwargs
+        body_collection = self._maidr_body_collection
+        wick_collection = self._maidr_wick_collection
+
+        if body_collection and wick_collection:
+            # Store the GIDs from the collections (modern path)
+            self._maidr_body_gid = body_collection.get_gid()
+            self._maidr_wick_gid = wick_collection.get_gid()
+            # Keep legacy gid filled for backward compatibility
+            self._maidr_gid = self._maidr_body_gid or self._maidr_wick_gid
+
+            # Use the original collections for highlighting
+            self._elements = [body_collection, wick_collection]
+
+            # Use the utility class to extract data
+            data = MplfinanceDataExtractor.extract_candlestick_data(
+                body_collection, wick_collection, self._maidr_date_nums, self._maidr_original_data
+            )
+            return data
+
+        # Fallback to original detection method
+        if not self.axes:
+            return []
+
+        ax_ohlc = self.axes[0]
+
+        # Look for Rectangle patches (original_flavor candlestick)
+        body_rectangles = []
+        for patch in ax_ohlc.patches:
+            if isinstance(patch, Rectangle):
+                body_rectangles.append(patch)
+
+        if body_rectangles:
+            # Set elements for highlighting
+            self._elements = body_rectangles
+
+            # Generate a GID for highlighting if none exists
+            if not self._maidr_gid:
+                self._maidr_gid = f"maidr-{uuid.uuid4()}"
+                # Set GID on all rectangles
+                for rect in body_rectangles:
+                    rect.set_gid(self._maidr_gid)
+            # Keep a dedicated body gid for legacy dict selectors
+            self._maidr_body_gid = getattr(self, "_maidr_body_gid", None) or self._maidr_gid
+
+            # Assign a shared gid to wick Line2D (vertical 2-point lines) on the same axis
+            wick_lines = []
+            for line in ax_ohlc.get_lines():
+                try:
+                    xydata = line.get_xydata()
+                    if xydata is None:
+                        continue
+                    xy_arr = np.asarray(xydata)
+                    if xy_arr.ndim == 2 and xy_arr.shape[0] == 2 and xy_arr.shape[1] >= 2:
+                        x0 = float(xy_arr[0, 0])
+                        x1 = float(xy_arr[1, 0])
+                        if abs(x0 - x1) < 1e-10:
+                            wick_lines.append(line)
+                except Exception:
+                    continue
+            if wick_lines:
+                if not getattr(self, "_maidr_wick_gid", None):
+                    self._maidr_wick_gid = f"maidr-{uuid.uuid4()}"
+                for line in wick_lines:
+                    line.set_gid(self._maidr_wick_gid)
+
+            # Use the utility class to extract data
+            data = MplfinanceDataExtractor.extract_rectangle_candlestick_data(
+                body_rectangles, self._maidr_date_nums, self._maidr_original_data
+            )
+            return data
+
+        return []
+
+    def _extract_axes_data(self) -> dict:
+        """
+        Extract the plot's axes data including labels.
+
+        Returns
+        -------
+        dict
+            Dictionary containing x and y axis labels.
+        """
+        x_labels = self.ax.get_xlabel()
+        if not x_labels:
+            x_labels = self.extract_shared_xlabel(self.ax)
+        if not x_labels:
+            x_labels = "X"
+        return {MaidrKey.X: x_labels, MaidrKey.Y: self.ax.get_ylabel()}
+
+    def _get_selector(self) -> Union[str, Dict[str, str]]:
+        """Return selectors for highlighting candlestick elements.
+
+        - Modern path (collections present): return a dict with separate selectors for body, wickLow, wickHigh
+        - Legacy path: return a dict with body and shared wick selectors (no open/close keys)
+        """
+        # Modern path: build structured selectors using separate gids
+        if self._maidr_body_collection and self._maidr_wick_collection and self._maidr_body_gid and self._maidr_wick_gid:
+            # Determine candle count N
+            N = None
+            if self._maidr_original_data is not None:
+                try:
+                    N = len(self._maidr_original_data)
+                except Exception:
+                    N = None
+            if N is None and hasattr(self._maidr_wick_collection, "get_paths"):
+                try:
+                    wick_paths = len(list(self._maidr_wick_collection.get_paths()))
+                    if wick_paths % 2 == 0 and wick_paths > 0:
+                        N = wick_paths // 2
+                except Exception:
+                    pass
+            if N is None and hasattr(self._maidr_body_collection, "get_paths"):
+                try:
+                    body_paths = len(list(self._maidr_body_collection.get_paths()))
+                    if body_paths > 0:
+                        N = body_paths
+                except Exception:
+                    pass
+            if N is None:
+                raise ExtractionError(PlotType.CANDLESTICK, self._maidr_wick_collection)
+
+            selectors = {
+                "body": f"g[id='{self._maidr_body_gid}'] > path",
+                "wickLow": f"g[id='{self._maidr_wick_gid}'] > path:nth-child(-n+{N})",
+                "wickHigh": f"g[id='{self._maidr_wick_gid}'] > path:nth-child(n+{N + 1})",
+            }
+            return selectors
+
+        # Legacy path: build shared-id selectors; omit open/close
+        legacy_selectors = {}
+        if getattr(self, "_maidr_body_gid", None) or self._maidr_gid:
+            body_gid = getattr(self, "_maidr_body_gid", None) or self._maidr_gid
+            legacy_selectors["body"] = f"g[id='{body_gid}'] > path"
+        if getattr(self, "_maidr_wick_gid", None):
+            legacy_selectors["wick"] = f"g[id='{self._maidr_wick_gid}'] > path"
+        if legacy_selectors:
+            return legacy_selectors
+
+        # Fallback
+        return "g[maidr='true'] > path, g[maidr='true'] > rect"
+
+    def render(self) -> dict:
+        """Initialize the MAIDR schema dictionary with basic plot information."""
+        base_schema = super().render()
+        base_schema[MaidrKey.TITLE] = "Candlestick Chart"
+        base_schema[MaidrKey.AXES] = self._extract_axes_data()
+        base_schema[MaidrKey.DATA] = self._extract_plot_data()
+        # Include selector only if the plot supports highlighting.
+        if self._support_highlighting:
+            base_schema[MaidrKey.SELECTOR] = self._get_selector()
+        return base_schema

{maidr-1.5.0 → maidr-1.6.1}/maidr/patch/candlestick.py

@@ -2,6 +2,7 @@ import wrapt
 from typing import Any, Callable, Dict, Tuple
 from matplotlib.patches import Rectangle
 from mplfinance import original_flavor
+import numpy as np
 
 from maidr.core.context_manager import ContextManager
 from maidr.core.enum.plot_type import PlotType
@@ -46,10 +47,35 @@ def candlestick(
         # Patch the plotting function.
         plot = wrapped(*args, **kwargs)
 
+    original_data = None
+    date_nums = None
+    if len(args) >= 2:
+        try:
+            quotes = args[1]
+            if quotes is not None:
+                arr = np.asarray(quotes)
+                if arr.ndim == 2 and arr.shape[1] >= 5 and arr.size > 0:
+                    date_nums = arr[:, 0].tolist()
+                    original_data = {
+                        "Open": arr[:, 1].tolist(),
+                        "High": arr[:, 2].tolist(),
+                        "Low": arr[:, 3].tolist(),
+                        "Close": arr[:, 4].tolist(),
+                    }
+        except Exception:
+            pass
+
     axes = []
     for ax in plot:
         axes.append(FigureManager.get_axes(ax))
-    FigureManager.create_maidr(axes, PlotType.CANDLESTICK)
+
+    extra_kwargs: Dict[str, Any] = {}
+    if original_data is not None:
+        extra_kwargs["_maidr_original_data"] = original_data
+    if date_nums is not None:
+        extra_kwargs["_maidr_date_nums"] = date_nums
+
+    FigureManager.create_maidr(axes, PlotType.CANDLESTICK, **extra_kwargs)
 
     return plot
 

{maidr-1.5.0 → maidr-1.6.1}/maidr/patch/mplfinance.py

@@ -83,9 +83,10 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
         )
 
         if wick_collection and body_collection:
-            gid = f"maidr-{uuid.uuid4()}"
-            wick_collection.set_gid(gid)
-            body_collection.set_gid(gid)
+            wick_gid = f"maidr-{uuid.uuid4()}"
+            body_gid = f"maidr-{uuid.uuid4()}"
+            wick_collection.set_gid(wick_gid)
+            body_collection.set_gid(body_gid)
 
             candlestick_kwargs = dict(
                 kwargs,
@@ -93,6 +94,8 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
                 _maidr_body_collection=body_collection,
                 _maidr_date_nums=date_nums,
                 _maidr_original_data=data,
+                _maidr_wick_gid=wick_gid,
+                _maidr_body_gid=body_gid,
             )
             common(
                 PlotType.CANDLESTICK,