maidr 1.4.0__tar.gz → 1.4.2__tar.gz

{maidr-1.4.0 → maidr-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: maidr
-Version: 1.4.0
+Version: 1.4.2
 Summary: Multimodal Access and Interactive Data Representations
 License: GPL-3.0-or-later
 Keywords: accessibility,visualization,sonification,braille,tactile,multimodal,data representation,blind,low vision,visual impairments

{maidr-1.4.0 → maidr-1.4.2}/maidr/__init__.py

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

{maidr-1.4.0 → maidr-1.4.2}/maidr/core/enum/smooth_keywords.py

@@ -2,8 +2,11 @@
 SMOOTH_KEYWORDS = [
     "smooth",
     "lowess",
+    "loess",
     "regression",
     "linear regression",
+    "linear fit",
+    "fit",
     "kde",
     "density",
     "gaussian",

{maidr-1.4.0 → maidr-1.4.2}/maidr/core/maidr.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 from datetime import datetime
+import urllib.request
+import urllib.error
+import json
 
 import io
 import json
@@ -22,6 +25,11 @@ from maidr.core.plot import MaidrPlot
 from maidr.util.environment import Environment
 from maidr.util.dedup_utils import deduplicate_smooth_and_line
 
+# Module-level cache for version to avoid repeated API calls
+_MAIDR_VERSION_CACHE: str | None = None
+_MAIDR_VERSION_CACHE_TIME: float = 0.0
+_MAIDR_CACHE_DURATION = 3600  # Cache for 1 hour
+
 
 class Maidr:
     """
@@ -34,6 +42,8 @@ class Maidr:
         The matplotlib figure associated with this instance.
     _plots : list[MaidrPlot]
         A list of MaidrPlot objects which hold additional plot-specific configurations.
+    _cached_version : str | None
+        Cached version of maidr from npm registry to avoid repeated API calls.
 
     Methods
     -------
@@ -271,20 +281,77 @@ class Maidr:
         """Generate a unique identifier string using UUID4."""
         return str(uuid.uuid4())
 
+    @staticmethod
+    def _get_latest_maidr_version() -> str:
+        """
+        Query the npm registry API to get the latest version of maidr with caching.
+
+        Returns
+        -------
+        str
+            The latest version of maidr from npm registry, or 'latest' as fallback.
+        """
+        import time
+
+        global _MAIDR_VERSION_CACHE, _MAIDR_VERSION_CACHE_TIME
+
+        # Check if version fetching is disabled via environment variable
+        if os.getenv("MAIDR_DISABLE_VERSION_FETCH", "").lower() in ("true", "1", "yes"):
+            return "latest"
+
+        current_time = time.time()
+
+        # Check if we have a valid cached version
+        if (
+            _MAIDR_VERSION_CACHE is not None
+            and current_time - _MAIDR_VERSION_CACHE_TIME < _MAIDR_CACHE_DURATION
+        ):
+            return _MAIDR_VERSION_CACHE
+
+        try:
+            # Query npm registry API for maidr package
+            with urllib.request.urlopen(
+                "https://registry.npmjs.org/maidr/latest", timeout=5  # 5 second timeout
+            ) as response:
+                if response.status == 200:
+                    data = json.loads(response.read().decode("utf-8"))
+                    version = data.get("version", "latest")
+
+                    # Cache the successful result
+                    _MAIDR_VERSION_CACHE = version
+                    _MAIDR_VERSION_CACHE_TIME = current_time
+
+                    return version
+
+        except Exception:
+            # Any error - just use latest
+            pass
+
+        # Fallback to 'latest' if API call fails
+        return "latest"
+
+    @staticmethod
+    def clear_version_cache() -> None:
+        """Clear the cached version to force a fresh API call on next request."""
+        global _MAIDR_VERSION_CACHE, _MAIDR_VERSION_CACHE_TIME
+        _MAIDR_VERSION_CACHE = None
+        _MAIDR_VERSION_CACHE_TIME = 0.0
+
     @staticmethod
     def _inject_plot(plot: HTML, maidr: str, maidr_id, use_iframe: bool = True) -> Tag:
         """Embed the plot and associated MAIDR scripts into the HTML structure."""
-        # MAIDR_TS_CDN_URL = "http://localhost:8888/tree/maidr/core/maidr.js"  # DEMO URL
-        MAIDR_TS_CDN_URL = "https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr.js"
-        # Append a query parameter (using TIMESTAMP) to bust the cache (so that the latest (non-cached) version is always loaded).
-        TIMESTAMP = datetime.now().strftime("%Y%m%d%H%M%S")
+        # Get the latest version from npm registry
+        latest_version = Maidr._get_latest_maidr_version()
+        MAIDR_TS_CDN_URL = (
+            f"https://cdn.jsdelivr.net/npm/maidr@{latest_version}/dist/maidr.js"
+        )
 
         script = f"""
-            if (!document.querySelector('script[src="{MAIDR_TS_CDN_URL}?v={TIMESTAMP}"]'))
+            if (!document.querySelector('script[src="{MAIDR_TS_CDN_URL}"]'))
             {{
                 var script = document.createElement('script');
                 script.type = 'module';
-                script.src = '{MAIDR_TS_CDN_URL}?v={TIMESTAMP}';
+                script.src = '{MAIDR_TS_CDN_URL}';
                 script.addEventListener('load', function() {{
                     window.main();
                 }});
@@ -299,7 +366,7 @@ class Maidr:
         base_html = tags.div(
             tags.link(
                 rel="stylesheet",
-                href="https://cdn.jsdelivr.net/npm/maidr/dist/maidr_style.css",
+                href=f"https://cdn.jsdelivr.net/npm/maidr@{latest_version}/dist/maidr_style.css",
             ),
             tags.script(script, type="text/javascript"),
             tags.div(plot),

{maidr-1.4.0 → maidr-1.4.2}/maidr/core/plot/candlestick.py

@@ -1,15 +1,24 @@
+from __future__ import annotations
+
 import matplotlib.dates as mdates
 import numpy as np
 from matplotlib.axes import Axes
 from matplotlib.patches import Rectangle
 
-from maidr.core.enum.plot_type import PlotType
-from maidr.core.plot.maidr_plot import MaidrPlot
+from maidr.core.enum import PlotType
+from maidr.core.plot import MaidrPlot
 from maidr.core.enum.maidr_key import MaidrKey
 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.
@@ -93,7 +102,20 @@ class CandlestickPlot(MaidrPlot):
         return []
 
     def _extract_axes_data(self) -> dict:
-        return {}
+        """
+        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) -> str:
         """Return the CSS selector for highlighting candlestick elements in the SVG output."""
@@ -109,9 +131,11 @@ class CandlestickPlot(MaidrPlot):
 
     def render(self) -> dict:
         """Initialize the MAIDR schema dictionary with basic plot information."""
+        title = "Candlestick Chart"
+
         maidr_schema = {
             MaidrKey.TYPE: self.type,
-            MaidrKey.TITLE: self.ax.get_title(),
+            MaidrKey.TITLE: title,
             MaidrKey.AXES: self._extract_axes_data(),
             MaidrKey.DATA: self._extract_plot_data(),
         }

{maidr-1.4.0 → maidr-1.4.2}/maidr/core/plot/mplfinance_barplot.py

@@ -30,6 +30,11 @@ class MplfinanceBarPlot(
         self._custom_patches = kwargs.get("_maidr_patches", None)
         # Store date numbers for volume bars (from mplfinance)
         self._maidr_date_nums = kwargs.get("_maidr_date_nums", None)
+        # Store custom title
+
+    def set_title(self, title: str) -> None:
+        """Set a custom title for this volume bar plot."""
+        self._title = title
 
     def _extract_plot_data(self) -> list:
         """Extract data from mplfinance volume patches."""
@@ -113,3 +118,22 @@ class MplfinanceBarPlot(
         # Use the standard working selector that gets replaced with UUID by Maidr class
         # This works for both original bar plots and mplfinance volume bars
         return "g[maidr='true'] > path"
+
+    def render(self) -> dict:
+        """Initialize the MAIDR schema dictionary with basic plot information."""
+        from maidr.core.enum.maidr_key import MaidrKey
+
+        title = "Volume Bar Plot"
+
+        maidr_schema = {
+            MaidrKey.TYPE: self.type,
+            MaidrKey.TITLE: title,
+            MaidrKey.AXES: self._extract_axes_data(),
+            MaidrKey.DATA: self._extract_plot_data(),
+        }
+
+        # Include selector only if the plot supports highlighting.
+        if self._support_highlighting:
+            maidr_schema[MaidrKey.SELECTOR] = self._get_selector()
+
+        return maidr_schema

{maidr-1.4.0 → maidr-1.4.2}/maidr/core/plot/mplfinance_lineplot.py

@@ -23,6 +23,7 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
 
     def __init__(self, ax: Axes, **kwargs):
         super().__init__(ax, PlotType.LINE)
+        self._line_titles = []  # Store line titles separately
 
     def _get_selector(self) -> Union[str, List[str]]:
         """Return selectors for all lines that have data."""
@@ -47,6 +48,65 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
 
         return selectors
 
+    def _extract_axes_data(self) -> dict:
+        """
+        Extract axis labels for the plot.
+
+        Returns
+        -------
+        dict
+            Dictionary containing x and y axis labels with custom y-label for moving averages.
+        """
+        x_labels = self.ax.get_xlabel()
+        if not x_labels:
+            x_labels = self.extract_shared_xlabel(self.ax)
+        if not x_labels:
+            x_labels = "Date"
+
+        # Get the period from the first line for y-axis label
+        ma_period = self._extract_moving_average_period()
+        y_label = (
+            f"{ma_period}-day mav price ($)"
+            if ma_period
+            else "Moving Average Price ($)"
+        )
+
+        return {MaidrKey.X: x_labels, MaidrKey.Y: y_label}
+
+    def _extract_moving_average_periods(self) -> List[str]:
+        """
+        Extract all moving average periods from the _maidr_ma_period attributes set by the mplfinance patch.
+
+        Returns
+        -------
+        List[str]
+            List of moving average periods (e.g., ["3", "6", "30"]).
+        """
+        all_lines = self.ax.get_lines()
+        periods = []
+        for line in all_lines:
+            # Get the period that was stored by the mplfinance patch
+            ma_period = getattr(line, "_maidr_ma_period", None)
+            if ma_period is not None:
+                periods.append(str(ma_period))
+
+        # Remove duplicates and sort
+        periods = sorted(list(set(periods)))
+
+        return periods
+
+    def _extract_moving_average_period(self) -> str:
+        """
+        Extract the moving average period from the _maidr_ma_period attribute set by the mplfinance patch.
+
+        Returns
+        -------
+        str
+            The moving average period (e.g., "3", "6", "30") or empty string if no period found.
+        """
+        periods = self._extract_moving_average_periods()
+        return periods[0] if periods else ""
+
     def _extract_plot_data(self) -> Union[List[List[dict]], None]:
         """Extract data from mplfinance moving average lines."""
         data = self._extract_line_data()
@@ -91,6 +151,17 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
                 line.set_gid(unique_gid)
 
             label: str = line.get_label()  # type: ignore
+
+            # Get the period for this specific line
+            ma_period = getattr(line, "_maidr_ma_period", None)
+
+            # Create title for this line
+            line_title = (
+                f"{ma_period}-Day Moving Average Line Plot"
+                if ma_period
+                else "Moving Average Line Plot"
+            )
+
             line_data = []
 
             # Check if this line has date numbers from mplfinance
@@ -117,12 +188,22 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
                 point_data = {
                     MaidrKey.X: x_value,
                     MaidrKey.Y: float(y),
-                    MaidrKey.FILL: (label if not label.startswith("_child") else ""),
                 }
                 line_data.append(point_data)
 
             if line_data:
-                all_lines_data.append(line_data)
+                # Create line data with title, axes, and points structure
+                line_with_metadata = {
+                    "title": line_title,
+                    "axes": {
+                        "x": "Date",
+                        "y": f"{ma_period}-day mav price ($)"
+                        if ma_period
+                        else "Moving Average Price ($)",
+                    },
+                    "points": line_data,
+                }
+                all_lines_data.append(line_with_metadata)
 
         return all_lines_data if all_lines_data else None
 
@@ -144,3 +225,49 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
             Date string in YYYY-MM-DD format
         """
         return MplfinanceDataExtractor._convert_date_num_to_string(x_value)
+
+    def _extract_line_titles(self) -> List[str]:
+        """
+        Extract titles for all moving average lines.
+
+        Returns
+        -------
+        List[str]
+            List of titles for each line.
+        """
+        all_lines = self.ax.get_lines()
+        titles = []
+
+        for line in all_lines:
+            ma_period = getattr(line, "_maidr_ma_period", None)
+            title = (
+                f"{ma_period}-Day Moving Average Line Plot"
+                if ma_period
+                else "Moving Average Line Plot"
+            )
+            titles.append(title)
+
+        return titles
+
+    def render(self) -> dict:
+        """Initialize the MAIDR schema dictionary with basic plot information."""
+        # Use the first line's period for the main title
+        ma_period = self._extract_moving_average_period()
+        title = (
+            f"{ma_period}-Day Moving Averages Line Plot"
+            if ma_period
+            else "Moving Averages Line Plot"
+        )
+
+        maidr_schema = {
+            MaidrKey.TYPE: self.type,
+            MaidrKey.TITLE: title,
+            MaidrKey.AXES: self._extract_axes_data(),
+            MaidrKey.DATA: self._extract_plot_data(),
+        }
+
+        # Include selector only if the plot supports highlighting.
+        if self._support_highlighting:
+            maidr_schema[MaidrKey.SELECTOR] = self._get_selector()
+
+        return maidr_schema

{maidr-1.4.0 → maidr-1.4.2}/maidr/patch/mplfinance.py

@@ -8,7 +8,6 @@ from matplotlib.lines import Line2D
 from maidr.core.enum import PlotType
 from maidr.patch.common import common
 from maidr.core.context_manager import ContextManager
-from maidr.util.mplfinance_utils import MplfinanceDataExtractor
 
 
 def mplfinance_plot_patch(wrapped, instance, args, kwargs):
@@ -150,6 +149,9 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
                 # Map NaN count to likely moving average period
                 estimated_period = nan_count + 1
 
+                # Store the period directly on the line for easy access
+                setattr(line, "_maidr_ma_period", estimated_period)
+
                 # Create a better label for the line
                 label = str(line.get_label())
                 if label.startswith("_child"):

{maidr-1.4.0 → maidr-1.4.2}/maidr/patch/regplot.py

@@ -5,11 +5,10 @@ from matplotlib.axes import Axes
 from matplotlib.lines import Line2D
 from maidr.core.enum import PlotType
 from maidr.patch.common import common
-import numpy as np
 from maidr.core.context_manager import ContextManager
 import uuid
 from maidr.core.enum.smooth_keywords import SMOOTH_KEYWORDS
-from maidr.util.regression_line_utils import find_regression_line
+from maidr.util.regression_line_utils import find_smooth_lines_by_label
 
 
 def regplot(wrapped, instance, args, kwargs) -> Axes:
@@ -23,27 +22,34 @@ def regplot(wrapped, instance, args, kwargs) -> Axes:
         # Prevent any MAIDR layer registration during plotting when scatter=False
         with ContextManager.set_internal_context():
             ax = wrapped(*args, **kwargs)
+
     axes = ax if isinstance(ax, Axes) else ax.axes if hasattr(ax, "axes") else None
     if axes is not None:
-        regression_line = find_regression_line(axes)
-        if regression_line is not None:
-            # ---
-            # Assign a unique gid to the regression line if not already set.
-            # This is necessary because the SVG output may contain many <g> and <path> tags,
-            # and only the regression line should be uniquely selectable for accessibility and highlighting.
-            # By setting a unique gid, we ensure the backend and frontend can generate a reliable selector
-            # (e.g., g[id='maidr-...'] path) that matches only the intended regression line.
-            # ---
-            if regression_line.get_gid() is None:
+        # Find and register all smooth lines
+        smooth_lines = find_smooth_lines_by_label(axes)
+        for line in smooth_lines:
+            # If line doesn't have a gid yet, assign one and register
+            if line.get_gid() is None:
                 new_gid = f"maidr-{uuid.uuid4()}"
-                regression_line.set_gid(new_gid)
-            common(
-                PlotType.SMOOTH,
-                lambda *a, **k: ax,
-                instance,
-                args,
-                dict(kwargs, regression_line=regression_line),
-            )
+                line.set_gid(new_gid)
+                common(
+                    PlotType.SMOOTH,
+                    lambda *a, **k: ax,
+                    instance,
+                    args,
+                    dict(kwargs, regression_line=line),
+                )
+            else:
+                # Even if it has a gid, register it as a smooth layer
+                # This handles the case where patched_plot already assigned a gid
+                common(
+                    PlotType.SMOOTH,
+                    lambda *a, **k: ax,
+                    instance,
+                    args,
+                    dict(kwargs, regression_line=line),
+                )
+
     return ax
 
 
@@ -53,7 +59,8 @@ def patched_plot(wrapped, instance, args, kwargs):
     """
     # Call the original plot function
     lines = wrapped(*args, **kwargs)
-    # lines can be a list of Line2D objects
+
+    # Check each line for smooth keywords and register if found
     for line in lines:
         if isinstance(line, Line2D):
             label = line.get_label() or ""
@@ -72,6 +79,7 @@ def patched_plot(wrapped, instance, args, kwargs):
                     args,
                     dict(kwargs, regression_line=line),
                 )
+
     return lines
 
 

maidr-1.4.2/maidr/util/regression_line_utils.py

@@ -0,0 +1,69 @@
+from matplotlib.lines import Line2D
+from matplotlib.axes import Axes
+import numpy as np
+from typing import List, Union
+from maidr.core.enum.smooth_keywords import SMOOTH_KEYWORDS
+
+
+def find_regression_line(axes: Axes) -> Union[Line2D, None]:
+    """
+    Helper to find the regression line (Line2D) in the given axes.
+    """
+    return next(
+        (
+            artist
+            for artist in axes.get_children()
+            if isinstance(artist, Line2D)
+            and artist.get_label() not in (None, "", "_nolegend_")
+            and artist.get_xydata() is not None
+            and np.asarray(artist.get_xydata()).size > 0
+        ),
+        None,
+    )
+
+
+def find_smooth_lines_by_label(axes: Axes) -> List[Line2D]:
+    """
+    Helper to find all smooth/regression lines (Line2D) in the given axes by checking their labels.
+
+    This function detects smooth lines by examining their labels for smooth-related keywords
+    or generic '_child' labels that are commonly created by seaborn's regplot function.
+
+    Parameters
+    ----------
+    axes : matplotlib.axes.Axes
+        The matplotlib axes object to search for smooth lines.
+
+    Returns
+    -------
+    List[Line2D]
+        List of Line2D objects that have labels matching smooth keywords or generic '_child' labels.
+
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> import seaborn as sns
+    >>>
+    >>> fig, ax = plt.subplots()
+    >>> # Create a regplot with smooth line
+    >>> sns.regplot(x=[1, 2, 3], y=[1, 2, 3], ax=ax, lowess=True)
+    >>>
+    >>> # Find smooth lines
+    >>> smooth_lines = find_smooth_lines_by_label(ax)
+    >>> print(f"Found {len(smooth_lines)} smooth lines")
+    """
+    smooth_lines = []
+    for line in axes.get_lines():
+        if isinstance(line, Line2D):
+            label = line.get_label() or ""
+            label_str = str(label)
+
+            # Check if label matches smooth keywords
+            if any(key in label_str.lower() for key in SMOOTH_KEYWORDS):
+                smooth_lines.append(line)
+            # Also check for seaborn regplot lines with generic labels (like '_child0', '_child1')
+            elif label_str.startswith("_child"):
+                # Lines with _child labels are likely smooth lines from seaborn regplot
+                smooth_lines.append(line)
+
+    return smooth_lines

{maidr-1.4.0 → maidr-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "maidr"
-version = "1.4.0"
+version = "1.4.2"
 description = "Multimodal Access and Interactive Data Representations"
 authors = [
     "JooYoung Seo <jseo1005@illinois.edu>",

maidr-1.4.0/maidr/util/regression_line_utils.py

@@ -1,19 +0,0 @@
-from matplotlib.lines import Line2D
-import numpy as np
-
-
-def find_regression_line(axes):
-    """
-    Helper to find the regression line (Line2D) in the given axes.
-    """
-    return next(
-        (
-            artist
-            for artist in axes.get_children()
-            if isinstance(artist, Line2D)
-            and artist.get_label() not in (None, "", "_nolegend_")
-            and artist.get_xydata() is not None
-            and np.asarray(artist.get_xydata()).size > 0
-        ),
-        None,
-    )