steer-core 0.1.16__py3-none-any.whl → 0.1.17__py3-none-any.whl

steer_core/Mixins/Plotter.py

@@ -0,0 +1,149 @@
+import plotly.graph_objects as go
+from typing import Dict, Any, Tuple, List, Union
+
+
+class PlotterMixin:
+    
+    @staticmethod
+    def plot_breakdown_sunburst(
+        breakdown_dict: Dict[str, Any],
+        title: str = "Breakdown",
+        root_label: str = "Total",
+        unit: str = "",
+        **kwargs,
+    ) -> go.Figure:
+        """
+        Create a sunburst plot for any generic nested breakdown dictionary.
+
+        Parameters
+        ----------
+        breakdown_dict : Dict[str, Any]
+            Nested dictionary where values can be either numbers or nested dictionaries.
+            Each nesting level becomes a ring in the sunburst plot.
+        title : str, optional
+            Title for the plot. Defaults to "Breakdown".
+        root_label : str, optional
+            Label for the root node. Defaults to "Total".
+        unit : str, optional
+            Unit string to display in hover text (e.g., "g", "kg", "%"). Defaults to "".
+
+        Returns
+        -------
+        go.Figure
+            Plotly sunburst figure
+        """
+
+        def _flatten_breakdown_values(data: Dict[str, Any]) -> List[float]:
+            """Recursively flatten all numeric values from nested breakdown dictionary"""
+            values = []
+            for value in data.values():
+                if isinstance(value, dict):
+                    values.extend(_flatten_breakdown_values(value))
+                elif isinstance(value, (int, float)):
+                    values.append(float(value))
+            return values
+
+        def _calculate_subtotal(data: Dict[str, Any]) -> float:
+            """Calculate the total value for a dictionary (sum of all nested numeric values)"""
+            total = 0.0
+            for value in data.values():
+                if isinstance(value, dict):
+                    total += _calculate_subtotal(value)
+                elif isinstance(value, (int, float)):
+                    total += float(value)
+            return total
+
+        def _prepare_sunburst_data(
+            data: Dict[str, Any], parent_id: str = "", current_path: str = ""
+        ) -> Tuple[List[str], List[str], List[str], List[float]]:
+            """Recursively prepare data for sunburst plot with proper hierarchy"""
+            ids = []
+            labels = []
+            parents = []
+            values = []
+
+            for key, value in data.items():
+                # Create unique ID for this node
+                node_id = f"{current_path}/{key}" if current_path else key
+
+                ids.append(node_id)
+                labels.append(key)
+                parents.append(parent_id)
+
+                if isinstance(value, dict):
+                    # This is a nested dictionary - calculate its total value
+                    subtotal = _calculate_subtotal(value)
+                    values.append(subtotal)
+
+                    # Recursively process nested dictionary
+                    (
+                        nested_ids,
+                        nested_labels,
+                        nested_parents,
+                        nested_values,
+                    ) = _prepare_sunburst_data(
+                        value, parent_id=node_id, current_path=node_id
+                    )
+
+                    # Add nested data to our lists
+                    ids.extend(nested_ids)
+                    labels.extend(nested_labels)
+                    parents.extend(nested_parents)
+                    values.extend(nested_values)
+
+                elif isinstance(value, (int, float)):
+                    # This is a leaf node with a numeric value
+                    values.append(float(value))
+
+            return ids, labels, parents, values
+
+        # Calculate total value for root node
+        total_value = _calculate_subtotal(breakdown_dict)
+
+        # Prepare hierarchical data starting with root
+        ids, labels, parents, values = _prepare_sunburst_data(
+            breakdown_dict, parent_id=""
+        )
+
+        # Add root node at the beginning
+        ids.insert(0, root_label)
+        labels.insert(0, root_label)
+        parents.insert(0, "")
+        values.insert(0, total_value)
+
+        # Update parent references to point to root
+        for i in range(1, len(parents)):
+            if parents[i] == "":
+                parents[i] = root_label
+
+        # Create custom hover text with percentages
+        hover_text = []
+        for i, (label, value) in enumerate(zip(labels, values)):
+            if label == root_label:
+                unit_str = f" {unit}" if unit else ""
+                hover_text.append(f"<b>{root_label}</b><br>{value:.2f}{unit_str}")
+            else:
+                percentage = (value / total_value * 100) if total_value > 0 else 0
+                unit_str = f" {unit}" if unit else ""
+                hover_text.append(
+                    f"<b>{label}</b><br>{value:.2f}{unit_str}<br>{percentage:.1f}% of total"
+                )
+
+        # Create the sunburst plot
+        fig = go.Figure(
+            go.Sunburst(
+                ids=ids,
+                labels=labels,
+                parents=parents,
+                values=values,
+                branchvalues="total",
+                hovertemplate="%{customdata}<extra></extra>",
+                customdata=hover_text,
+            )
+        )
+
+        fig.update_layout(
+            title=dict(text=title, x=0.5, font=dict(size=16)), font_size=12, **kwargs
+        )
+
+        return fig

