MatplotLibAPI 3.2.8__py3-none-any.whl → 3.2.9__py3-none-any.whl

MatplotLibAPI/Composite.py

@@ -1,6 +1,6 @@
 # Hint for Visual Code Python Interactive window
 # %%
-from typing import Optional, Tuple, List
+from typing import Optional, Tuple, List, Dict
 import pandas as pd
 import matplotlib.pyplot as plt
 from matplotlib.figure import Figure
@@ -27,7 +27,53 @@ def plot_composite_bubble(
         ascending: bool = False,
         table_rows: int = 10,
         figsize: Tuple[float, float] = (19.2, 10.8)) -> Figure:
+    """
+    Plot a composite bubble chart with additional tables for top and bottom values.
 
+    Parameters:
+    pd_df (pd.DataFrame): 
+        The pandas DataFrame containing the data to be plotted.
+    label (str): 
+        The column name for the bubble labels.
+    x (str): 
+        The column name for the x-axis values.
+    y (str): 
+        The column name for the y-axis values.
+    z (str): 
+        The column name for the bubble sizes.
+    title (Optional[str]): 
+        The title of the plot. Default is "Test".
+    style (StyleTemplate): 
+        A StyleTemplate object to define the visual style of the plot. Default is BUBBLE_STYLE_TEMPLATE.
+    max_values (int): 
+        The maximum number of values to display in the bubble chart. Default is 50.
+    center_to_mean (bool): 
+        A flag indicating whether to center the bubbles to the mean. Default is False.
+    filter_by (Optional[str]): 
+        The column name to filter the data by. Default is None.
+    sort_by (Optional[str]): 
+        The column name to sort the data by. Default is None.
+    ascending (bool): 
+        A flag indicating whether to sort in ascending order. Default is False.
+    table_rows (int): 
+        The number of rows to display in the tables. Default is 10.
+    figsize (Tuple[float, float]): 
+        The size of the figure. Default is (19.2, 10.8).
+
+    Returns:
+    Figure: 
+        The matplotlib figure object containing the composite bubble chart and tables.
+
+    Example:
+    >>> df = pd.DataFrame({
+    ...     "Label": ["A", "B", "C"],
+    ...     "X": [1, 2, 3],
+    ...     "Y": [4, 5, 6],
+    ...     "Z": [7, 8, 9]
+    ... })
+    >>> fig = plot_composite_bubble(df, label="Label", x="X", y="Y", z="Z")
+    >>> fig.show()
+    """
     validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
 
     if not sort_by:
