l4v1 0.0.1__tar.gz

l4v1-0.0.1/.gitignore

@@ -0,0 +1,160 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

l4v1-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12.2

l4v1-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

l4v1-0.0.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: l4v1
+Version: 0.0.1
+Summary: Add your description here
+Author-email: Miro Lavi <mirolavi@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: plotly>=5.21.0
+Requires-Dist: polars>=0.20.21
+Description-Content-Type: text/markdown
+
+# l4v1-analytics

l4v1-0.0.1/README.md

@@ -0,0 +1 @@
+# l4v1-analytics

l4v1-0.0.1/TESTING.py

@@ -0,0 +1,25 @@
+from l4v1.impact_analysis import impact_plot, impact_table
+import polars as pl
+
+df = pl.scan_parquet("data/supermarket_sales.parquet").with_columns(
+    pl.col(pl.Categorical).cast(pl.Utf8)
+)
+
+sales_week5 = df.filter(pl.col("Datetime").dt.week() == 5)
+sales_week6 = df.filter(pl.col("Datetime").dt.week() == 6)
+
+impact_table_df = impact_table(
+    df_primary=sales_week6,
+    df_comparison=sales_week5,
+    group_by_columns=["Branch", "Product line"],
+    volume_metric_name="Quantity",
+    outcome_metric_name="Total",
+)
+
+impact_plot(
+    impact_table=impact_table_df,
+    format_data_labels="{:,.0f}",
+    primary_total_label="Test1",
+    comparison_total_label="Test2",
+    title="Detailed Impact Analysis"
+)

l4v1-0.0.1/l4v1/impact_analysis.py

