maidr 1.9.0__tar.gz → 1.10.0__tar.gz

{maidr-1.9.0 → maidr-1.10.0}/CHANGELOG.md

@@ -1,6 +1,15 @@
 # CHANGELOG
 
 
+## v1.10.0 (2026-01-31)
+
+### Features
+
+- Remove candlestick formatting and add ylabel to dodged plots
+  ([#260](https://github.com/xability/py-maidr/pull/260),
+  [`70b2626`](https://github.com/xability/py-maidr/commit/70b2626bb31e109e8cdb29051f809fe03bfb6275))
+
+
 ## v1.9.0 (2025-10-31)
 
 ### Features

{maidr-1.9.0 → maidr-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.9.0
+Version: 1.10.0
 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

{maidr-1.9.0 → maidr-1.10.0}/docs/examples.qmd

@@ -152,6 +152,7 @@ for offset, (category, counts) in zip(offsets, weight_counts.items()):
 ax.set_xticks(x)
 ax.set_xticklabels(species)
 ax.set_xlabel("Species")
+ax.set_ylabel("Weight")
 ax.set_title("Dodged Bar Plot: Penguin Weight Counts")
 ax.legend(loc="upper right")
 

{maidr-1.9.0 → maidr-1.10.0}/maidr/__init__.py

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

{maidr-1.9.0 → maidr-1.10.0}/maidr/core/plot/candlestick.py

@@ -1,24 +1,21 @@
 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
+import pandas as pd
 
 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.
+    This class extracts candlestick data directly from the original DataFrame
+    without any formatting or transformation.
     """
 
     def __init__(self, axes: list[Axes], **kwargs) -> None:
@@ -34,23 +31,17 @@ class CandlestickPlot(MaidrPlot):
             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
+        # Store 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
-        self._maidr_datetime_converter = kwargs.get("_maidr_datetime_converter", None)
+        self._maidr_original_data = kwargs.get("_maidr_original_data", None)
 
-        # Store the GID for proper selector generation (legacy/shared)
+        # Store the GID for selector generation
         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:
@@ -62,105 +53,83 @@ class CandlestickPlot(MaidrPlot):
 
     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.
+        Extract candlestick data directly from the original DataFrame.
 
         Returns
         -------
         list[dict]
             List of dictionaries containing candlestick data with keys:
-            - 'value': Date string
+            - 'value': Date string (raw from DataFrame index)
             - '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)
+            - 'volume': Volume (float)
         """
-
-        # 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)
+            # Store the GIDs from the collections
             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 datetime converter for enhanced data extraction
-            if self._maidr_datetime_converter is not None:
-                data = self._maidr_datetime_converter.extract_candlestick_data(
-                    self.axes[0], wick_collection, body_collection
-                )
-                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
+            # Extract data directly from DataFrame
+            if self._maidr_original_data is not None and isinstance(
+                self._maidr_original_data, pd.DataFrame
+            ):
+                return self._extract_from_dataframe(self._maidr_original_data)
 
         return []
 
+    def _extract_from_dataframe(self, df: pd.DataFrame) -> list[dict]:
+        """
+        Extract candlestick data directly from DataFrame without any formatting.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            DataFrame with OHLC data and DatetimeIndex.
+
+        Returns
+        -------
+        list[dict]
+            List of candlestick data dictionaries with raw values.
+        """
+        candles = []
+
+        for i in range(len(df)):
+            try:
+                # Get date directly from index - raw representation
+                date_value = str(df.index[i])
+
+                # Get OHLC values directly from DataFrame columns
+                open_price = float(df.iloc[i]["Open"])
+                high_price = float(df.iloc[i]["High"])
+                low_price = float(df.iloc[i]["Low"])
+                close_price = float(df.iloc[i]["Close"])
+
+                # Get volume if available, otherwise 0
+                volume = float(df.iloc[i].get("Volume", 0.0))
+
+                candle_data = {
+                    "value": date_value,
+                    "open": open_price,
+                    "high": high_price,
+                    "low": low_price,
+                    "close": close_price,
+                    "volume": volume,
+                }
+                candles.append(candle_data)
+            except (KeyError, IndexError, ValueError, TypeError):
+                continue
+
+        return candles
+
     def _extract_axes_data(self) -> dict:
         """
         Extract the plot's axes data including labels.

{maidr-1.9.0 → maidr-1.10.0}/maidr/util/datetime_conversion.py

@@ -6,18 +6,16 @@ from datetime import datetime
 
 class DatetimeConverter:
     """
-    Enhanced datetime converter that automatically detects time periods
-    and provides intelligent date/time formatting for mplfinance plots.
+    Datetime converter for mplfinance plots.
 
-    This utility automatically detects the time period of financial data and formats
-    datetime values consistently for screen reader accessibility and visual clarity.
+    This utility provides datetime value conversion for financial data visualization.
 
     Parameters
     ----------
     data : pd.DataFrame
         DataFrame with DatetimeIndex containing financial data.
     datetime_format : str, optional
-        Custom datetime format string. If None, automatic format detection is used.
+        Custom datetime format string (currently unused, kept for compatibility).
 
     Attributes
     ----------
@@ -49,14 +47,14 @@ class DatetimeConverter:
     >>>
     >>> # Get formatted datetime
     >>> formatted = converter.get_formatted_datetime(0)
-    >>> print(formatted)  # Output: "Jan 15 2024"
+    >>> print(formatted)  # Output: "2024-01-15 00:00:00"
     >>>
     >>> # For time-based data
     >>> hourly_dates = pd.date_range('2024-01-15 09:00:00', periods=3, freq='H')
     >>> df_hourly = pd.DataFrame({'Open': [3050, 3078, 3080]}, index=hourly_dates)
     >>> converter_hourly = create_datetime_converter(df_hourly)
     >>> formatted_hourly = converter_hourly.get_formatted_datetime(0)
-    >>> print(formatted_hourly)  # Output: "Jan 15 2024 09:00"
+    >>> print(formatted_hourly)  # Output: "2024-01-15 09:00:00"
     """
 
     def __init__(
@@ -164,9 +162,7 @@ class DatetimeConverter:
 
     def get_formatted_datetime(self, index: int) -> Optional[str]:
         """
-        Get formatted datetime string for given index using consistent formatting.
-
-        Always includes year for screen reader accessibility.
+        Get datetime string for given index.
 
         Parameters
         ----------
@@ -176,13 +172,13 @@ class DatetimeConverter:
         Returns
         -------
         str or None
-            Formatted datetime string or None if index is invalid.
+            Datetime string or None if index is invalid.
 
         Examples
         --------
         >>> converter = create_datetime_converter(df)
         >>> formatted = converter.get_formatted_datetime(0)
-        >>> print(formatted)  # "Jan 15 2024" for daily data
+        >>> print(formatted)  # "2024-01-15 00:00:00"
         """
         if index not in self.date_mapping:
             return None
@@ -192,7 +188,7 @@ class DatetimeConverter:
 
     def _format_datetime_custom(self, dt: datetime) -> str:
         """
-        Consistent datetime formatting with year always included.
+        Format datetime as-is using ISO format.
 
         Parameters
         ----------
@@ -202,24 +198,15 @@ class DatetimeConverter:
         Returns
         -------
         str
-            Formatted datetime string with consistent pattern.
+            Formatted datetime string in ISO format.
 
         Notes
         -----
-        Formatting rules:
-        - Daily data: "Jan 15 2024"
-        - Time-based data: "Jan 15 2024 09:00" or "Jan 15 2024 09:00:30"
-        - Seconds are only shown when they are non-zero for cleaner display.
+        Returns the datetime as a string without smart formatting.
+        Output format is "YYYY-MM-DD HH:MM:SS" (e.g., "2024-01-15 00:00:00").
         """
-        if self.time_period in ["minute", "intraday", "hour"]:
-            # Time-based data: include time with optional seconds
-            if dt.second == 0:
-                return dt.strftime("%b %d %Y %H:%M")
-            else:
-                return dt.strftime("%b %d %Y %H:%M:%S")
-        else:
-            # Daily/weekly/monthly data: just date
-            return dt.strftime("%b %d %Y")
+        # Return string representation of datetime
+        return str(dt)
 
     @property
     def date_nums(self) -> List[float]:

maidr-1.10.0/maidr/util/mplfinance_utils.py

@@ -0,0 +1,117 @@
+"""
+Utility functions for handling mplfinance-specific data extraction and processing.
+"""
+
+import re
+import matplotlib.dates as mdates
+from matplotlib.patches import Rectangle
+from typing import List, Optional
+
+
+class MplfinanceDataExtractor:
+    """
+    Utility class for extracting and processing mplfinance-specific data.
+
+    This class handles the conversion of mplfinance plot elements (patches, collections)
+    into standardized data formats that can be used by the core plot classes.
+    """
+
+    @staticmethod
+    def extract_volume_data(
+        volume_patches: List[Rectangle], date_nums: Optional[List[float]] = None
+    ) -> List[dict]:
+        """
+        Extract volume data from mplfinance Rectangle patches.
+
+        Parameters
+        ----------
+        volume_patches : List[Rectangle]
+            List of Rectangle patches representing volume bars
+        date_nums : Optional[List[float]], default=None
+            List of matplotlib date numbers corresponding to the patches
+
+        Returns
+        -------
+        List[dict]
+            List of dictionaries with 'x' and 'y' keys for volume data
+        """
+        if not volume_patches:
+            return []
+
+        formatted_data = []
+
+        # Sort patches by x-coordinate to maintain order
+        sorted_patches = sorted(volume_patches, key=lambda p: p.get_x())
+
+        for i, patch in enumerate(sorted_patches):
+            height = patch.get_height()
+
+            # Use date mapping if available, otherwise use index
+            if date_nums is not None and i < len(date_nums):
+                date_num = date_nums[i]
+                x_label = MplfinanceDataExtractor._convert_date_num_to_string(date_num)
+            else:
+                x_label = f"date_{i:03d}"
+
+            formatted_data.append({"x": str(x_label), "y": float(height)})
+
+        return formatted_data
+
+    @staticmethod
+    def clean_axis_label(label: str) -> str:
+        """
+        Clean up axis labels by removing LaTeX formatting.
+
+        Parameters
+        ----------
+        label : str
+            The original axis label
+
+        Returns
+        -------
+        str
+            Cleaned axis label
+        """
+        if not label or not isinstance(label, str):
+            return label
+
+        # Removes LaTeX-like scientific notation, e.g., "$10^{6}$"
+        cleaned_label = re.sub(r"\s*\$.*?\$", "", label).strip()
+        return cleaned_label if cleaned_label else label
+
+    @staticmethod
+    def _convert_date_num_to_string(date_num: float) -> str:
+        """
+        Convert matplotlib date number to date string.
+
+        Parameters
+        ----------
+        date_num : float
+            Matplotlib date number
+
+        Returns
+        -------
+        str
+            Date string representation (e.g., "2024-01-15 00:00:00") or fallback index
+        """
+        try:
+            # Check if this looks like a matplotlib date number (typically > 700000)
+            if date_num > 700000:
+                date_dt = mdates.num2date(date_num)
+                if hasattr(date_dt, "replace"):
+                    date_dt = date_dt.replace(tzinfo=None)
+                return str(date_dt)
+            elif date_num > 1000:
+                # Try converting as if it's a pandas timestamp
+                try:
+                    import pandas as pd
+
+                    date_dt = pd.to_datetime(date_num, unit="D")
+                    return str(date_dt)
+                except (ValueError, TypeError):
+                    pass
+        except (ValueError, TypeError, OverflowError):
+            pass
+
+        # Fallback to index-based date string
+        return f"date_{int(date_num):03d}"

{maidr-1.9.0 → maidr-1.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "maidr"
-version = "1.9.0"
+version = "1.10.0"
 description = "Multimodal Access and Interactive Data Representations"
 authors = [
     { name = "JooYoung Seo", email = "jseo1005@illinois.edu" },

{maidr-1.9.0 → maidr-1.10.0}/uv.lock

@@ -1876,7 +1876,7 @@ wheels = [
 
 [[package]]
 name = "maidr"
-version = "1.8.1"
+version = "1.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "htmltools" },
@@ -3993,6 +3993,12 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1e/48/973da1ee8bc0743519759e74c3615b39acdc3faf00e0a0710f8c856d8c9d/statsmodels-0.14.5-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a085d47c8ef5387279a991633883d0e700de2b0acc812d7032d165888627bef", size = 10453538, upload-time = "2025-07-07T14:24:06.959Z" },
     { url = "https://files.pythonhosted.org/packages/c7/d6/18903fb707afd31cf1edaec5201964dbdacb2bfae9a22558274647a7c88f/statsmodels-0.14.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9f866b2ebb2904b47c342d00def83c526ef2eb1df6a9a3c94ba5fe63d0005aec", size = 10681584, upload-time = "2025-07-07T14:24:21.038Z" },
     { url = "https://files.pythonhosted.org/packages/44/d6/80df1bbbfcdc50bff4152f43274420fa9856d56e234d160d6206eb1f5827/statsmodels-0.14.5-cp313-cp313-win_amd64.whl", hash = "sha256:2a06bca03b7a492f88c8106103ab75f1a5ced25de90103a89f3a287518017939", size = 9604641, upload-time = "2025-07-07T12:08:36.23Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/6c/0fb40a89d715412160097c6f3387049ed88c9bd866c8838a8852c705ae2f/statsmodels-0.14.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:07c4dad25bbb15864a31b4917a820f6d104bdc24e5ddadcda59027390c3bed9e", size = 10211256, upload-time = "2025-10-30T13:46:58.591Z" },
+    { url = "https://files.pythonhosted.org/packages/88/4a/e36fe8b19270ab3e80df357da924c6c029cab0fb9a0fbd28aaf49341707d/statsmodels-0.14.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:babb067c852e966c2c933b79dbb5d0240919d861941a2ef6c0e13321c255528d", size = 10110933, upload-time = "2025-10-30T13:47:11.774Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/bf/1b7e7b1a6c09a88a9c5c9e60622c050dfd08af11c2e6d4a42dbc71b32ee1/statsmodels-0.14.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:110194b137286173cc676d7bad0119a197778de6478fc6cbdc3b33571165ac1e", size = 10253981, upload-time = "2025-10-30T16:32:22.399Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/d0/f95da95524bdd99613923ca61a3036d1308cee1290e5e8acb89f51736a8c/statsmodels-0.14.5-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9c8a9c384a60c80731b278e7fd18764364c8817f4995b13a175d636f967823d1", size = 10460450, upload-time = "2025-10-30T16:32:44.985Z" },
+    { url = "https://files.pythonhosted.org/packages/28/bb/59e7be0271be264b7b541baf3973f97747740950bfd5115de731f63da8ab/statsmodels-0.14.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:557df3a870a57248df744fdfcc444ecbc5bdbf1c042b8a8b5d8e3e797830dc2a", size = 10694060, upload-time = "2025-10-30T16:33:07.656Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/c0/b28d0fd0347ea38d3610052f479e4b922eb33bb8790817f93cd89e6e08ba/statsmodels-0.14.5-cp314-cp314-win_amd64.whl", hash = "sha256:95af7a9c4689d514f4341478b891f867766f3da297f514b8c4adf08f4fa61d03", size = 9648961, upload-time = "2025-10-30T13:47:24.303Z" },
     { url = "https://files.pythonhosted.org/packages/39/2d/3ab5a8e736b94a91434a70dcbdc4363775711ef17c733e6bde5f24cb2f62/statsmodels-0.14.5-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:b23b8f646dd78ef5e8d775d879208f8dc0a73418b41c16acac37361ff9ab7738", size = 10077385, upload-time = "2025-07-07T12:13:55.07Z" },
     { url = "https://files.pythonhosted.org/packages/44/ec/091dc1e69bbc84139e3409e45ac26e285ef41eb67116d13e094cdde7804d/statsmodels-0.14.5-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:4e5e26b21d2920905764fb0860957d08b5ba2fae4466ef41b1f7c53ecf9fc7fa", size = 9752723, upload-time = "2025-07-07T12:08:52.238Z" },
     { url = "https://files.pythonhosted.org/packages/72/0a/0ab3a900fc3245ebdaaca59018567b1e23bcab13c9eea2d7b3d8ffcbb82e/statsmodels-0.14.5-cp39-cp39-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4a060c7e0841c549c8ce2825fd6687e6757e305d9c11c9a73f6c5a0ce849bb69", size = 10470566, upload-time = "2025-07-07T14:33:03.356Z" },