steer_core/Mixins/Serializer.py

@@ -5,24 +5,23 @@ from copy import deepcopy
 
 
 class SerializerMixin:
-
     def serialize(self) -> str:
         """
         Serialize an object to a string representation.
-        
+
         Parameters
         ----------
         obj : Type
             The object to serialize.
-        
+
         Returns
         -------
         str
             The serialized string representation of the object.
         """
         pickled = dumps(self)
-        based = base64.b64encode(pickled).decode('utf-8')
-        return based 
+        based = base64.b64encode(pickled).decode("utf-8")
+        return based
 
     @staticmethod
     def deserialize(String: str) -> Type:
@@ -39,7 +38,6 @@ class SerializerMixin:
         SerializerMixin
             The deserialized object.
         """
-        decoded = base64.b64decode(String.encode('utf-8'))
+        decoded = base64.b64decode(String.encode("utf-8"))
         obj = deepcopy(loads(decoded))
         return obj
-    

steer_core/Mixins/TypeChecker.py

@@ -3,14 +3,10 @@ import pandas as pd
 import numpy as np
 
 
-ALLOWED_REFERENCE = [
-    'Na/Na+',
-    'Li/Li+'
-]
+ALLOWED_REFERENCE = ["Na/Na+", "Li/Li+"]
 
 
 class ValidationMixin:
-
     @staticmethod
     def validate_type(value: Type, expected_type: Type, name: str) -> None:
         """
@@ -31,7 +27,9 @@ class ValidationMixin:
             If the value is not of the expected type.
         """
         if not isinstance(value, expected_type):
-            raise TypeError(f"{name} must be of type {expected_type.__name__}. Provided: {type(value).__name__}.")
+            raise TypeError(
+                f"{name} must be of type {expected_type.__name__}. Provided: {type(value).__name__}."
+            )
 
     @staticmethod
     def validate_percentage(value: float, name: str) -> None:
@@ -54,7 +52,9 @@ class ValidationMixin:
             raise TypeError(f"{name} must be a number. Provided: {value}.")
 
         if not (0 <= value <= 100):
-            raise ValueError(f"{name} must be a percentage between 0 and 100. Provided: {value}.")
+            raise ValueError(
+                f"{name} must be a percentage between 0 and 100. Provided: {value}."
+            )
 
     @staticmethod
     def validate_fraction(value: float, name: str) -> None:
@@ -74,13 +74,13 @@ class ValidationMixin:
             If the value is not a fraction.
         """
         if not (0 <= value <= 1):