@@ -0,0 +1,406 @@
+import polars as pl
+import polars.selectors as cs
+import plotly.graph_objects as go
+from typing import Any, Callable, Dict, List, Tuple, Union, Optional
+
+
+def _group_dataframe(
+    lf: pl.LazyFrame,
+    group_by_columns: List[str],
+    metric_names: List[str],
+) -> pl.LazyFrame:
+    transformed_cols = [
+        pl.col(col_name).cast(pl.Utf8).alias(col_name) for col_name in group_by_columns
+    ]
+    agg_expressions = [pl.col(metric).sum().cast(pl.Float64) for metric in metric_names]
+    return lf.group_by(transformed_cols).agg(agg_expressions)
+
+
+def _get_join_key_expression(group_by_columns: List[str]) -> pl.Expr:
+    group_keys = list()
+
+    for join_key in group_by_columns:
+        temp_expr = (
+            pl.when(pl.col(join_key).is_null())
+            .then(pl.col(f"{join_key}_comparison"))
+            .otherwise(join_key)
+        ).str.to_lowercase()
+
+        group_keys.append(temp_expr)
+
+    # Concatenate unique values returned by each expression
+    expr = pl.concat_str(*group_keys, separator="|").alias("group_keys")
+
+    return expr
+
+
+def _get_impact_expressions(
+    volume_metric_name: str,
+    outcome_metric_name: str,
+) -> Tuple[pl.Expr, pl.Expr, pl.Expr, pl.Expr, pl.Expr]:
+    # Volume
+    volume_new = pl.col(volume_metric_name)
+    volume_comparison = pl.col(f"{volume_metric_name}_comparison")
+    volume_diff = volume_new - volume_comparison
+
+    # Outcome
+    outcome_new = pl.col(outcome_metric_name)
+    outcome_comparison = pl.col(f"{outcome_metric_name}_comparison")
+
+    # Rate
+    rate_new = outcome_new / volume_new
+    rate_comparison = outcome_comparison / volume_comparison
+    rate_avg_comparison = outcome_comparison.sum() / volume_comparison.sum()
+
+    # Impact Expressions
+    rate_impact = (rate_new - rate_comparison) * volume_new
+    volume_impact = volume_diff * rate_avg_comparison
+    mix_impact = (rate_comparison - rate_avg_comparison) * volume_diff
+
+    def impact_expression(expr: pl.Expr, name: str) -> pl.Expr:
+        expr = (
+            pl.when((outcome_comparison.is_null()) | (outcome_new.is_null()))
+            .then(pl.lit(0))
+            .otherwise(expr)
+        ).alias(f"{name}_impact")
+
+        return expr
+
+    rate_impact_expr = impact_expression(rate_impact, "rate")
+    volume_impact_expr = impact_expression(volume_impact, "volume")
+    mix_impact_expr = impact_expression(mix_impact, "mix")
+
+    new_impact = (
+        pl.when((outcome_comparison.is_null()) & (outcome_new.is_not_null()))
+        .then(outcome_new)
+        .otherwise(pl.lit(0))
+        .alias("new_impact")
+    )
+    old_impact = (
+        pl.when((outcome_new.is_null()) & (outcome_comparison.is_not_null()))
+        .then((outcome_comparison * -1))
+        .otherwise(pl.lit(0))
+        .alias("old_impact")
+    )
+
+    return (
+        rate_impact_expr,
+        volume_impact_expr,
+        mix_impact_expr,
+        new_impact,
+        old_impact,
+    )
+
+
+def impact_table(
+    df_primary: Union[pl.LazyFrame, pl.DataFrame],
+    df_comparison: Union[pl.LazyFrame, pl.DataFrame],
+    group_by_columns: Union[str, List[str]],
+    volume_metric_name: str,
+    outcome_metric_name: str,
+) -> pl.DataFrame:
+    """
+    Generates a table with impact analysis results from primary and comparison data frames.
+
+    Parameters
+    ----------
+    df_primary : Union[pl.LazyFrame, pl.DataFrame]
+        The primary dataset to analyze.
+    df_comparison : Union[pl.LazyFrame, pl.DataFrame]
+        The dataset to compare against the primary dataset.
+    group_by_columns : Union[str, List[str]]
+        Column name(s) used to group data. Can be a single column name or a list of names.
+    volume_metric_name : str
+        The name of the column in the data frame that represents the volume metric.
+    outcome_metric_name : str
+        The name of the column in the data frame that represents the outcome metric.
+
+    Returns
+    -------
+    pl.DataFrame
+        A Polars DataFrame containing the results of the impact analysis.
+
+    Raises
+    ------
+    TypeError
+        If the input data frames are not Polars DataFrame or LazyFrame types.
+    ValueError
+        If any of the parameters are missing or if the 'group_by_columns' contains non-string types.
+    """
+    # Ensure polars df type and convert to lazy
+    if not all(
+        isinstance(item, (pl.LazyFrame, pl.DataFrame))
+        for item in (df_primary, df_comparison)
+    ):
+        raise TypeError(
+            "df_primary and df_comparison must be Polars LazyFrame or DataFrame"
+        )
+    if isinstance(df_primary, pl.DataFrame):
+        df_primary = df_primary.lazy()
+    if isinstance(df_comparison, pl.DataFrame):
+        df_comparison = df_comparison.lazy()
+
+    # Validate group_by_columns
+    if isinstance(group_by_columns, str):
+        group_by_columns = [group_by_columns]
+    elif isinstance(group_by_columns, list):
+        if not all(isinstance(col, str) for col in group_by_columns):
+            raise ValueError("All elements in group_by_columns must be strings.")
+    else:
+        raise TypeError(
+            "group_by_columns must be a list of strings or a single string."
+        )
+
+    # Check metric column names are string types
+    if not all(
+        isinstance(item, str) for item in (volume_metric_name, outcome_metric_name)
+    ):
+        raise TypeError("volume_metric_name and outcome_metric_name must be strings.")
+
+    df_primary, df_comparison = [
+        _group_dataframe(
+            df,
+            group_by_columns,
+            [volume_metric_name, outcome_metric_name],
+        )
+        for df in [df_primary, df_comparison]
+    ]
+
+    impact_expressions = _get_impact_expressions(
+        volume_metric_name, outcome_metric_name
+    )
+
+    impact_table = (
+        df_primary.join(
+            df_comparison, how="outer", on=group_by_columns, suffix="_comparison"
+        )
+        .select(
+            _get_join_key_expression(group_by_columns),
+            cs.numeric(),
+            *impact_expressions,
+        )
+        .with_columns(cs.numeric().fill_nan(0).fill_null(0))
+        .sort(by="group_keys")
+    )
+
+    return impact_table.collect()
+
+
+def _parse_metric_column_names(impact_table: pl.LazyFrame) -> tuple:
+    metric_columns = impact_table.select(cs.ends_with("_comparison")).columns
+    volume_col = metric_columns[0]
+    outcome_col = metric_columns[1]
+
+    volume_col_stripped = (
+        volume_col.replace("_comparison", "")
+        if volume_col.endswith("_comparison")
+        else ValueError()
+    )
+    outcome_col_stripped = (
+        outcome_col.replace("_comparison", "")
+        if outcome_col.endswith("_comparison")
+        else ValueError()
+    )
+
+    return volume_col_stripped, outcome_col_stripped
+
+
+def _create_data_label(
+    value: float, previous_value: float, format_func: Callable
+) -> str:
+    formatted_value = format_func(value)
+    if previous_value is not None:
+        growth = value - previous_value
+        sign = "+" if growth >= 0 else ""
+        formatted_growth = f"{sign}{format_func(growth)}"
+        return f"{formatted_value} ({formatted_growth})"
+    return formatted_value
+
+
+def _prep_data_for_impact_plot(
+    impact_table: pl.DataFrame,
+    format_data_labels: Callable,
+    primary_total_label: str,
+    comparison_total_label: str,
+) -> Tuple[list, list, list, list]:
+    _, outcome_metric_name = _parse_metric_column_names(impact_table)
+    if format_data_labels is None:
+        format_data_labels = lambda value: f"{value:,.0f}"
+    primary_total_label = primary_total_label or outcome_metric_name
+    comparison_total_label = (
+        comparison_total_label or f"COMPARISON {outcome_metric_name}"
+    )
+
+    x_labels, y_values, data_labels, measure_list = [], [], [], []
+    outcome_comparison = impact_table.get_column(
+        f"{outcome_metric_name}_comparison"
+    ).sum()
+
+    x_labels.append(f"<b>{comparison_total_label}</b>".upper())
+    y_values.append(outcome_comparison)
+    data_labels.append(f"<b>{format_data_labels(outcome_comparison)}</b>")
+    measure_list.append("absolute")
+
+    cumulative_sum = outcome_comparison
+    previous_value = outcome_comparison
+
+    impact_types = ["rate", "volume", "mix", "old", "new"]
+    if (impact_table.get_column("old_impact").sum() == 0) & (
+        impact_table.get_column("new_impact").sum() == 0
+    ):
+        impact_types = ["rate", "volume", "mix"]
+
+    for impact_type in impact_types:
+        for key in impact_table.get_column("group_keys").unique().sort(descending=True):
+            impact_value = (
+                impact_table.filter(pl.col("group_keys") == key)
+                .get_column(f"{impact_type}_impact")
+                .sum()
+            )
+            # if impact_value != 0:
+            x_labels.append(f"{key} ({impact_type[0]}.)".lower())
+            y_values.append(impact_value)
+            data_labels.append(format_data_labels(impact_value))
+            measure_list.append("relative")
+            cumulative_sum += impact_value
+
+        x_labels.append(f"<b>{impact_type.capitalize()} Impact Subtotal</b>")
+        y_values.append(cumulative_sum)
+        data_labels.append(
+            _create_data_label(cumulative_sum, previous_value, format_data_labels)
+        )
+        measure_list.append("absolute")
+        previous_value = cumulative_sum
+
+    outcome_new = impact_table.get_column(outcome_metric_name).sum()
+    x_labels.append(f"<b>{primary_total_label}</b>".upper())
+    y_values.append(outcome_new)
+    data_labels.append(
+        f"<b>{_create_data_label(outcome_new, outcome_comparison, format_data_labels)}</b>"
+    )
+    measure_list.append("total")
+
+    return x_labels, y_values, data_labels, measure_list
+
+
+def impact_plot(
+    impact_table: pl.DataFrame,
+    primary_total_label: Optional[str] = None,
+    comparison_total_label: Optional[str] = None,
+    format_data_labels: Optional[str] = "{:,.0f}",
+    title: Optional[str] = None,
+    color_increase: Optional[str] = "#00AF00",
+    color_decrease: Optional[str] = "#FF0000",
+    color_total: Optional[str] = "#F1F1F1",
+    text_font_size: Optional[int] = 8,
+    plot_height: Optional[int] = None,
+    plot_width: Optional[int] = 750,
+    plotly_template: Optional[str] = "plotly_white",
+    plotly_trace_settings: Optional[Dict[str, Any]] = None,
+    plotly_layout_settings: Optional[Dict[str, Any]] = None,
+) -> go.Figure:
+    """
+    Creates a waterfall plot visualizing the impact analysis results.
+
+    Parameters
+    ----------
+    impact_table : pl.DataFrame
+        The DataFrame containing impact analysis results, as returned by the `impact_table` function.
+    primary_total_label : str, optional
+        Label for the total of the primary data set in the plot. Defaults to the outcome metric name.
+    comparison_total_label : str, optional
+        Label for the total of the comparison data set in the plot. Defaults to "COMPARISON <outcome_metric_name>".
+    format_data_labels : str, optional
+        Format specification for the data labels. Defaults to "{:,.0f}". This should be a string
+        following Python's string formatting syntax, which allows custom numeric formatting, e.g.,
+        "{:.2f}" for floating-point numbers with two decimals, or "{:,.2f}" for numbers with commas
+        as thousands separators and two decimals.
+    title : str, optional
+        The title of the plot.
+    color_increase : str, optional
+        Color for positive changes. Can be specified as a hexadecimal code (e.g., "#00AF00") or
+        a named Plotly color (e.g., "green"). Defaults to green "#00AF00".
+    color_decrease : str, optional
+        Color for negative changes. Can be specified as a hexadecimal code (e.g., "#FF0000") or
+        a named Plotly color (e.g., "red"). Defaults to red "#FF0000".
+    color_total : str, optional
+        Color for total columns. Can be specified as a hexadecimal code (e.g., "#F1F1F1") or
+        a named Plotly color (e.g., "grey"). Defaults to light gray "#F1F1F1".
+    text_font_size : int, optional
+        Font size of the text in the plot. Defaults to 8.
+    plot_height : int, optional
+        Height of the plot in pixels. Calculated based on the number of labels if not provided.
+    plot_width : int, optional
+        Width of the plot in pixels. Defaults to 750.
+    plotly_template : str, optional
+        The Plotly template to use for the plot styling. Defaults to "plotly_white".
+    plotly_trace_settings : Dict[str, Any], optional
+        Additional trace settings for advanced customization using Plotly's trace options.
+    plotly_layout_settings : Dict[str, Any], optional
+        Additional layout settings for advanced customization using Plotly's layout options.
+
+    Returns
+    -------
+    go.Figure
+        A Plotly Figure object representing the impact analysis as a waterfall chart.
+
+    Raises
+    ------
+    TypeError
+        If `impact_table` is not a Polars DataFrame.
+    ValueError
+        If no columns with '_comparison' are found in `impact_table`.
+    """
+    if not isinstance(impact_table, pl.DataFrame):
+        raise TypeError("impact_table must be Polars DataFrame")
+
+    # Check for columns containing "_comparison" in the impact table
+    comparison_columns = [col for col in impact_table.columns if "_comparison" in col]
+    if not comparison_columns:
+        raise ValueError(
+            "No comparison column found in the impact_table. Use impact_table function and use it's returned dataframe for plotting."
+        )
+
+    # Convert format string to a formatting function
+    formatter = lambda x: format_data_labels.format(x)
+
+    # Prepare data for plotting
+    x_labels, y_values, data_labels, measure_list = _prep_data_for_impact_plot(
+        impact_table, formatter, primary_total_label, comparison_total_label
+    )
+
+    # Create the plot
+    fig = go.Figure(
+        go.Waterfall(
+            orientation="h",
+            measure=measure_list,
+            x=y_values,
+            y=x_labels,
+            text=data_labels,
+            textposition="auto",
+            textfont=dict(size=text_font_size),
+            increasing=dict(marker=dict(color=color_increase)),
+            decreasing=dict(marker=dict(color=color_decrease)),
+            totals=dict(
+                marker=dict(color=color_total, line=dict(color="black", width=1))
+            ),
+        )
+    )
+
+    # Update layout with basic settings
+    layout_params = {
+        "title": title,
+        "height": plot_height if plot_height else len(x_labels) * 25 + 100,
+        "width": plot_width,
+        "template": plotly_template,
+    }
+
+    # Apply advanced settings if provided
+    if plotly_trace_settings:
+        fig.update_traces(plotly_trace_settings)
+    if plotly_layout_settings:
+        fig.update_layout(**plotly_layout_settings)
+    else:
+        fig.update_layout(**layout_params)
+
+    return fig