@@ -90,35 +136,60 @@ def plot_composite_bubble(
     return fig
 
 
-def plot_composite_treemap(pd_dfs: List[pd.DataFrame],
-                   path: str,
-                   values: str,
-                   style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
-                   title: Optional[str] = None,
-                   color: Optional[str] = None,
-                   sort_by: Optional[str] = None,
-                   ascending: bool = False,
-                   max_values: int = 100) -> go.Figure:
+def plot_composite_treemap(pd_dfs: Dict[str, pd.DataFrame],
+                           values: str,
+                           style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
+                           title: Optional[str] = None,
+                           color: Optional[str] = None,
+                           sort_by: Optional[str] = None,
+                           ascending: bool = False,
+                           max_values: int = 100) -> Optional[go.Figure]:
+    """
+    Plot a composite treemap from multiple DataFrames.
+
+    Parameters:
+    pd_dfs (Dict[str, pd.DataFrame]): 
+        A dictionary where keys are dimension names and values are pandas DataFrames to be plotted.
+    values (str): 
+        The column name in each DataFrame that contains the values to be visualized in the treemap.
+    style (StyleTemplate): 
+        A StyleTemplate object to define the visual style of the treemap. Default is TREEMAP_STYLE_TEMPLATE.
+    title (Optional[str]): 
+        An optional title for the composite treemap plot. Default is None.
+    color (Optional[str]): 
+        An optional column name for coloring the treemap. Default is None.
+    sort_by (Optional[str]): 
+        An optional column name for sorting the treemap values. Default is None.
+    ascending (bool): 
+        A flag indicating whether to sort in ascending order. Default is False.
+    max_values (int): 
+        The maximum number of values to display in each treemap. Default is 100.
 
+    Returns:
+    Optional[go.Figure]: 
+        The composite treemap figure object or None if no DataFrames are provided.
+    """
     num_dimensions = len(pd_dfs)
     if num_dimensions > 0:
+        subplot_titles = [f"{title}::{dim.title()}" if title is not None else dim.title(
+        ) for dim in pd_dfs.keys()]
         fig = make_subplots(
             rows=num_dimensions,
             cols=1,
-            specs=[[{'type': 'domain'}] for _ in range(num_dimensions)],
-            vertical_spacing=0.02
+            subplot_titles=subplot_titles,
+            vertical_spacing=0.2
         )
-        current_row = 1
-        for pd_df in pd_dfs:
-            trm = aplot_treemap(pd_df=pd_df,
-                                path=path,
-                                values=values,
-                                title=title,
-                                style=style,
-                                color=color,
-                                sort_by=sort_by,
-                                ascending=ascending,
-                                max_values=max_values)
-            fig.add_trace(trm,row=current_row, col=1)
-            current_row += 1
-        return fig
+
+    current_row = 1
+    for path, df in pd_dfs.items():
+        trm = aplot_treemap(pd_df=df,
+                            path=path,
+                            values=values,
+                            style=style,
+                            color=color,
+                            sort_by=sort_by,
+                            ascending=ascending,
+                            max_values=max_values)
+        fig.add_trace(trm, row=current_row, col=1)
+        current_row += 1
+    return fig

MatplotLibAPI/StyleTemplate.py

@@ -10,9 +10,30 @@ from matplotlib.ticker import FuncFormatter
 
 # region Utils
 
+
 def validate_dataframe(pd_df: pd.DataFrame,
                        cols: List[str],
                        sort_by: Optional[str] = None):
+    """
+    Validate that specified columns exist in a pandas DataFrame and optionally check for a sorting column.
+
+    Parameters:
+    pd_df (pd.DataFrame): The pandas DataFrame to validate.
+    cols (List[str]): A list of column names that must exist in the DataFrame.
+    sort_by (Optional[str]): An optional column name that, if provided, must also exist in the DataFrame.
+
+    Raises:
+    AttributeError: If any of the specified columns or the sorting column (if provided) do not exist in the DataFrame.
+
+    Example:
+    >>> import pandas as pd
+    >>> data = {'A': [1, 2, 3], 'B': [4, 5, 6]}
+    >>> df = pd.DataFrame(data)
+    >>> validate_dataframe(df, ['A', 'B'])  # No error
+    >>> validate_dataframe(df, ['A', 'C'])  # Raises AttributeError
+    >>> validate_dataframe(df, ['A'], sort_by='B')  # No error
+    >>> validate_dataframe(df, ['A'], sort_by='C')  # Raises AttributeError
+    """
     _columns = cols.copy()
     if sort_by and sort_by not in _columns:
         _columns.append(sort_by)
@@ -27,6 +48,41 @@ def format_func(
         x: Optional[str] = None,
         y: Optional[str] = None,
         z: Optional[str] = None):
+    """
+    Update the formatting functions for specified keys if they exist in the provided format functions dictionary.
+
+    Parameters:
+    format_funcs (Optional[Dict[str, Optional[Callable[[Union[int, float, str]], str]]]]): 
+        A dictionary mapping keys to formatting functions. The keys can be 'label', 'x', 'y', and 'z'.
+    label (Optional[str]): 
+        The key to update with the 'label' formatting function from the dictionary.
+    x (Optional[str]): 
+        The key to update with the 'x' formatting function from the dictionary.
+    y (Optional[str]): 
+        The key to update with the 'y' formatting function from the dictionary.
+    z (Optional[str]): 
+        The key to update with the 'z' formatting function from the dictionary.
+
+    Returns:
+    Optional[Dict[str, Optional[Callable[[Union[int, float, str]], str]]]]:
+        The updated dictionary with the specified keys pointing to their corresponding formatting functions.
+
+    Example:
+    >>> format_funcs = {
+    ...     "label": lambda x: f"Label: {x}",
+    ...     "x": lambda x: f"X-axis: {x}",
+    ...     "y": lambda y: f"Y-axis: {y}",
+    ... }
+    >>> updated_funcs = format_func(format_funcs, label="new_label", x="new_x")
+    >>> print(updated_funcs)
+    {
+        "label": lambda x: f"Label: {x}",
+        "x": lambda x: f"X-axis: {x}",
+        "y": lambda y: f"Y-axis: {y}",
+        "new_label": lambda x: f"Label: {x}",
+        "new_x": lambda x: f"X-axis: {x}",
+    }
+    """
 
     if label and "label" in format_funcs:
         format_funcs[label] = format_funcs["label"]
@@ -64,13 +120,52 @@ class StyleTemplate:
     palette: str = PALETTE
     legend: bool = True
     xscale: Optional[str] = None
-    x_ticks: int = 10
+    x_ticks: int = 5
     yscale: Optional[str] = None
     y_ticks: int = 5
     format_funcs: Optional[Dict[str, Optional[Callable[[
         Union[int, float, str]], str]]]] = None
     col_widths: Optional[List[float]] = None
-
+    """
+    A class to define style templates for data visualization with customizable attributes.
+
+    Attributes:
+    background_color (str): 
+        The background color for the visualizations. Default is BACKGROUND_COLOR.
+    fig_border (str): 
+        The border color for the figures. Default is BACKGROUND_COLOR.
+    font_name (str): 
+        The name of the font to use. Default is 'Arial'.
+    font_size (int): 
+        The base size of the font. Default is FONT_SIZE.
+    font_color (str): 
+        The color of the font. Default is TEXT_COLOR.
+    palette (str): 
+        The color palette to use. Default is PALETTE.
+    legend (bool): 
+        A flag to determine if the legend should be displayed. Default is True.
+    xscale (Optional[str]): 
+        The scale type for the x-axis. Default is None.
+    x_ticks (int): 
+        The number of ticks on the x-axis. Default is 10.
+    yscale (Optional[str]): 
+        The scale type for the y-axis. Default is None.
+    y_ticks (int): 
+        The number of ticks on the y-axis. Default is 5.
+    format_funcs (Optional[Dict[str, Optional[Callable[[Union[int, float, str]], str]]]]): 
+        A dictionary mapping data keys to formatting functions. Default is None.
+    col_widths (Optional[List[float]]): 
+        A list of column widths. Default is None.
+
+    Properties:
+    font_mapping (dict): 
+        A dictionary mapping font size levels to specific font sizes.
+
+    Example:
+    >>> template = StyleTemplate()
+    >>> template.font_mapping
+    {0: FONT_SIZE-3, 1: FONT_SIZE-1, 2: FONT_SIZE, 3: FONT_SIZE+1, 4: FONT_SIZE+3}
+    """
     @property
     def font_mapping(self):
         return {0: self.font_size-3,
@@ -81,11 +176,37 @@ class StyleTemplate:
 
 
 class DynamicFuncFormatter(FuncFormatter):
+    """
+    A class to create a dynamic function formatter for matplotlib plots.
+
+    Inherits from:
+    FuncFormatter: A base class from matplotlib for formatting axis ticks.
+
+    Parameters:
+    func_name (Callable): The function to be used for formatting.
+
+    Example:
+    >>> formatter = DynamicFuncFormatter(percent_formatter)
+    """
     def __init__(self, func_name):
         super().__init__(func_name)
 
 
 def percent_formatter(val, pos: Optional[int] = None):
+    """
+    Format a value as a percentage.
+
+    Parameters:
+    val (float): The value to format.
+    pos (Optional[int]): The position (not used).
+
+    Returns:
+    str: The formatted percentage string.
+
+    Example:
+    >>> percent_formatter(0.005)
+    '1%'
+    """
     if val*100 <= 0.1:  # For 0.1%
         return f"{val*100:.2f}%"
     elif val*100 <= 1:  # For 1%
@@ -95,6 +216,20 @@ def percent_formatter(val, pos: Optional[int] = None):
 
 
 def bmk_formatter(val, pos: Optional[int] = None):
+    """
+    Format a value as billions, millions, or thousands.
+
+    Parameters:
+    val (float): The value to format.
+    pos (Optional[int]): The position (not used).
+
+    Returns:
+    str: The formatted string with B, M, or K suffix.
+
+    Example:
+    >>> bmk_formatter(1500000)
+    '1.5M'
+    """
     if val >= 1_000_000_000:  # Billions
         return f"{val / 1_000_000_000:.2f}B"
     elif val >= 1_000_000:  # Millions
@@ -106,26 +241,93 @@ def bmk_formatter(val, pos: Optional[int] = None):
 
 
 def integer_formatter(value, pos: Optional[int] = None):
+    """
+    Format a value as an integer.
+
+    Parameters:
+    value (float): The value to format.
+    pos (Optional[int]): The position (not used).
+
+    Returns:
+    str: The formatted integer string.
+
+    Example:
+    >>> integer_formatter(42.9)
+    '42'
+    """
     return f"{int(value)}"
 
 
 def string_formatter(value, pos: Optional[int] = None):
+    """
+    Format a string by replacing '-' and '_' with spaces and capitalizing words.
+
+    Parameters:
+    value (str): The string to format.
+    pos (Optional[int]): The position (not used).
+
+    Returns:
+    str: The formatted string.
+
+    Example:
+    >>> string_formatter("example-string_formatter")
+    'Example String Formatter'
+    """
     return str(value).replace("-", " ").replace("_", " ").title()
 
 
 def yy_mm__formatter(x, pos: Optional[int] = None):
+    """
+    Format a date as 'YYYY-MM'.
+
+    Parameters:
+    x (float): The value to format.
+    pos (Optional[int]): The position (not used).
+
+    Returns:
+    str: The formatted date string.
+
+    Example:
+    >>> yy_mm__formatter(737060)
+    '2020-01'
+    """
     return num2date(x).strftime('%Y-%m')
 
 
 def yy_mm_dd__formatter(x, pos: Optional[int] = None):
+    """
+    Format a date as 'YYYY-MM-DD'.
+
+    Parameters:
+    x (float): The value to format.
+    pos (Optional[int]): The position (not used).
+
+    Returns:
+    str: The formatted date string.
+
+    Example:
+    >>> yy_mm_dd__formatter(737060)
+    '2020-01-01'
+    """
     return num2date(x).strftime('%Y-%m-%D')
 
 
-def percent_formatter(x,  pos: Optional[int] = None):
-    return f"{x * 100:.0f}%"
+def generate_ticks(min_val, max_val, num_ticks:int=5):
+    """
+    Generate tick marks for a given range.
+
+    Parameters:
+    min_val (Union[float, str]): The minimum value of the range.
+    max_val (Union[float, str]): The maximum value of the range.
+    num_ticks (int): The number of ticks to generate. Default is 10.
 
+    Returns:
+    np.ndarray: An array of tick marks.
 
-def generate_ticks(min_val, max_val, num_ticks="10"):
+    Example:
+    >>> generate_ticks(0, 100, 5)
+    array([  0.,  25.,  50.,  75., 100.])
+    """
     # Identify the type of the input
     try:
         min_val = float(min_val)

MatplotLibAPI/__init__.py

@@ -1,12 +1,12 @@
 
 from .StyleTemplate import StyleTemplate
 from .Bubble import aplot_bubble, fplot_bubble, BUBBLE_STYLE_TEMPLATE
-from .Composite import plot_composite_bubble
+from .Composite import plot_composite_bubble,plot_composite_treemap
 from .Timeserie import aplot_timeserie, fplot_timeserie, TIMESERIE_STYLE_TEMPLATE
 from .Table import aplot_table, fplot_table, TABLE_STYLE_TEMPLATE
 from .Network import aplot_network, aplot_network_components, fplot_network, NETWORK_STYLE_TEMPLATE
 from .Treemap import fplot_treemap, aplot_treemap, TREEMAP_STYLE_TEMPLATE
-from typing import List, Optional, Tuple
+from typing import List, Optional, Tuple,Dict
 import pandas as pd
 from pandas.api.extensions import register_dataframe_accessor
 
@@ -294,6 +294,30 @@ class DataFrameAccessor:
                              ascending=ascending,
                              max_values=max_values)
 
+    def fplot_composite_treemap(self,
+                      pathes: List[str],
+                      values: str,
+                      style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
+                      title: Optional[str] = None,
+                      color: Optional[str] = None,
+                      sort_by: Optional[str] = None,
+                      max_values: int = 100,
+                      ascending: bool = False,
+                      fig: Optional[go.Figure] = None) -> go.Figure:
+        pd_dfs:Dict[str,pd.DataFrame]={}
+        for path in pathes:
+            pd_dfs[path]=self._obj
+
+
+        return plot_composite_treemap(pd_dfs=pd_dfs,
+                             values=values,
+                             title=title,
+                             style=style,
+                             color=color,
+                             sort_by=sort_by,
+                             ascending=ascending,
+                             max_values=max_values)
+
 
 __all__ = ["validate_dataframe", "aplot_bubble", "aplot_timeserie", "aplot_table", "aplot_network", "aplot_network_components", "fplot_network",
-           "plot_pivotbar", "fplot_treemap", "aplot_treemap", "plot_composite_bubble", "StyleTemplate", "DataFrameAccessor"]
+           "plot_pivotbar", "fplot_treemap", "aplot_treemap", "plot_composite_bubble","plot_composite_treemap", "StyleTemplate", "DataFrameAccessor"]