-            raise ValueError(f"{name} must be a fraction between 0 and 1. Provided: {value}.")
+            raise ValueError(
+                f"{name} must be a fraction between 0 and 1. Provided: {value}."
+            )
 
     @staticmethod
     def validate_pandas_dataframe(
-        df: pd.DataFrame, 
-        name: str,
-        column_names: list = None
+        df: pd.DataFrame, name: str, column_names: list = None
     ) -> None:
         """
         Validate that the input is a pandas DataFrame.
@@ -103,8 +103,10 @@ class ValidationMixin:
         if column_names is not None:
             missing_columns = [col for col in column_names if col not in df.columns]
             if missing_columns:
-                raise ValueError(f"{name} is missing required columns: {missing_columns}. "
-                                 f"Available columns: {df.columns.tolist()}.")
+                raise ValueError(
+                    f"{name} is missing required columns: {missing_columns}. "
+                    f"Available columns: {df.columns.tolist()}."
+                )
 
     @staticmethod
     def validate_electrochemical_reference(reference: str) -> None:
@@ -124,8 +126,10 @@ class ValidationMixin:
         ValidationMixin.validate_string(reference, "Electrochemical reference")
 
         if reference not in ALLOWED_REFERENCE:
-            raise ValueError(f"Invalid electrochemical reference: {reference}. "
-                             f"Must be one of {ALLOWED_REFERENCE}.")
+            raise ValueError(
+                f"Invalid electrochemical reference: {reference}. "
+                f"Must be one of {ALLOWED_REFERENCE}."
+            )
 
     @staticmethod
     def validate_datum(datum: np.ndarray) -> None:
@@ -144,10 +148,10 @@ class ValidationMixin:
         """
         if type(datum) is not tuple and len(datum) != 3:
             raise ValueError("Datum must be a 3D point with exactly 3 coordinates.")
-        
+
         if not all(isinstance(coord, (int, float)) for coord in datum):
             raise TypeError("All coordinates in datum must be numbers.")
-    
+
     @staticmethod
     def validate_positive_float(value: float, name: str) -> None:
         """
@@ -167,7 +171,7 @@ class ValidationMixin:
         """
         if not isinstance(value, (int, float)):
             raise ValueError(f"{name} must be a positive float. Provided: {value}.")
-        
+
     @staticmethod
     def validate_string(value: str, name: str) -> None:
         """
@@ -187,7 +191,7 @@ class ValidationMixin:
         """
         if not isinstance(value, str):
             raise TypeError(f"{name} must be a string. Provided: {value}.")
-        
+
     @staticmethod
     def validate_two_iterable_of_floats(value: tuple, name: str) -> None:
         """
@@ -207,16 +211,22 @@ class ValidationMixin:
         """
         # Accept both tuples and lists
         if not isinstance(value, (tuple, list)) or len(value) != 2:
-            raise TypeError(f"{name} must be a tuple or list of two numbers. Provided: {value}.")
-        
+            raise TypeError(
+                f"{name} must be a tuple or list of two numbers. Provided: {value}."
+            )
+
         # Check if all values are numeric (int or float)
         if not all(isinstance(v, (int, float)) for v in value):
-            raise TypeError(f"{name} must be a tuple or list of two numbers. Provided: {value}.")
-        
+            raise TypeError(
+                f"{name} must be a tuple or list of two numbers. Provided: {value}."
+            )
+
         # Check if all values are non-negative
         if not all(v >= 0 for v in value):
-            raise ValueError(f"{name} must be a tuple or list of two non-negative numbers. Provided: {value}.")
-        
+            raise ValueError(
+                f"{name} must be a tuple or list of two non-negative numbers. Provided: {value}."
+            )
+
     @staticmethod
     def validate_positive_float_list(value: list, name: str) -> None:
         """
@@ -234,9 +244,12 @@ class ValidationMixin:
         TypeError
             If the value is not a list of positive floats.
         """
-        if not isinstance(value, list) or not all(isinstance(v, (int, float)) and v > 0 for v in value):
-            raise TypeError(f"{name} must be a list of positive floats. Provided: {value}.")
-        
+        if not isinstance(value, list) or not all(
+            isinstance(v, (int, float)) and v > 0 for v in value
+        ):
+            raise TypeError(
+                f"{name} must be a list of positive floats. Provided: {value}."
+            )
+
         if len(value) == 0:
             raise ValueError(f"{name} must not be an empty list. Provided: {value}.")
-        

steer_core/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.16"
+__version__ = "0.1.17"

