maidr 1.7.2__tar.gz → 1.8.0__tar.gz

{maidr-1.7.2 → maidr-1.8.0}/CHANGELOG.md

@@ -1,6 +1,39 @@
 # CHANGELOG
 
 
+## v1.8.0 (2025-09-17)
+
+### Features
+
+- Remove maidr.show params ([#244](https://github.com/xability/py-maidr/pull/244),
+  [`493cf57`](https://github.com/xability/py-maidr/commit/493cf5713068b1514b4836e46763c3619a51dd23))
+
+### Refactoring
+
+- **maidr.api**: Improve lazy figure detection, eliminate code duplication, and resolve merge
+  conflicts ([#241](https://github.com/xability/py-maidr/pull/241),
+  [`15a966e`](https://github.com/xability/py-maidr/commit/15a966ea2ca9170ddf8bc28634705fb6233a1d58))
+
+Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
+
+Co-authored-by: jooyoungseo <19754711+jooyoungseo@users.noreply.github.com>
+
+
+## v1.7.3 (2025-09-15)
+
+### Bug Fixes
+
+- Ensure all subplots are accessible and improve dodged plot detection
+  ([#242](https://github.com/xability/py-maidr/pull/242),
+  [`979b971`](https://github.com/xability/py-maidr/commit/979b9713d07be8bc9046056e7f1c0519336ddd22))
+
+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.7.2 (2025-09-12)
 
 ### Bug Fixes

{maidr-1.7.2 → maidr-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.7.2
+Version: 1.8.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.7.2 → maidr-1.8.0}/example/flask/test_flask_app.py

@@ -1,5 +1,6 @@
 import matplotlib
-matplotlib.use('Agg')  # Use non-interactive backend for Flask
+
+matplotlib.use("Agg")  # Use non-interactive backend for Flask
 
 from flask import Flask
 import matplotlib.pyplot as plt
@@ -14,7 +15,8 @@ logger = logging.getLogger(__name__)
 
 app = Flask(__name__)
 
-@app.route('/')
+
+@app.route("/")
 def index():
     # Log environment detection
     logger.info("=== Environment Detection ===")
@@ -34,8 +36,12 @@ def index():
     logger.info(f"flask_detected: {flask_detected}")
     logger.info(f"notebook_detected: {notebook_detected}")
     logger.info(f"shiny_detected: {shiny_detected}")
-    logger.info("Condition: use_iframe and (flask_detected or notebook_detected or shiny_detected)")
-    logger.info(f"Result: {use_iframe and (flask_detected or notebook_detected or shiny_detected)}")
+    logger.info(
+        "Condition: use_iframe and (flask_detected or notebook_detected or shiny_detected)"
+    )
+    logger.info(
+        f"Result: {use_iframe and (flask_detected or notebook_detected or shiny_detected)}"
+    )
 
     # Load the penguins dataset
     penguins = sns.load_dataset("penguins")
@@ -65,7 +71,8 @@ def index():
     # Return the maidr HTML directly
     return str(maidr_html)
 
-if __name__ == '__main__':
+
+if __name__ == "__main__":
     logger.info("Starting Flask app with logging...")
     logger.info("Visit http://localhost:5002 to see the maidr plot in Flask")
-    app.run(debug=False, host='0.0.0.0', port=5002)
+    app.run(debug=False, host="0.0.0.0", port=5002)

{maidr-1.7.2 → maidr-1.8.0}/maidr/__init__.py

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

maidr-1.8.0/maidr/api.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from htmltools import Tag
+from matplotlib.axes import Axes
+from matplotlib.container import BarContainer
+
+from maidr.core import Maidr
+from maidr.core.enum import PlotType
+from maidr.core.figure_manager import FigureManager
+
+
+def _get_plot_or_current(plot: Any | None) -> Any:
+    """
+    Get the plot object or current matplotlib figure if plot is None.
+    
+    Parameters
+    ----------
+    plot : Any or None
+        The plot object. If None, returns the current matplotlib figure.
+        
+    Returns
+    -------
+    Any
+        The plot object or current matplotlib figure.
+    """
+    if plot is None:
+        # Lazy import matplotlib.pyplot when needed
+        import matplotlib.pyplot as plt
+        
+        return plt.gcf()
+    return plot
+
+
+def render(plot: Any | None = None) -> Tag:
+    """
+    Render a MAIDR plot to HTML.
+
+    Parameters
+    ----------
+    plot : Any or None, optional
+        The plot object to render. If None, uses the current matplotlib figure.
+
+    Returns
+    -------
+    htmltools.Tag
+        The rendered HTML representation of the plot.
+    """
+    plot = _get_plot_or_current(plot)
+    
+    ax = FigureManager.get_axes(plot)
+    if isinstance(ax, list):
+        for axes in ax:
+            maidr = FigureManager.get_maidr(axes.get_figure())
+        return maidr.render()
+    else:
+        maidr = FigureManager.get_maidr(ax.get_figure())
+        return maidr.render()
+
+
+def show(
+    plot: Any | None = None,
+    renderer: Literal["auto", "ipython", "browser"] = "auto",
+    clear_fig: bool = True,
+) -> object:
+    """
+    Display a MAIDR plot.
+
+    Parameters
+    ----------
+    plot : Any or None, optional
+        The plot object to display. If None, uses the current matplotlib figure.
+    renderer : {"auto", "ipython", "browser"}, default "auto"
+        The renderer to use for display.
+    clear_fig : bool, default True
+        Whether to clear the figure after displaying.
+
+    Returns
+    -------
+    object
+        The display result.
+    """
+    plot = _get_plot_or_current(plot)
+    
+    ax = FigureManager.get_axes(plot)
+    if isinstance(ax, list):
+        for axes in ax:
+            maidr = FigureManager.get_maidr(axes.get_figure())
+        return maidr.show(renderer)
+    else:
+        maidr = FigureManager.get_maidr(ax.get_figure())
+        return maidr.show(renderer, clear_fig=clear_fig)
+
+
+def save_html(
+    plot: Any | None = None,
+    *, 
+    file: str,
+    lib_dir: str | None = "lib", 
+    include_version: bool = True
+) -> str:
+    """
+    Save a MAIDR plot as HTML file.
+
+    Parameters
+    ----------
+    plot : Any or None, optional
+        The plot object to save. If None, uses the current matplotlib figure.
+    file : str
+        The file path where to save the HTML.
+    lib_dir : str or None, default "lib"
+        Directory name for libraries.
+    include_version : bool, default True
+        Whether to include version information.
+
+    Returns
+    -------
+    str
+        The path to the saved HTML file.
+    """
+    plot = _get_plot_or_current(plot)
+    
+    ax = FigureManager.get_axes(plot)
+    htmls = []
+    if isinstance(ax, list):
+        for axes in ax:
+            maidr = FigureManager.get_maidr(axes.get_figure())
+            htmls.append(maidr._create_html_doc(use_iframe=False))
+        return htmls[-1].save_html(
+            file, libdir=lib_dir, include_version=include_version
+        )
+    else:
+        maidr = FigureManager.get_maidr(ax.get_figure())
+        return maidr.save_html(file, lib_dir=lib_dir, include_version=include_version)
+
+
+def stacked(plot: Axes | BarContainer) -> Maidr:
+    ax = FigureManager.get_axes(plot)
+    return FigureManager.create_maidr(ax, PlotType.STACKED)
+
+
+def close(plot: Any | None = None) -> None:
+    """
+    Close a MAIDR plot and clean up resources.
+
+    Parameters
+    ----------
+    plot : Any or None, optional
+        The plot object to close. If None, uses the current matplotlib figure.
+    """
+    plot = _get_plot_or_current(plot)
+    
+    ax = FigureManager.get_axes(plot)
+    FigureManager.destroy(ax.get_figure())

{maidr-1.7.2 → maidr-1.8.0}/maidr/core/figure_manager.py

@@ -15,20 +15,24 @@ from maidr.core.plot import MaidrPlotFactory
 
 class FigureManager:
     """
-    Manages creation and retrieval of Maidr instances associated with matplotlib figures.
+    Manages creation and retrieval of Maidr instances associated with figures.
 
-    This class provides methods to manage Maidr objects which facilitate the organization and
-    manipulation of plots within matplotlib figures.
+    This class provides methods to manage Maidr objects which facilitate the
+    organization and manipulation of plots within matplotlib figures.
 
     Attributes
     ----------
     figs : dict
-        A dictionary that maps matplotlib Figure objects to their corresponding Maidr instances.
+        A dictionary that maps matplotlib Figure objects to their corresponding
+        Maidr instances.
+    PLOT_TYPE_PRIORITY : dict
+        Defines the priority order for plot types. Higher numbers take precedence.
 
     Methods
     -------
     create_maidr(ax, plot_type, **kwargs)
-        Creates a Maidr instance for the given Axes and plot type, and adds a plot to it.
+        Creates a Maidr instance for the given Axes and plot type, and adds a
+        plot to it.
     _get_maidr(fig)
         Retrieves or creates a Maidr instance associated with the given Figure.
     get_axes(artist)
@@ -37,6 +41,21 @@ class FigureManager:
 
     figs = {}
 
+    # Define plot type priority order (higher numbers take precedence)
+    PLOT_TYPE_PRIORITY = {
+        PlotType.BAR: 1,
+        PlotType.STACKED: 2,
+        PlotType.DODGED: 2,  # DODGED and STACKED have same priority
+        PlotType.LINE: 1,
+        PlotType.SCATTER: 1,
+        PlotType.HIST: 1,
+        PlotType.BOX: 1,
+        PlotType.HEAT: 1,
+        PlotType.COUNT: 1,
+        PlotType.SMOOTH: 1,
+        PlotType.CANDLESTICK: 1,
+    }
+
     _instance = None
     _lock = threading.Lock()
 
@@ -44,14 +63,15 @@ class FigureManager:
         if not cls._instance:
             with cls._lock:
                 if not cls._instance:
-                    cls._instance = super(FigureManager, cls).__new__()
+                    cls._instance = super(FigureManager, cls).__new__(cls)
         return cls._instance
 
     @classmethod
     def create_maidr(
         cls, axes: Axes | list[Axes], plot_type: PlotType, **kwargs
     ) -> Maidr:
-        """Create a Maidr instance for the given Axes and plot type, and adds a plot to it."""
+        """Create a Maidr instance for the given Axes and plot type, and
+        adds a plot to it."""
         if axes is None:
             raise ValueError("No plot found.")
         if plot_type is None:
@@ -72,9 +92,34 @@ class FigureManager:
 
     @classmethod
     def _get_maidr(cls, fig: Figure, plot_type: PlotType) -> Maidr:
-        """Retrieve or create a Maidr instance for the given Figure."""
+        """
+        Retrieve or create a Maidr instance for the given Figure.
+
+        If a Maidr instance already exists for the figure, update its plot type
+        if the new plot type has higher priority (DODGED/STACKED > BAR).
+
+        Parameters
+        ----------
+        fig : Figure
+            The matplotlib figure to get or create a Maidr instance for.
+        plot_type : PlotType
+            The plot type to set or update for the Maidr instance.
+
+        Returns
+        -------
+        Maidr
+            The Maidr instance associated with the figure.
+        """
         if fig not in cls.figs.keys():
             cls.figs[fig] = Maidr(fig, plot_type)
+        else:
+            # Update plot type if the new type has higher priority
+            maidr = cls.figs[fig]
+            current_priority = cls.PLOT_TYPE_PRIORITY.get(maidr.plot_type, 0)
+            new_priority = cls.PLOT_TYPE_PRIORITY.get(plot_type, 0)
+
+            if new_priority > current_priority:
+                maidr.plot_type = plot_type
         return cls.figs[fig]
 
     @classmethod

{maidr-1.7.2 → maidr-1.8.0}/maidr/core/maidr.py

@@ -10,6 +10,7 @@ import webbrowser
 import subprocess
 from pathlib import Path
 from typing import Any, Literal, cast
+from collections import defaultdict
 
 import matplotlib.pyplot as plt
 from htmltools import HTML, HTMLDocument, Tag, tags
@@ -159,10 +160,7 @@ class Maidr:
             if explorer_path:
                 try:
                     result = subprocess.run(
-                        [explorer_path, url],
-                        capture_output=True,
-                        text=True,
-                        timeout=10
+                        [explorer_path, url], capture_output=True, text=True, timeout=10
                     )
 
                     if result.returncode == 0:
@@ -204,10 +202,49 @@ class Maidr:
         """Create an HTML document from Tag objects."""
         return HTMLDocument(self._create_html_tag(use_iframe), lang="en")
 
+    def _merge_plots_by_subplot_position(self) -> list[MaidrPlot]:
+        """
+        Merge plots by their subplot position, keeping only the first plot per position.
+
+        For DODGED and STACKED plot types, multiple plots on the same subplot
+        should be merged into a single plot since GroupedBarPlot extracts all
+        containers from the axes itself.
+
+        Returns
+        -------
+        list[MaidrPlot]
+            List of plots with one plot per unique subplot position.
+
+        Examples
+        --------
+        If we have plots at positions [(0,0), (0,0), (0,1), (1,0)],
+        this will return plots at positions [(0,0), (0,1), (1,0)].
+        """
+        # Group plots by their subplot position (row, col) using defaultdict
+        subplot_groups: dict[tuple[int, int], list[MaidrPlot]] = defaultdict(list)
+
+        for plot in self._plots:
+            # Get subplot position, defaulting to (0, 0) if not set
+            position = (getattr(plot, "row_index", 0), getattr(plot, "col_index", 0))
+            subplot_groups[position].append(plot)
+
+        # Keep only the first plot for each subplot position
+        # The GroupedBarPlot will extract all containers from that axes
+        merged_plots: list[MaidrPlot] = []
+        for position_plots in subplot_groups.values():
+            merged_plots.append(
+                position_plots[0]
+            )  # Each list is guaranteed to have at least one plot
+
+        return merged_plots
+
     def _flatten_maidr(self) -> dict | list[dict]:
         """Return a single plot schema or a list of schemas from the Maidr instance."""
+        # Handle DODGED/STACKED plots: only keep one plot per subplot position
+        # because GroupedBarPlot extracts all containers from the axes itself
         if self.plot_type in (PlotType.DODGED, PlotType.STACKED):
-            self._plots = [self._plots[0]]
+            self._plots = self._merge_plots_by_subplot_position()
+
         # Deduplicate: if any SMOOTH plots exist, remove LINE plots
         self._plots = deduplicate_smooth_and_line(self._plots)
 
@@ -354,7 +391,11 @@ class Maidr:
         # Render the plot inside an iframe if in a Jupyter notebook, Google Colab
         # or VSCode notebook. No need for iframe if this is a Quarto document.
         # For TypeScript we will use iframe by default for now
-        if use_iframe and (Environment.is_flask() or Environment.is_notebook() or Environment.is_shiny()):
+        if use_iframe and (
+            Environment.is_flask()
+            or Environment.is_notebook()
+            or Environment.is_shiny()
+        ):
             unique_id = "iframe_" + Maidr._unique_id()
 
             def generate_iframe_script(unique_id: str) -> str:

{maidr-1.7.2 → maidr-1.8.0}/maidr/core/plot/candlestick.py

@@ -43,7 +43,9 @@ class CandlestickPlot(MaidrPlot):
         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_original_data = kwargs.get(
+            "_maidr_original_data", None
+        )  # Store original data
         self._maidr_datetime_converter = kwargs.get("_maidr_datetime_converter", None)
 
         # Store the GID for proper selector generation (legacy/shared)
@@ -122,7 +124,9 @@ class CandlestickPlot(MaidrPlot):
                     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
+                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 = []
@@ -132,7 +136,11 @@ class CandlestickPlot(MaidrPlot):
                         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:
+                        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:
@@ -176,7 +184,12 @@ class CandlestickPlot(MaidrPlot):
         - 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:
+        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:

{maidr-1.7.2 → maidr-1.8.0}/maidr/core/plot/lineplot.py

@@ -115,7 +115,9 @@ class MultiLinePlot(MaidrPlot, LineExtractorMixin):
                 line_type = label
 
             # Use the new method to extract data with categorical labels
-            line_coords = LineExtractorMixin.extract_line_data_with_categorical_labels(self.ax, line)
+            line_coords = LineExtractorMixin.extract_line_data_with_categorical_labels(
+                self.ax, line
+            )
             if line_coords is None:
                 continue
 

{maidr-1.7.2 → maidr-1.8.0}/maidr/core/plot/maidr_plot.py

@@ -5,6 +5,7 @@ from abc import ABC, abstractmethod
 from matplotlib.axes import Axes
 
 from maidr.core.enum import MaidrKey, PlotType
+
 # uuid is used to generate unique identifiers for each plot layer in the MAIDR schema.
 import uuid
 

{maidr-1.7.2 → maidr-1.8.0}/maidr/core/plot/mplfinance_lineplot.py

@@ -105,7 +105,10 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
                     continue
 
                 # Use datetime converter for enhanced data extraction
-                datetime_converter = getattr(line, "_maidr_datetime_converter", None) or self._maidr_datetime_converter
+                datetime_converter = (
+                    getattr(line, "_maidr_datetime_converter", None)
+                    or self._maidr_datetime_converter
+                )
                 if datetime_converter is not None:
                     # Convert x-coordinate (matplotlib index) to formatted datetime
                     x_value = datetime_converter.get_formatted_datetime(int(round(x)))