analytics-toolkit 1.3.7.6__tar.gz → 1.3.8.2__tar.gz

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-toolkit
-Version: 1.3.7.6
+Version: 1.3.8.2
 Summary: Shared Python utilities for SQL, Excel, and date helpers.
 Author: analytics_toolkit contributors
 License: MIT License
@@ -75,7 +75,7 @@ Python toolkit for AB-test analysis, SQL workflows, Excel reports, and date help
 
 [Documentation Overview](https://github.com/Karapsin/analytics_toolkit/blob/main/docs/README.md)
 
-**Version:** `1.3.7.6`<br>
+**Version:** `1.3.8.2`<br>
 **Depends:** Python (`>=3.8,<3.15`)<br>
 **Imports:** [clickhouse-connect](https://pypi.org/project/clickhouse-connect/) (`>=0.5.14,<1`), [lz4](https://pypi.org/project/lz4/) (`>=4.3.2,<5`), [numpy](https://pypi.org/project/numpy/) (`>=1.24.2,<2`), [openpyxl](https://pypi.org/project/openpyxl/) (`>=3.1.1,<4`), [orjson](https://pypi.org/project/orjson/) (`>=3.8.7,<4`), [pandas](https://pypi.org/project/pandas/) (`>=1.4.4,<3`), [psycopg2-binary](https://pypi.org/project/psycopg2-binary/) (`>=2.9.5,<3`), [python-dateutil](https://pypi.org/project/python-dateutil/) (`>=2.8.2,<3`), [pytz](https://pypi.org/project/pytz/) (`>=2022.7`), [requests](https://pypi.org/project/requests/) (`>=2.28.2,<3`), [scipy](https://pypi.org/project/scipy/) (`>=1.10.1,<2`), [sqlglot](https://pypi.org/project/sqlglot/) (`>=20,<31`), [sqlparse](https://pypi.org/project/sqlparse/) (`>=0.4.3,<1`), [tqdm](https://pypi.org/project/tqdm/) (`>=4.65.0,<5`), [trino](https://pypi.org/project/trino/) (`>=0.320,<1`), [zstandard](https://pypi.org/project/zstandard/) (`>=0.20.0,<1`)<br>
 **Suggests:** [apache-airflow](https://pypi.org/project/apache-airflow/) (`>=2.4,<3`; optional extra `airflow`)<br>
@@ -130,8 +130,22 @@ rows = sql.transfer(
 )
 ```
 
-- `sql.read` / `sql.read_sql`: run a query and return a dataframe.
-- `sql.execute` / `sql.execute_sql`: run DDL or DML without returning a dataframe.
+Aliases can point to the same backend type, so Greenplum-to-Greenplum transfers
+work the same way.
+
+```python
+rows = sql.transfer(
+    from_db="gp_sales",
+    to_db="gp_finance",
+    from_sql="select user_id, order_id, amount from mart.sales_orders",
+    to_table="finance.sales_orders_copy",
+    write_mode="replace",
+    batch_size=50_000,
+)
+```
+
+- `sql.read`: run a query and return a dataframe.
+- `sql.execute`: run DDL or DML without returning a dataframe.
 - `sql.execute_read`: run setup SQL and return the final result as a dataframe.
 - `sql.load_df`: load a pandas dataframe into a configured backend table.
 - `sql.transfer`: move rows from a source query to a target table across backends.

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/README.md

@@ -6,7 +6,7 @@ Python toolkit for AB-test analysis, SQL workflows, Excel reports, and date help
 
 [Documentation Overview](https://github.com/Karapsin/analytics_toolkit/blob/main/docs/README.md)
 
-**Version:** `1.3.7.6`<br>
+**Version:** `1.3.8.2`<br>
 **Depends:** Python (`>=3.8,<3.15`)<br>
 **Imports:** [clickhouse-connect](https://pypi.org/project/clickhouse-connect/) (`>=0.5.14,<1`), [lz4](https://pypi.org/project/lz4/) (`>=4.3.2,<5`), [numpy](https://pypi.org/project/numpy/) (`>=1.24.2,<2`), [openpyxl](https://pypi.org/project/openpyxl/) (`>=3.1.1,<4`), [orjson](https://pypi.org/project/orjson/) (`>=3.8.7,<4`), [pandas](https://pypi.org/project/pandas/) (`>=1.4.4,<3`), [psycopg2-binary](https://pypi.org/project/psycopg2-binary/) (`>=2.9.5,<3`), [python-dateutil](https://pypi.org/project/python-dateutil/) (`>=2.8.2,<3`), [pytz](https://pypi.org/project/pytz/) (`>=2022.7`), [requests](https://pypi.org/project/requests/) (`>=2.28.2,<3`), [scipy](https://pypi.org/project/scipy/) (`>=1.10.1,<2`), [sqlglot](https://pypi.org/project/sqlglot/) (`>=20,<31`), [sqlparse](https://pypi.org/project/sqlparse/) (`>=0.4.3,<1`), [tqdm](https://pypi.org/project/tqdm/) (`>=4.65.0,<5`), [trino](https://pypi.org/project/trino/) (`>=0.320,<1`), [zstandard](https://pypi.org/project/zstandard/) (`>=0.20.0,<1`)<br>
 **Suggests:** [apache-airflow](https://pypi.org/project/apache-airflow/) (`>=2.4,<3`; optional extra `airflow`)<br>
@@ -61,8 +61,22 @@ rows = sql.transfer(
 )
 ```
 
-- `sql.read` / `sql.read_sql`: run a query and return a dataframe.
-- `sql.execute` / `sql.execute_sql`: run DDL or DML without returning a dataframe.
+Aliases can point to the same backend type, so Greenplum-to-Greenplum transfers
+work the same way.
+
+```python
+rows = sql.transfer(
+    from_db="gp_sales",
+    to_db="gp_finance",
+    from_sql="select user_id, order_id, amount from mart.sales_orders",
+    to_table="finance.sales_orders_copy",
+    write_mode="replace",
+    batch_size=50_000,
+)
+```
+
+- `sql.read`: run a query and return a dataframe.
+- `sql.execute`: run DDL or DML without returning a dataframe.
 - `sql.execute_read`: run setup SQL and return the final result as a dataframe.
 - `sql.load_df`: load a pandas dataframe into a configured backend table.
 - `sql.transfer`: move rows from a source query to a target table across backends.

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/analytics_toolkit/ab_utils/api.py

@@ -6,10 +6,15 @@ from analytics_toolkit.general import time_print
 
 from .bootstrap import _apply_multiple_comparisons_adjustment
 from .constants import DEFAULT_ALPHA, DEFAULT_POWER
-from .cuped import _compute_cuped_statistics
+from .cuped import _compute_cuped_statistics, _prepare_cuped_context
 from .outliers import _build_outlier_context
 from .ratio import _normalize_ratio_metrics
-from .rows import _build_comparisons, _build_metric_definitions, _build_metric_row
+from .rows import (
+    _build_comparisons,
+    _build_metric_definitions,
+    _build_metric_row,
+    _prepare_metric_context,
+)
 from .stats import _compute_mde_from_standard_error, _safe_relative
 from .validation import (
     _validate_input_columns,
@@ -105,6 +110,15 @@ def compute_test_metrics(
     ratio_specs = _normalize_ratio_metrics(df, ratio_metrics, reserved_columns={group, user_id})
     comparisons = _build_comparisons(group_names, control, test_vs_test=test_vs_test)
     metric_definitions = _build_metric_definitions(metric_columns, ratio_specs)
+    group_values = df[group].to_numpy()
+    group_masks = {group_name: group_values == group_name for group_name in group_names}
+    comparison_frames = {
+        (test_group, baseline_group): df.loc[
+            group_masks[test_group] | group_masks[baseline_group],
+            [user_id, group],
+        ].copy()
+        for test_group, baseline_group in comparisons
+    }
     time_print(
         "compute_test_metrics: setup complete "
         f"groups={len(group_names)} comparisons={len(comparisons)} "
@@ -129,6 +143,26 @@ def compute_test_metrics(
             )
     time_print("compute_test_metrics: outlier contexts complete")
 
+    prepared_metric_contexts: dict[str, dict[str, object]] = {}
+    prepared_cuped_contexts: dict[str, dict[str, object]] = {}
+    for metric_definition in metric_definitions:
+        metric_key = str(metric_definition["metric_key"])
+        outlier_context = metric_definition.get("_outlier_context")
+        prepared_metric_contexts[metric_key] = _prepare_metric_context(
+            df=df,
+            metric_definition=metric_definition,
+            outlier_context=outlier_context,
+        )
+        if pre_exp_metrics_df is not None:
+            prepared_cuped_contexts[metric_key] = _prepare_cuped_context(
+                df=df,
+                pre_exp_metrics_df=pre_exp_metrics_df,
+                user_id_column=user_id,
+                metric_definition=metric_definition,
+                outlier_context=outlier_context,
+                pre_outlier_context=metric_definition.get("_pre_outlier_context"),
+            )
+
     rows: list[dict[str, object]] = []
     for test_group, baseline_group in comparisons:
         time_print(f"compute_test_metrics: comparison {test_group} vs {baseline_group}")
@@ -146,6 +180,8 @@ def compute_test_metrics(
                 mde_alpha=mde_alpha,
                 mde_power=mde_power,
                 outlier_context=outlier_context,
+                prepared_metric_context=prepared_metric_contexts.get(metric_name),
+                group_masks=group_masks,
             )
             row["_comparison_key"] = (test_group, baseline_group)
             if pre_exp_metrics_df is not None:
@@ -160,6 +196,10 @@ def compute_test_metrics(
                     metric_definition=metric_definition,
                     outlier_context=outlier_context,
                     pre_outlier_context=metric_definition.get("_pre_outlier_context"),
+                    prepared_cuped_context={
+                        **prepared_cuped_contexts[metric_name],
+                        "comparison_frame": comparison_frames[(test_group, baseline_group)],
+                    },
                 )
                 row["mde_abs CUPED"] = _compute_mde_from_standard_error(
                     standard_error=row["s.e. CUPED"],

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/analytics_toolkit/ab_utils/cuped.py

@@ -41,29 +41,68 @@ def _compute_cuped_p_value(
     return p_value
 
 
-def _compute_cuped_statistics(
+def _prepare_cuped_context(
     df: pd.DataFrame,
     pre_exp_metrics_df: pd.DataFrame,
-    group_column: str,
     user_id_column: str,
-    baseline_group: str,
-    test_group: str,
     metric_definition: dict[str, object],
     outlier_context: dict[str, object] | None = None,
     pre_outlier_context: dict[str, object] | None = None,
-) -> tuple[float, float]:
-    cuped_frame, reason = _build_cuped_frame(
+) -> dict[str, object]:
+    exp_values, exp_error = _build_metric_values_by_user(
         df=df,
-        pre_exp_metrics_df=pre_exp_metrics_df,
         user_id_column=user_id_column,
-        group_column=group_column,
-        baseline_group=baseline_group,
-        test_group=test_group,
         metric_definition=metric_definition,
+        value_column="metric_exp",
         outlier_context=outlier_context,
-        pre_outlier_context=pre_outlier_context,
     )
+    pre_values, pre_error = _build_metric_values_by_user(
+        df=pre_exp_metrics_df,
+        user_id_column=user_id_column,
+        metric_definition=metric_definition,
+        value_column="metric_pre",
+        outlier_context=pre_outlier_context,
+    )
+    return {
+        "exp_values": exp_values.set_index(user_id_column) if exp_error is None else None,
+        "pre_values": pre_values.set_index(user_id_column) if pre_error is None else None,
+        "exp_error": exp_error,
+        "pre_error": pre_error,
+    }
+
+
+def _compute_cuped_statistics(
+    df: pd.DataFrame,
+    pre_exp_metrics_df: pd.DataFrame,
+    group_column: str,
+    user_id_column: str,
+    baseline_group: str,
+    test_group: str,
+    metric_definition: dict[str, object],
+    outlier_context: dict[str, object] | None = None,
+    pre_outlier_context: dict[str, object] | None = None,
+    prepared_cuped_context: dict[str, object] | None = None,
+) -> tuple[float, float]:
     metric_name = str(metric_definition["metric_key"])
+    if prepared_cuped_context is None:
+        cuped_frame, reason = _build_cuped_frame(
+            df=df,
+            pre_exp_metrics_df=pre_exp_metrics_df,
+            user_id_column=user_id_column,
+            group_column=group_column,
+            baseline_group=baseline_group,
+            test_group=test_group,
+            metric_definition=metric_definition,
+            outlier_context=outlier_context,
+            pre_outlier_context=pre_outlier_context,
+        )
+    else:
+        cuped_frame, reason = _build_cuped_frame_from_prepared_context(
+            comparison_frame=prepared_cuped_context["comparison_frame"],
+            user_id_column=user_id_column,
+            prepared_cuped_context=prepared_cuped_context,
+        )
+
     if reason is not None:
         warnings.warn(
             (
@@ -93,6 +132,26 @@ def _compute_cuped_statistics(
     return p_value, standard_error
 
 
+def _build_cuped_frame_from_prepared_context(
+    comparison_frame: pd.DataFrame,
+    user_id_column: str,
+    prepared_cuped_context: dict[str, object],
+) -> tuple[pd.DataFrame | None, str | None]:
+    exp_values = prepared_cuped_context.get("exp_values")
+    if exp_values is None:
+        return None, f"experiment metric values are unavailable: {prepared_cuped_context.get('exp_error')}"
+    pre_values = prepared_cuped_context.get("pre_values")
+    if pre_values is None:
+        return None, f"pre-experiment metric values are unavailable: {prepared_cuped_context.get('pre_error')}"
+
+    cuped_frame = comparison_frame.copy()
+    cuped_frame = cuped_frame.join(exp_values, on=user_id_column).join(pre_values, on=user_id_column)
+    cuped_frame = cuped_frame.dropna(subset=["metric_exp", "metric_pre"]).reset_index(drop=True)
+    if cuped_frame.empty:
+        return None, "no overlapping non-missing experiment/pre-experiment observations"
+    return cuped_frame, None
+
+
 def _build_cuped_frame(
     df: pd.DataFrame,
     pre_exp_metrics_df: pd.DataFrame,

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/analytics_toolkit/ab_utils/metrics.py

@@ -29,6 +29,7 @@ from .cuped import (
     _compute_cuped_p_value_from_frame,
     _compute_cuped_statistics,
     _compute_cuped_statistics_from_frame,
+    _prepare_cuped_context,
 )
 from .outliers import (
     _apply_outliers_to_agg_ratio_components,
@@ -59,6 +60,7 @@ from .rows import (
     _build_metric_definitions,
     _build_metric_row,
     _build_ratio_metric_row,
+    _prepare_metric_context,
 )
 from .stats import (
     _both_present,
@@ -110,6 +112,8 @@ __all__ = [
     "_build_ratio_valid_mask",
     "_build_ratio_valid_mask_from_arrays",
     "_build_value_outlier_mask",
+    "_prepare_cuped_context",
+    "_prepare_metric_context",
     "_compute_agg_ratio_diff_standard_error",
     "_compute_agg_ratio_group_stats",
     "_compute_agg_ratio_group_stats_arrays",

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/analytics_toolkit/ab_utils/parallel.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import contextvars
+import inspect
 from collections.abc import Mapping
 from contextlib import ExitStack
 from concurrent.futures import Future, ThreadPoolExecutor, as_completed
@@ -20,6 +21,9 @@ from .api import compute_test_metrics
 async_sql = sql_facade.async_sql
 
 _SQL_DATAFRAME_FIELDS = frozenset({"df", "pre_exp_df", "pre_exp_metrics_df"})
+_COMPUTE_TEST_METRICS_FIELDS = frozenset(
+    inspect.signature(compute_test_metrics).parameters
+)
 _DEFAULT_HARD_CONCURRENCY_CAP = 10
 _CONCURRENCY_STATE: contextvars.ContextVar["_ConcurrencyState | None"] = (
     contextvars.ContextVar("analytics_toolkit_ab_parallel_concurrency", default=None)
@@ -127,9 +131,11 @@ def parallel_compute_metrics_from_sql(
     soft_concurrency_cap: int | None = None,
     hard_concurrency_cap: int = _DEFAULT_HARD_CONCURRENCY_CAP,
     progress: bool = False,
+    **metric_defaults: Any,
 ) -> dict[str, pd.DataFrame | str]:
     """Load SQL-backed task dataframes, then run ``parallel_compute_metrics``."""
     _validate_start_comment("start_comment", start_comment)
+    metric_defaults = _validate_metric_defaults(metric_defaults)
     task_defs = _validate_sql_tasks(tasks)
     _validate_concurrency(concurrency)
     _validate_optional_soft_concurrency_cap(soft_concurrency_cap)
@@ -191,7 +197,8 @@ def parallel_compute_metrics_from_sql(
             sql_failures[name] = df_result
             continue
 
-        metric_kwargs = dict(kwargs)
+        metric_kwargs = dict(metric_defaults)
+        metric_kwargs.update(kwargs)
         metric_kwargs["df"] = df_result
         if pre_exp_sql is not None:
             pre_exp_df_result = sql_results[_sql_read_task_name(name, "pre_exp_sql")]
@@ -424,6 +431,38 @@ def _validate_sql_task_spec(
     return name, kwargs, sql, pre_exp_sql, start_comment
 
 
+def _validate_metric_defaults(metric_defaults: Mapping[str, Any]) -> dict[str, Any]:
+    if not metric_defaults:
+        return {}
+
+    dataframe_fields = sorted(_SQL_DATAFRAME_FIELDS.intersection(metric_defaults))
+    if dataframe_fields:
+        fields = ", ".join(dataframe_fields)
+        raise ValueError(
+            "parallel_compute_metrics_from_sql top-level metric defaults cannot "
+            f"define SQL-backed dataframe field(s): {fields}."
+        )
+
+    supported_fields = _COMPUTE_TEST_METRICS_FIELDS - {
+        "df",
+        "pre_exp_metrics_df",
+    }
+    unexpected_fields = sorted(set(metric_defaults) - supported_fields)
+    if unexpected_fields:
+        quoted_fields = ", ".join(repr(field) for field in unexpected_fields)
+        if len(unexpected_fields) == 1:
+            raise TypeError(
+                "parallel_compute_metrics_from_sql() got an unexpected keyword "
+                f"argument {quoted_fields}"
+            )
+        raise TypeError(
+            "parallel_compute_metrics_from_sql() got unexpected keyword "
+            f"arguments: {quoted_fields}"
+        )
+
+    return dict(metric_defaults)
+
+
 def _make_sql_read_task(
     *,
     name: str,
@@ -435,7 +474,7 @@ def _make_sql_read_task(
     task = {
         "name": _sql_read_task_name(name, field),
         "type": "read",
-        "connection_type": db,
+        "db_key": db,
         "query": query,
     }
     if start_comment is not _MISSING:

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/analytics_toolkit/ab_utils/rows.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from itertools import combinations
 import math
 
+import numpy as np
 import pandas as pd
 
 from .constants import DEFAULT_ALPHA, DEFAULT_POWER
@@ -71,6 +72,75 @@ def _build_metric_definitions(
     return metric_definitions
 
 
+def _prepare_metric_context(
+    df: pd.DataFrame,
+    metric_definition: dict[str, object],
+    outlier_context: dict[str, object] | None = None,
+) -> dict[str, object]:
+    if outlier_context is None:
+        outlier_context = metric_definition.get("_outlier_context")
+
+    if metric_definition["kind"] == "mean":
+        metric_values = _get_numeric_metric_series(df, str(metric_definition["column"]))
+        metric_values, outlier_mask = _apply_outliers_to_values(
+            metric_values,
+            outlier_context,
+        )
+        return {
+            "kind": "mean",
+            "metric_key": str(metric_definition["metric_key"]),
+            "column": str(metric_definition["column"]),
+            "values": metric_values.to_numpy(dtype=float),
+            "outlier_mask": outlier_mask.to_numpy(dtype=bool),
+            "outlier_context": outlier_context,
+        }
+
+    ratio_spec = dict(metric_definition["ratio_spec"])
+    numerator = _get_numeric_metric_series(df, ratio_spec["numerator"])
+    denominator = _get_numeric_metric_series(df, ratio_spec["denominator"])
+    if ratio_spec["level"] == "user":
+        valid_mask = _build_ratio_valid_mask(
+            numerator=numerator,
+            denominator=denominator,
+            level=ratio_spec["level"],
+        )
+        values = pd.Series(np.nan, index=df.index, dtype=float)
+        values.loc[valid_mask] = numerator.loc[valid_mask] / denominator.loc[valid_mask]
+        values, outlier_mask = _apply_outliers_to_values(
+            values,
+            outlier_context,
+        )
+        return {
+            "kind": "ratio",
+            "metric_key": str(metric_definition["metric_key"]),
+            "ratio_spec": ratio_spec,
+            "values": values.to_numpy(dtype=float),
+            "outlier_mask": outlier_mask.to_numpy(dtype=bool),
+            "outlier_context": outlier_context,
+        }
+
+    numerator, denominator, outlier_mask = _apply_outliers_to_agg_ratio_components(
+        numerator=numerator,
+        denominator=denominator,
+        outlier_context=outlier_context,
+    )
+    valid_mask = _build_ratio_valid_mask(
+        numerator=numerator,
+        denominator=denominator,
+        level=ratio_spec["level"],
+    )
+    return {
+        "kind": "ratio",
+        "metric_key": str(metric_definition["metric_key"]),
+        "ratio_spec": ratio_spec,
+        "numerator": numerator.to_numpy(dtype=float),
+        "denominator": denominator.to_numpy(dtype=float),
+        "valid_mask": valid_mask.to_numpy(dtype=bool),
+        "outlier_mask": outlier_mask.to_numpy(dtype=bool),
+        "outlier_context": outlier_context,
+    }
+
+
 def _build_metric_row(
     df: pd.DataFrame,
     group_column: str,
@@ -80,7 +150,22 @@ def _build_metric_row(
     mde_alpha: float,
     mde_power: float,
     outlier_context: dict[str, object] | None = None,
+    prepared_metric_context: dict[str, object] | None = None,
+    group_masks: dict[str, np.ndarray] | None = None,
 ) -> dict[str, object]:
+    if prepared_metric_context is not None:
+        return _build_metric_row_from_prepared_context(
+            df=df,
+            group_column=group_column,
+            baseline_group=baseline_group,
+            test_group=test_group,
+            metric_definition=metric_definition,
+            prepared_metric_context=prepared_metric_context,
+            mde_alpha=mde_alpha,
+            mde_power=mde_power,
+            group_masks=group_masks,
+        )
+
     if outlier_context is None:
         outlier_context = metric_definition.get("_outlier_context")
     if metric_definition["kind"] == "mean":
@@ -123,6 +208,121 @@ def _build_metric_row(
     )
 
 
+def _build_metric_row_from_prepared_context(
+    df: pd.DataFrame,
+    group_column: str,
+    baseline_group: str,
+    test_group: str,
+    metric_definition: dict[str, object],
+    prepared_metric_context: dict[str, object],
+    mde_alpha: float,
+    mde_power: float,
+    group_masks: dict[str, np.ndarray] | None = None,
+) -> dict[str, object]:
+    if group_masks is None:
+        group_values = df[group_column].to_numpy()
+        group_masks = {
+            baseline_group: group_values == baseline_group,
+            test_group: group_values == test_group,
+        }
+
+    baseline_mask = np.asarray(group_masks[baseline_group], dtype=bool)
+    test_mask = np.asarray(group_masks[test_group], dtype=bool)
+
+    if prepared_metric_context["kind"] == "mean":
+        metric_name = str(prepared_metric_context["metric_key"])
+        metric_values = np.asarray(prepared_metric_context["values"], dtype=float)
+        outlier_mask = np.asarray(prepared_metric_context["outlier_mask"], dtype=bool)
+        baseline_values = pd.Series(metric_values[baseline_mask]).dropna()
+        test_values = pd.Series(metric_values[test_mask]).dropna()
+        return _build_mean_metric_row(
+            metric_name=metric_name,
+            metric_key=metric_name,
+            baseline_values=baseline_values,
+            test_values=test_values,
+            mde_alpha=mde_alpha,
+            mde_power=mde_power,
+            outliers_cutoff=_get_outlier_cutoff(prepared_metric_context.get("outlier_context")),
+            outliers_n_control=int(outlier_mask[baseline_mask].sum()),
+            outliers_n_test=int(outlier_mask[test_mask].sum()),
+        )
+
+    ratio_spec = dict(metric_definition["ratio_spec"])
+    metric_key = str(prepared_metric_context["metric_key"])
+    if ratio_spec["level"] == "user":
+        metric_values = np.asarray(prepared_metric_context["values"], dtype=float)
+        outlier_mask = np.asarray(prepared_metric_context["outlier_mask"], dtype=bool)
+        baseline_values = pd.Series(metric_values[baseline_mask]).dropna()
+        test_values = pd.Series(metric_values[test_mask]).dropna()
+        return _build_mean_metric_row(
+            metric_name=metric_key,
+            metric_key=metric_key,
+            baseline_values=baseline_values,
+            test_values=test_values,
+            mde_alpha=mde_alpha,
+            mde_power=mde_power,
+            outliers_cutoff=_get_outlier_cutoff(prepared_metric_context.get("outlier_context")),
+            outliers_n_control=int(outlier_mask[baseline_mask].sum()),
+            outliers_n_test=int(outlier_mask[test_mask].sum()),
+        )
+
+    numerator = np.asarray(prepared_metric_context["numerator"], dtype=float)
+    denominator = np.asarray(prepared_metric_context["denominator"], dtype=float)
+    valid_mask = np.asarray(prepared_metric_context["valid_mask"], dtype=bool)
+    outlier_mask = np.asarray(prepared_metric_context["outlier_mask"], dtype=bool)
+    baseline_valid_mask = baseline_mask & valid_mask
+    test_valid_mask = test_mask & valid_mask
+    baseline_frame = pd.DataFrame(
+        {"numerator": numerator[baseline_valid_mask], "denominator": denominator[baseline_valid_mask]}
+    )
+    test_frame = pd.DataFrame(
+        {"numerator": numerator[test_valid_mask], "denominator": denominator[test_valid_mask]}
+    )
+    outliers_n_control = int(outlier_mask[baseline_mask].sum())
+    outliers_n_test = int(outlier_mask[test_mask].sum())
+    baseline_stats = _compute_agg_ratio_group_stats(baseline_frame)
+    test_stats = _compute_agg_ratio_group_stats(test_frame)
+
+    delta_abs = math.nan
+    if _both_present(test_stats["ratio"], baseline_stats["ratio"]):
+        delta_abs = test_stats["ratio"] - baseline_stats["ratio"]
+
+    baseline_variance = _compute_agg_ratio_variance(baseline_frame, baseline_stats["ratio"])
+    test_variance = _compute_agg_ratio_variance(test_frame, test_stats["ratio"])
+    se_diff = math.nan
+    if not math.isnan(baseline_variance) and not math.isnan(test_variance):
+        se_diff = math.sqrt(baseline_variance + test_variance)
+    p_value = _compute_normal_p_value(delta_abs=delta_abs, standard_error=se_diff)
+    mde_abs = _compute_mde_from_standard_error(
+        standard_error=se_diff,
+        alpha=mde_alpha,
+        power=mde_power,
+    )
+
+    return {
+        "metric_name": metric_key,
+        "n0": int(baseline_stats["n"]),
+        "n1": int(test_stats["n"]),
+        "outliers_cutoff": _get_outlier_cutoff(prepared_metric_context.get("outlier_context")),
+        "outliers_n_control": outliers_n_control,
+        "outliers_n_test": outliers_n_test,
+        "metric_control": baseline_stats["ratio"],
+        "metric_test": test_stats["ratio"],
+        "variance_control": baseline_variance,
+        "variance_test": test_variance,
+        "delta_abs": delta_abs,
+        "delta_relative": _safe_relative(delta_abs, baseline_stats["ratio"]),
+        "mde_abs": mde_abs,
+        "mde_relative": _safe_relative(mde_abs, baseline_stats["ratio"]),
+        "s.e.": se_diff,
+        "p-value": p_value,
+        "s.e. bootstrap": math.nan,
+        "bootstrap_adj_p": math.nan,
+        "_metric_key": metric_key,
+        "_test_stat": _compute_studentized_statistic(delta_abs, se_diff),
+    }
+
+
 def _build_mean_metric_row(
     metric_name: str,
     metric_key: str,

{analytics_toolkit-1.3.7.6 → analytics_toolkit-1.3.8.2}/analytics_toolkit/cli.py

@@ -3,8 +3,33 @@ from __future__ import annotations
 import argparse
 import sys
 from collections.abc import Sequence
+from pathlib import Path
 
-from .sql import format_support_matrix
+
+def _prefer_local_package_path() -> None:
+    package = sys.modules.get(__package__)
+    package_path = getattr(package, "__path__", None)
+    if package_path is None:
+        return
+
+    local_path = str(Path(__file__).resolve().parent)
+    existing_paths = [str(path) for path in package_path]
+    package.__path__ = [
+        local_path,
+        *[path for path in existing_paths if not _same_path(path, local_path)],
+    ]
+
+
+def _same_path(left: str, right: str) -> bool:
+    try:
+        return Path(left).resolve() == Path(right).resolve()
+    except OSError:
+        return left == right
+
+
+_prefer_local_package_path()
+
+from .sql.core.capabilities import format_support_matrix
 from .sql.connection import validate_connections
 
 
@@ -35,6 +60,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     support_parser = sql_subparsers.add_parser("support-matrix")
     support_parser.set_defaults(handler=_handle_sql_support_matrix)
+
     return parser
 
 
@@ -59,5 +85,12 @@ def _handle_sql_support_matrix(args: argparse.Namespace) -> int:
     return 0
 
 
+def _display_path(path: Path) -> str:
+    try:
+        return str(path.relative_to(Path.cwd()))
+    except ValueError:
+        return str(path)
+
+
 if __name__ == "__main__":
     raise SystemExit(main(sys.argv[1:]))