{steer_core-0.1.16.dist-info → steer_core-0.1.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steer-core
-Version: 0.1.16
+Version: 0.1.17
 Summary: Modelling energy storage from cell to site - STEER OpenCell Design
 Home-page: https://github.com/nicholas9182/steer-core/
 Author: Nicholas Siemons

steer_core-0.1.17.dist-info/RECORD

@@ -0,0 +1,34 @@
+steer_core/DataManager.py,sha256=06TrnBa4SLGvLeH2DacCxwGZ4zjLZslwNcwIlmfhxtA,10943
+steer_core/__init__.py,sha256=BzIjnki8Bz3evNWo6bjGxxpLhy_tN9MRYhtM0MnDiWs,23
+steer_core/Apps/ContextManagers.py,sha256=-ImT0O8BdmPKOd_e7wS6AWJMMQme7nGDEUdxTi_wv8s,1870
+steer_core/Apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Apps/Components/MaterialSelectors.py,sha256=LBf2PvHkyAXUoZgEhoJCfo5shEfaloa6l3PeOJAakFk,35707
+steer_core/Apps/Components/RangeSliderComponents.py,sha256=tixdJSC--0OaWgI6OEpNSFZCzvW0iedXIfNVoIdt2XA,22071
+steer_core/Apps/Components/SliderComponents.py,sha256=BGv_yzXhWV_VJ8LE5P7__tMukOxIFjcuBGHwl0oi3-Y,27600
+steer_core/Apps/Components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Apps/Performance/CallbackTimer.py,sha256=Dh1dWvgX_LownO_UBmlBtUwl5XRb4sQ5kpzSqLXK2G8,387
+steer_core/Apps/Performance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Apps/Utils/SliderControls.py,sha256=jSjYZBWE9A9uzFDJjHBjP0RND9DeKUKm0V3ovDoeezo,27008
+steer_core/Apps/Utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Constants/Units.py,sha256=SPwPK13dHE3ua_e4F8yz-sLDOYgWalWRa-tPL7Yc-vQ,619
+steer_core/Constants/Universal.py,sha256=5FWdrex5NiI2DResDmwO7GIvGN2B0DNtdlG1l-ysDh8,41
+steer_core/Constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/ContextManagers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Data/database.db,sha256=lCRyt-d92hq_yWMLmPVNvyjknMCznxkAf54eDX2iz90,13615104
+steer_core/Decorators/Coordinates.py,sha256=MxUWXQNrR9Q0_p4gGAywS4qnPAztajJzSay1Cu6lCRQ,1441
+steer_core/Decorators/Electrochemical.py,sha256=YDXzYxrIpbMMViK2y56UHZHb6Y4bDSIeXSVeP8VtYr4,990
+steer_core/Decorators/General.py,sha256=y1azWe4Ja9BP5vHn2gqwIpHVs11xQ1WKdqOc9v_uegs,969
+steer_core/Decorators/Objects.py,sha256=aYaRQBFgdSE0IB4QgBVfb6GhEPagoU6TRNrW_pOaqQI,506
+steer_core/Decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core/Mixins/Colors.py,sha256=vbo44Fr0oeziwHJ-tu7ojG-GzqFc2LBcT_hH4szvPFc,6796
+steer_core/Mixins/Coordinates.py,sha256=irdrrXIm7lmjMqgXyRXmu-x5swNQHhR7S0EZTBhvV8U,12824
+steer_core/Mixins/Data.py,sha256=2SXRIExCmd98N5JtNEFCQ9poi94fRF_GV5TNYjEGy6o,1363
+steer_core/Mixins/Plotter.py,sha256=zYj-P9ryhSUe5mHoIyjasZSOnY5sDCFKx6u73E8rFZc,5424
+steer_core/Mixins/Serializer.py,sha256=VC3sqfPMR8BxBC7WaDO6cCDpVAgLV8MKAVZtiX953gQ,1016
+steer_core/Mixins/TypeChecker.py,sha256=YXvM3s0NIMGf8Dyk7xWgEMUak-tkuPxNK7ZgmefRUoE,7577
+steer_core/Mixins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steer_core-0.1.17.dist-info/METADATA,sha256=TARSguSAGdeKSpug0Dh5as4CxsD6vSgkla5r1gaebSA,704
+steer_core-0.1.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+steer_core-0.1.17.dist-info/top_level.txt,sha256=6LFpGCSDE_SqRoT7raeM3Ax7KTBKQnyXLXxM9kXtw5M,11
+steer_core-0.1.17.dist-info/RECORD,,

steer_core-0.1.16.dist-info/RECORD

@@ -1,33 +0,0 @@
-steer_core/DataManager.py,sha256=KKpN8GiVHm8xfUmjHKgfLt_xRXT--dhNX8gxs022VHs,11156
-steer_core/__init__.py,sha256=yF88-8vL8keLe6gCTumymw0UoMkWkSrJnzLru4zBCLQ,23
-steer_core/Apps/ContextManagers.py,sha256=p3_m6cio2bobP0gg03Iu18XRPHTeIsoZasf5TnLsvZg,1810
-steer_core/Apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Apps/Components/MaterialSelectors.py,sha256=KVDhOK5c0LT-2z9_o_QYdk6wsDjPEZ0Wb4xHXOjZvNc,31715
-steer_core/Apps/Components/RangeSliderComponents.py,sha256=At-xmyIS9GEAO7MzWXc4vwwzY-zqwNKdGHYkXSUIDck,21732
-steer_core/Apps/Components/SliderComponents.py,sha256=SQRt8LQxNHCeif70CF4cgx-Cvwx_poUSweu86qYJBlA,27680
-steer_core/Apps/Components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Apps/Performance/CallbackTimer.py,sha256=wFbW2_nl6KdEKrtdviOh5y66ZQlbVf0ZDHm-SZBjbYg,390
-steer_core/Apps/Performance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Apps/Utils/SliderControls.py,sha256=NyX1BN4XJmeDD1MhfKfFyVjo8VvfRn68WRuFhXkTxS8,26971
-steer_core/Apps/Utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Constants/Units.py,sha256=Bdlv_APY2-kbKva3FW4jA0srTbavqAumrEaaQ6HNKuU,489
-steer_core/Constants/Universal.py,sha256=5FWdrex5NiI2DResDmwO7GIvGN2B0DNtdlG1l-ysDh8,41
-steer_core/Constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/ContextManagers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Data/database.db,sha256=bcjSOuGjuWuCvWyZttRTIiz251hAvYs4xdScwpfwzy8,13615104
-steer_core/Decorators/Coordinates.py,sha256=qo79PlA8ZZ6QY-VvH9YGg27gqpVJ2-Xa3blyoQVCp7A,1436
-steer_core/Decorators/Electrochemical.py,sha256=fAy89aw3zspBu_8UPa5kEhUpvO-bYpM0xH1r6O6mSiA,985
-steer_core/Decorators/General.py,sha256=-Wu-kTC9JAokicgt_nvANR7zpbCBPNR1kDmY6jzHfy4,966
-steer_core/Decorators/Objects.py,sha256=xiQfFgyTY2k8MF4lWojHMWbUMzojpyt8fRGl5bTNze8,503
-steer_core/Decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core/Mixins/Colors.py,sha256=rJnXyUb9hdy3SkzrPV9dXvnBFZ1funYRF8Q0EZr3vZA,1152
-steer_core/Mixins/Coordinates.py,sha256=lxToydRFDiRkHdA2sOJKZnu44ztbNfURV6aza5eMGtE,12969
-steer_core/Mixins/Data.py,sha256=wdNedZHS5Q7B-pCIoEbqTWMcxsC91CVn9pbQ2Zszg3w,1363
-steer_core/Mixins/Serializer.py,sha256=x-aX8BcFSh5egZdkKinYMmIHLqZymCnETNUld3hzgnk,1039
-steer_core/Mixins/TypeChecker.py,sha256=wmsDMYhjAynMQFN_7VixcyzKiin3WyklGT4JuJtxnm0,7400
-steer_core/Mixins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steer_core-0.1.16.dist-info/METADATA,sha256=qU1QQDw2n9OQGXHSBQ3XGSAtZJcW26OdsDHyiLTtU-0,704
-steer_core-0.1.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-steer_core-0.1.16.dist-info/top_level.txt,sha256=6LFpGCSDE_SqRoT7raeM3Ax7KTBKQnyXLXxM9kXtw5M,11
-steer_core-0.1.16.dist-info/RECORD,,