l4v1-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "l4v1"
+version = "0.0.1"
+description = "Add your description here"
+authors = [
+    { name = "Miro Lavi", email = "mirolavi@gmail.com" }
+]
+dependencies = [
+    "polars>=0.20.21",
+    "plotly>=5.21.0",
+]
+readme = "README.md"
+requires-python = ">= 3.8"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.rye]
+managed = true
+dev-dependencies = [
+    "jupyterlab>=4.1.6",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/l4v1_analytics"]

l4v1-0.0.1/requirements-dev.lock

@@ -0,0 +1,254 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+
+-e file:.
+anyio==4.3.0
+    # via httpx
+    # via jupyter-server
+argon2-cffi==23.1.0
+    # via jupyter-server
+argon2-cffi-bindings==21.2.0
+    # via argon2-cffi
+arrow==1.3.0
+    # via isoduration
+asttokens==2.4.1
+    # via stack-data
+async-lru==2.0.4
+    # via jupyterlab
+attrs==23.2.0
+    # via jsonschema
+    # via referencing
+babel==2.14.0
+    # via jupyterlab-server
+beautifulsoup4==4.12.3
+    # via nbconvert
+bleach==6.1.0
+    # via nbconvert
+certifi==2024.2.2
+    # via httpcore
+    # via httpx
+    # via requests
+cffi==1.16.0
+    # via argon2-cffi-bindings
+charset-normalizer==3.3.2
+    # via requests
+comm==0.2.2
+    # via ipykernel
+debugpy==1.8.1
+    # via ipykernel
+decorator==5.1.1
+    # via ipython
+defusedxml==0.7.1
+    # via nbconvert
+executing==2.0.1
+    # via stack-data
+fastjsonschema==2.19.1
+    # via nbformat
+fqdn==1.5.1
+    # via jsonschema
+h11==0.14.0
+    # via httpcore
+httpcore==1.0.5
+    # via httpx
+httpx==0.27.0
+    # via jupyterlab
+idna==3.7
+    # via anyio
+    # via httpx
+    # via jsonschema
+    # via requests
+ipykernel==6.29.4
+    # via jupyterlab
+ipython==8.23.0
+    # via ipykernel
+isoduration==20.11.0
+    # via jsonschema
+jedi==0.19.1
+    # via ipython
+jinja2==3.1.3
+    # via jupyter-server
+    # via jupyterlab
+    # via jupyterlab-server
+    # via nbconvert
+json5==0.9.25
+    # via jupyterlab-server
+jsonpointer==2.4
+    # via jsonschema
+jsonschema==4.21.1
+    # via jupyter-events
+    # via jupyterlab-server
+    # via nbformat
+jsonschema-specifications==2023.12.1
+    # via jsonschema
+jupyter-client==8.6.1
+    # via ipykernel
+    # via jupyter-server
+    # via nbclient
+jupyter-core==5.7.2
+    # via ipykernel
+    # via jupyter-client
+    # via jupyter-server
+    # via jupyterlab
+    # via nbclient
+    # via nbconvert
+    # via nbformat
+jupyter-events==0.10.0
+    # via jupyter-server
+jupyter-lsp==2.2.5
+    # via jupyterlab
+jupyter-server==2.14.0
+    # via jupyter-lsp
+    # via jupyterlab
+    # via jupyterlab-server
+    # via notebook-shim
+jupyter-server-terminals==0.5.3
+    # via jupyter-server
+jupyterlab==4.1.6
+jupyterlab-pygments==0.3.0
+    # via nbconvert
+jupyterlab-server==2.26.0
+    # via jupyterlab
+markupsafe==2.1.5
+    # via jinja2
+    # via nbconvert
+matplotlib-inline==0.1.7
+    # via ipykernel
+    # via ipython
+mistune==3.0.2
+    # via nbconvert
+nbclient==0.10.0
+    # via nbconvert
+nbconvert==7.16.3
+    # via jupyter-server
+nbformat==5.10.4
+    # via jupyter-server
+    # via nbclient
+    # via nbconvert
+nest-asyncio==1.6.0
+    # via ipykernel
+notebook-shim==0.2.4
+    # via jupyterlab
+overrides==7.7.0
+    # via jupyter-server
+packaging==24.0
+    # via ipykernel
+    # via jupyter-server
+    # via jupyterlab
+    # via jupyterlab-server
+    # via nbconvert
+    # via plotly
+pandocfilters==1.5.1
+    # via nbconvert
+parso==0.8.4
+    # via jedi
+pexpect==4.9.0
+    # via ipython
+platformdirs==4.2.0
+    # via jupyter-core
+plotly==5.21.0
+    # via l4v1
+polars==0.20.21
+    # via l4v1
+prometheus-client==0.20.0
+    # via jupyter-server
+prompt-toolkit==3.0.43
+    # via ipython
+psutil==5.9.8
+    # via ipykernel
+ptyprocess==0.7.0
+    # via pexpect
+    # via terminado
+pure-eval==0.2.2
+    # via stack-data
+pycparser==2.22
+    # via cffi
+pygments==2.17.2
+    # via ipython
+    # via nbconvert
+python-dateutil==2.9.0.post0
+    # via arrow
+    # via jupyter-client
+python-json-logger==2.0.7
+    # via jupyter-events
+pyyaml==6.0.1
+    # via jupyter-events
+pyzmq==26.0.2
+    # via ipykernel
+    # via jupyter-client
+    # via jupyter-server
+referencing==0.34.0
+    # via jsonschema
+    # via jsonschema-specifications
+    # via jupyter-events
+requests==2.31.0
+    # via jupyterlab-server
+rfc3339-validator==0.1.4
+    # via jsonschema
+    # via jupyter-events
+rfc3986-validator==0.1.1
+    # via jsonschema
+    # via jupyter-events
+rpds-py==0.18.0
+    # via jsonschema
+    # via referencing
+send2trash==1.8.3
+    # via jupyter-server
+six==1.16.0
+    # via asttokens
+    # via bleach
+    # via python-dateutil
+    # via rfc3339-validator
+sniffio==1.3.1
+    # via anyio
+    # via httpx
+soupsieve==2.5
+    # via beautifulsoup4
+stack-data==0.6.3
+    # via ipython
+tenacity==8.2.3
+    # via plotly
+terminado==0.18.1
+    # via jupyter-server
+    # via jupyter-server-terminals
+tinycss2==1.2.1
+    # via nbconvert
+tornado==6.4
+    # via ipykernel
+    # via jupyter-client
+    # via jupyter-server
+    # via jupyterlab
+    # via terminado
+traitlets==5.14.3
+    # via comm
+    # via ipykernel
+    # via ipython
+    # via jupyter-client
+    # via jupyter-core
+    # via jupyter-events
+    # via jupyter-server
+    # via jupyterlab
+    # via matplotlib-inline
+    # via nbclient
+    # via nbconvert
+    # via nbformat
+types-python-dateutil==2.9.0.20240316
+    # via arrow
+uri-template==1.3.0
+    # via jsonschema
+urllib3==2.2.1
+    # via requests
+wcwidth==0.2.13
+    # via prompt-toolkit
+webcolors==1.13
+    # via jsonschema
+webencodings==0.5.1
+    # via bleach
+    # via tinycss2
+websocket-client==1.7.0
+    # via jupyter-server

l4v1-0.0.1/requirements.lock

@@ -0,0 +1,18 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+
+-e file:.
+packaging==24.0
+    # via plotly
+plotly==5.21.0
+    # via l4v1
+polars==0.20.21
+    # via l4v1
+tenacity==8.2.3
+    # via plotly

l4v1-0.0.1/tests/test_price_volume_mix.py

@@ -0,0 +1,29 @@
+from l4v1.price_volume_mix import pvm_plot, pvm_table
+import polars as pl
+import datetime as dt
+
+df = pl.read_parquet("../data/supermarket_sales.parquet").with_columns(
+    pl.col(pl.Categorical).cast(pl.Utf8)
+)
+
+df1 = df.filter(pl.col("Datetime").dt.week() == 4)
+df2 = df.filter(pl.col("Datetime").dt.week() == 5)
+
+df1.columns
+
+# Create the performance volume mix table
+pvm_df = pvm_table(
+    df_primary=df1,
+    df_comparison=df2,
+    group_by_columns=["Customer type", "Product line"],
+    metrics={"volume": "Quantity", "outcome": "Total"},
+)
+
+pvm_df
+
+pvm_plot(
+    pvm_table=pvm_df,
+    outcome_metric_name="Total",
+    primary_label="lala",
+    comparison_label="zaza",
+)