utilsds-models 0.0.1__py3-none-any.whl

utilsds-models/visualization.py

@@ -0,0 +1,179 @@
+"""
+NGR Metrics Calculation Module
+
+This module provides functions for calculating various error metrics
+for NGR (Net Gaming Revenue) predictions with business-optimal weighting.
+"""
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+
+def calculate_ngr_metrics(
+    df: pd.DataFrame, late_stage_day: Optional[int] = None, late_stage_correction: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    Calculate NGR metrics with business-optimal weighting.
+
+    This function computes various error metrics (MAE, MAPE, ME, MPE) with business weights
+    based on days_since_ftd. Optionally applies late-stage corrections to predictions.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame containing prediction results with columns:
+        - 'days_since_ftd': int, days since first time deposit
+        - 'remaining_ngr': float, actual remaining NGR
+        - 'remaining_ngr_pred': float, predicted remaining NGR
+    late_stage_day : int, optional
+        Day threshold after which to apply correction
+    late_stage_correction : float, optional
+        Correction factor to apply (0.0-1.0) linearly after late_stage_day
+
+    Returns
+    -------
+    dict
+        Dictionary containing calculated metrics:
+        - 'Standard MAE': Mean Absolute Error
+        - 'Standard MAPE (%)': Mean Absolute Percentage Error
+        - 'Standard ME': Mean Error
+        - 'Standard MPE (%)': Mean Percentage Error
+        - 'Business Optimal MAE': Weighted MAE
+        - 'Business Optimal MAPE (%)': Weighted MAPE
+        - 'Business Optimal ME': Weighted ME
+        - 'Business Optimal MPE (%)': Weighted MPE
+        - 'mean_abs_error_by_bin': DataFrame with errors by period
+        - 'mean_values': DataFrame with aggregated values by day
+        - 'weights': Array of business weights by day
+
+    Notes
+    -----
+    Business-optimal weights by day ranges:
+    - Days 1-7: 0.05 (learning period - insufficient data)
+    - Days 8-14: 0.85 (early signals emerging)
+    - Days 15-45: 1.00 (SUPER CRITICAL - optimal intervention window)
+    - Days 46-90: 0.90 (confirmation period - high value)
+    - Days 91-180: 0.60 (established patterns - moderate value)
+    - Days 181-270: 0.40 (mature behavior - operational value)
+    - Days 271+: 0.30 (end-game precision - tactical value)
+
+    Examples
+    --------
+    >>> metrics = calculate_ngr_metrics(
+    ...     df,
+    ...     late_stage_day=320,
+    ...     late_stage_correction=0.95
+    ... )
+    >>> print(f"Business MAE: {metrics['Business Optimal MAE']:.2f}")
+    """
+
+    # Calculate mean values grouped by days_since_ftd
+    mean_values = (
+        df.groupby("days_since_ftd")
+        .agg(
+            {
+                "remaining_ngr": "mean",
+                "remaining_ngr_pred": "mean",
+            }
+        )
+        .reset_index()
+    )
+    mean_values = mean_values[mean_values["days_since_ftd"] < 365]
+
+    # Apply late stage correction if specified
+    if late_stage_day is not None and late_stage_correction is not None:
+        days_array = mean_values["days_since_ftd"].values
+        days_from_start = days_array - late_stage_day
+        max_days = 364 - late_stage_day
+
+        correction_factor = np.where(
+            days_array <= late_stage_day,
+            1.0,  # Before late_stage_day: no changes
+            1.0 - (1.0 - late_stage_correction) * (days_from_start / max_days),  # Linear transition
+        )
+        mean_values["remaining_ngr_pred"] = mean_values["remaining_ngr_pred"] * correction_factor
+
+    days = mean_values["days_since_ftd"].values.astype(np.float64)
+
+    # Business-optimal weighting
+    weights = np.where(
+        days <= 7,
+        0.05,  # Learning period - insufficient data
+        np.where(
+            days <= 14,
+            0.85,  # Early signals emerging
+            np.where(
+                days <= 45,
+                1.00,  # SUPER CRITICAL - optimal intervention window
+                np.where(
+                    days <= 90,
+                    0.90,  # Confirmation period - high value
+                    np.where(
+                        days <= 180,
+                        0.60,  # Established patterns - moderate value
+                        np.where(days <= 270, 0.40, 0.30),  # Mature behavior - operational value
+                    ),
+                ),
+            ),
+        ),
+    )  # End-game precision - tactical value
+
+    abs_errors = np.abs(mean_values["remaining_ngr"] - mean_values["remaining_ngr_pred"])
+    errors = mean_values["remaining_ngr"] - mean_values["remaining_ngr_pred"]
+
+    # Define bins for error analysis by period
+    bins = [0, 7, 14, 45, 90, 180, 270, 364]
+    labels = ["1-7", "8-14", "15-45", "46-90", "91-180", "181-270", "271-364"]
+
+    # Calculate standard metrics
+    business_optimal_tmae = np.sum(abs_errors * weights) / np.sum(weights)
+    business_optimal_me = np.sum(errors * weights) / np.sum(weights)
+    standard_mae = round(np.mean(abs_errors), 4)
+    standard_me = round(np.mean(errors), 4)
+
+    # Calculate percentage-based metrics
+    # Avoid division by zero - use small epsilon for very small values
+    epsilon = 1e-6
+    safe_remaining_ngr = np.where(np.abs(mean_values["remaining_ngr"]) < epsilon, epsilon, mean_values["remaining_ngr"])
+
+    percentage_abs_errors = (
+        np.abs((mean_values["remaining_ngr"] - mean_values["remaining_ngr_pred"]) / safe_remaining_ngr) * 100
+    )
+    errors_percentage = ((mean_values["remaining_ngr"] - mean_values["remaining_ngr_pred"]) / safe_remaining_ngr) * 100
+
+    # Assign each day to a period bin
+    day_bins = pd.cut(mean_values["days_since_ftd"], bins=bins, labels=labels, right=True, include_lowest=True)
+
+    # Calculate mean errors by period
+    mean_abs_error_by_bin = pd.DataFrame(
+        {
+            "bin": labels,
+            "mean_abs_error": [abs_errors[day_bins == label].mean() for label in labels],
+            "mean_error": [errors[day_bins == label].mean() for label in labels],
+            "mape": [percentage_abs_errors[day_bins == label].mean() for label in labels],
+        }
+    )
+
+    # Calculate business-optimal percentage metrics
+    business_optimal_mape = np.sum(percentage_abs_errors * weights) / np.sum(weights)
+    standard_mape = np.mean(percentage_abs_errors)
+
+    business_optimal_mpe = np.sum(errors_percentage * weights) / np.sum(weights)
+    standard_mpe = np.mean(errors_percentage)
+
+    # Return dict with all metrics
+    return {
+        "Standard MAE": standard_mae,
+        "Standard MAPE (%)": round(standard_mape, 1),
+        "Standard ME": standard_me,
+        "Standard MPE (%)": round(standard_mpe, 1),
+        "Business Optimal MAE": round(business_optimal_tmae, 2),
+        "Business Optimal MAPE (%)": round(business_optimal_mape, 1),
+        "Business Optimal ME": round(business_optimal_me, 2),
+        "Business Optimal MPE (%)": round(business_optimal_mpe, 1),
+        "mean_abs_error_by_bin": mean_abs_error_by_bin,
+        "mean_values": mean_values,
+        "weights": weights,
+    }

utilsds_models-0.0.1.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: utilsds-models
+Version: 0.0.1
+Summary: Solution for specific models
+Author-email: DS Team <ds@sts.pl>
+License: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: matplotlib>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+
+# utilsds
+
+Utilsds is a library that includes classes and functions used in data science projects such as:
+
+- **algorithm**:
+  - `Algorithm`: Base class for fitting, training, and getting hyperparameters of machine learning models.
+
+- **data_ops**:
+  - `DataOperations`: Handle data operations locally and with Google Cloud services (BigQuery and Cloud Storage).
+  - BigQuery operations:
+    - `load_bq_data`: Load data from tables, views, and SQL files.
+    - `save_bq_view`, `save_bq_table`: Save views and tables.
+    - `load_bq_procedure`: Execute stored procedures.
+    - `load_bq_details`: Get table/view details and schema.
+    - `delete_bq_data`: Delete data with safety confirmations.
+    - `dry_run`: Perform dry runs to estimate query costs.
+  - Cloud Storage operations:
+    - `save_gcs_bucket`: Create buckets.
+    - `save_gcs_file`, `load_gcs_file`: Save and load files (.pkl, .json, .csv, .html, .sql).
+  - Local file operations:
+    - `save_local_file`, `load_local_file`: Save and load files (.pkl, .json, .csv, .html, .sql).
+
+- **data_processing**:
+  - `SkewnessTransformer`: Transform skewed data using various methods (IHS, neglog, Yeo-Johnson, quantile).
+  - `NullReplacer`: Replace null values in specified columns with configurable strategies.
+  - `ColumnDropper`: Drop specified columns from a DataFrame.
+  - `OutliersCleaner`: Clean outliers by clipping values outside specified percentile ranges.
+  - `CategoricalMapper`: Map values in categorical columns according to a specified mapping scheme.
+  - `NumericalMapper`: Convert numerical columns to categorical by binning.
+  - `Encoder`: One-hot encode categorical columns in the data.
+  - `Normalizer`: Normalize numerical columns using a provided scaler.
+
+- **data_split**:
+  - `train_test_validation_split`: Split data into training, testing, and validation sets.
+  - `resample_X_y`: resample train data and target column.
+
+- **ds_statistics**:
+  - `test_kruskal_wallis`: Perform the Kruskal-Wallis statistical test.
+  - `test_agosto_pearsona`: Test for normality using D'Agostino-Pearson test.
+
+- **evaluate**:
+  - `ModelEvaluator`: Evaluate models and generate plots for diagnostics.
+  - `ShapExplainer`: Explain model predictions using SHAP values.
+
+- **experiments**:
+  - `VertexExperiment`: Manage experiments with Vertex AI.
+
+- **optuna**:
+  - `Optuna`: Optimize hyperparameters using Optuna.
+
+- **metrics**:
+  - `Metrics`: Calculate metrics for both classification and regression models.
+
+- **modeling**:
+  - `Modeling`: Manage modeling, metrics, and logging with Vertex AI.
+
+- **Supervised**:
+  - `LazyClassifier`: A classifier that automatically trains and evaluates multiple models.
+  - `LazyRegressor`: A regressor that automatically trains and evaluates multiple models.
+  - `get_card_split`: Function to split data into card-like groups.
+  - `adjusted_rsquared`: Calculate adjusted R-squared for regression models.
+
+- **visualization**:
+  - `MetricsPlot`: Compare metrics for different parameter values.
+  - `Radar`: Create radar plots for visualizing data.
+  - `cluster_characteristics`: Analyze cluster characteristics.
+  - `comparison_density`: Compare density distributions.
+  - `elbow_visualisation`: Visualize the elbow method for clustering.
+  - `describe_clusters_metrics`: Describe metrics for clusters.
+  - `category_null_variables`: Visualize null variables in categorical data.
+  - `normal_distr_plots`: Visualize normal distribution plots.
+  - `distplot_limitations`: Visualize limitations of distplot.
+  - `boxplot_limitations`: Visualize limitations of boxplot.
+  - `violinplot_limitations`: Visualize limitations of violinplot.
+  - `countplot_limitations`: Visualize limitations of countplot.
+  - `categorical_variable_perc`: Visualize percentage of categorical variables.
+  - `spearman_correlation`: Visualize spearman correlation.
+  - `calculate_crammers_v`: Calculate Crammer's V.
+
+- **what_if_streamlit**:
+  - `ShapSaver`: Save SHAP explainer components for lazy loading in what-if analysis.
+  - `ColumnMetadataGenerator`: Generate column metadata from a DataFrame or CSV file.
+
+- **monitoring**:
+  - `mapping`: Create column mapping from configuration file for Evidently.
+  - `test_data`: Test data for issues using Evidently test suites.
+  - `check_data_drift`: Check data for drift using Evidently metrics.
+  - `send_email_with_table`: Send email notifications with HTML tables for monitoring alerts.

utilsds_models-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+utilsds-models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utilsds-models/custom_metrics.py,sha256=bHoLUsbvI4ypCFWtV6dFguj2prF0BI4HGH6ZYtzYQBY,21067
+utilsds-models/data_processing.py,sha256=fNM9fk8bfn_OEwrK1eCqRCwU4h5JR3ujtwVxwmzxL-0,14087
+utilsds-models/evip_dynamic.py,sha256=m90XHO9V1sFN501NjWpPVBlfM33n8W-QHNcjfO302pg,4227
+utilsds-models/metrics.py,sha256=sUb0LbIjumIu13DU2lNONYoTRtHjQLo0Z-gX39Pg77U,7016
+utilsds-models/visualization.py,sha256=sUb0LbIjumIu13DU2lNONYoTRtHjQLo0Z-gX39Pg77U,7016
+utilsds_models-0.0.1.dist-info/METADATA,sha256=CjTuHtwSPl3oFB8dUnvwRqvaUa5UaBXBSTUNVRaBRjY,4973
+utilsds_models-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+utilsds_models-0.0.1.dist-info/top_level.txt,sha256=TopNmyfabH891p-7KDjmfWjIUDYBEvo-4a2vBWz5uyU,15
+utilsds_models-0.0.1.dist-info/RECORD,,

utilsds_models-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

utilsds_models-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+utilsds-models