{MatplotLibAPI-3.2.8.dist-info → MatplotLibAPI-3.2.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: MatplotLibAPI
-Version: 3.2.8
+Version: 3.2.9
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE

MatplotLibAPI-3.2.9.dist-info/RECORD

@@ -0,0 +1,14 @@
+MatplotLibAPI/Bubble.py,sha256=ZtOTWGAnJ1zy7bjKQ3OF985R-iZHvZOo_rG1dZMbP-Q,5116
+MatplotLibAPI/Composite.py,sha256=i6rgqcmywm1tq7gf9Zjm_jKIgiBia82QVWFbNT0Lv3I,7150
+MatplotLibAPI/Network.py,sha256=zzizLBAMD-nV-1WGZTIoOQn3SVsvr9R8Ba2DTCyuTvA,18790
+MatplotLibAPI/Pivot.py,sha256=Bo7ZpkxqoE75e8vpSsKIT5X2Q7lLdfAyy46ox1fARbc,7183
+MatplotLibAPI/StyleTemplate.py,sha256=YtDsDIEYjpHqLuj1YXlmLUbBdxHfoq7ndQ1sG4WD1IA,10967
+MatplotLibAPI/Table.py,sha256=p_nHXRiC6dneBSf0j5nx-hBijBSXd7NBLmdBicFUGqQ,2809
+MatplotLibAPI/Timeserie.py,sha256=B03xjcBCgWVpkDQKvoyGtNjm6OLtCo1fINyXJrXeWM8,4952
+MatplotLibAPI/Treemap.py,sha256=1WYHV9eaU4zcXrwTIScQvsGrfgiuYg-aAoeIhTZVPKw,3395
+MatplotLibAPI/__init__.py,sha256=5a9TvLliMN0o-1V8Lw0Gj0JSQMXh8jTWxxgLcxIhLxU,13948
+MatplotLibAPI-3.2.9.dist-info/LICENSE,sha256=hMErKLb6YZR3lRR5zr-vxeFkvY69QAaafgSpZ5-P1dQ,1067
+MatplotLibAPI-3.2.9.dist-info/METADATA,sha256=Ep-K8MSVrt_DkVDg-JFQDtB7ttaGuczFc0CNSdjunz0,462
+MatplotLibAPI-3.2.9.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+MatplotLibAPI-3.2.9.dist-info/top_level.txt,sha256=MrzbBjDEW48Vb6YhQIqpFYGOhHzQnEIM5Qy2xy2iqew,14
+MatplotLibAPI-3.2.9.dist-info/RECORD,,

MatplotLibAPI-3.2.8.dist-info/RECORD

@@ -1,14 +0,0 @@
-MatplotLibAPI/Bubble.py,sha256=ZtOTWGAnJ1zy7bjKQ3OF985R-iZHvZOo_rG1dZMbP-Q,5116
-MatplotLibAPI/Composite.py,sha256=YpC4VxYX4nMgiiV8ic734c_NGaCTdQCptT8bpMdTqCQ,4222
-MatplotLibAPI/Network.py,sha256=zzizLBAMD-nV-1WGZTIoOQn3SVsvr9R8Ba2DTCyuTvA,18790
-MatplotLibAPI/Pivot.py,sha256=Bo7ZpkxqoE75e8vpSsKIT5X2Q7lLdfAyy46ox1fARbc,7183
-MatplotLibAPI/StyleTemplate.py,sha256=va8_yXaun1RnjQUOEHGvsXJrKWHdzz4BhnY0CkROLW8,4599
-MatplotLibAPI/Table.py,sha256=p_nHXRiC6dneBSf0j5nx-hBijBSXd7NBLmdBicFUGqQ,2809
-MatplotLibAPI/Timeserie.py,sha256=B03xjcBCgWVpkDQKvoyGtNjm6OLtCo1fINyXJrXeWM8,4952
-MatplotLibAPI/Treemap.py,sha256=1WYHV9eaU4zcXrwTIScQvsGrfgiuYg-aAoeIhTZVPKw,3395
-MatplotLibAPI/__init__.py,sha256=-NgOIPG0P7G4pllESRsrOzcKgT0u-ZSE04AHRk-8Aas,12918
-MatplotLibAPI-3.2.8.dist-info/LICENSE,sha256=hMErKLb6YZR3lRR5zr-vxeFkvY69QAaafgSpZ5-P1dQ,1067
-MatplotLibAPI-3.2.8.dist-info/METADATA,sha256=X-bNBBQloDBC8Np3t6YsFWi3AjJ3AG_OOH9GdEJAudU,462
-MatplotLibAPI-3.2.8.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-MatplotLibAPI-3.2.8.dist-info/top_level.txt,sha256=MrzbBjDEW48Vb6YhQIqpFYGOhHzQnEIM5Qy2xy2iqew,14
-MatplotLibAPI-3.2.8.dist-info/RECORD,,