Merge pull request #412 from Crunch-io/ZC-617-audience-ratio-measure

[ZC-617]: add audience ratio measure

Author: ernestoarbitrio

.github/workflows/ci.yml

@@ -10,14 +10,14 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
     strategy:
       max-parallel: 5
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}

src/cr/cube/cubepart.py

@@ -278,6 +278,11 @@ def __repr__(self):
 
     # ---interface ---------------------------------------------------
 
+    @lazyproperty
+    def audience_ratio(self):
+        """2D np.float64 ndarray of audience-ratio for each matrix cell."""
+        return self._assemble_matrix(self._measures.audience_ratio.blocks)
+
     @lazyproperty
     def column_aliases(self):
         """1D str ndarray of alias for each column, for use as column headings."""

src/cr/cube/enums.py

@@ -116,6 +116,7 @@ class MEASURE(enum.Enum):
     COLUMN_BASE_WEIGHTED = "col_base_weighted"
     COLUMN_INDEX = "col_index"
     COLUMN_PERCENT = "col_percent"
+    AUDIENCE_RATIO = "audience_ratio"
     COLUMN_PERCENT_MOE = "col_percent_moe"
     COLUMN_SHARE_SUM = "col_share_sum"
     COLUMN_STDDEV = "col_std_dev"

src/cr/cube/matrix/assembler.py

@@ -50,19 +50,17 @@ def column_display_order(cls, dimensions, second_order_measures, format):
         # --- form consistent with `.row_display_order()` and we'll elaborate this when
         # --- we add sort-by-value to columns.
         collation_method = dimensions[1].order_spec.collation_method
+        # fmt: off
         HelperCls = (
             _SortColumnsByLabelHelper
             if collation_method == CM.LABEL
-            else (
-                _SortColumnsByBaseRowHelper
-                if collation_method == CM.OPPOSING_ELEMENT
-                else (
-                    _SortColumnsByInsertedRowHelper
-                    if collation_method == CM.OPPOSING_INSERTION
-                    else _ColumnOrderHelper
-                )
-            )
+            else _SortColumnsByBaseRowHelper
+            if collation_method == CM.OPPOSING_ELEMENT
+            else _SortColumnsByInsertedRowHelper
+            if collation_method == CM.OPPOSING_INSERTION
+            else _ColumnOrderHelper
         )
+        # fmt: on
         return HelperCls(dimensions, second_order_measures, format)._display_order
 
     @classmethod
@@ -75,28 +73,21 @@ def row_display_order(cls, dimensions, second_order_measures, format):
         """
         collation_method = dimensions[0].order_spec.collation_method
         dim_type = dimensions[1].dimension_type
+        # fmt: off
         HelperCls = (
             _SortRowsByBaseColumnHelper
             if collation_method == CM.OPPOSING_ELEMENT
-            else (
-                _SortRowsByDerivedColumnHelper
-                if collation_method == CM.OPPOSING_INSERTION
-                and dim_type in DT.ARRAY_TYPES
-                else (
-                    _SortRowsByInsertedColumnHelper
-                    if collation_method == CM.OPPOSING_INSERTION
-                    else (
-                        _SortRowsByLabelHelper
-                        if collation_method == CM.LABEL
-                        else (
-                            _SortRowsByMarginalHelper
-                            if collation_method == CM.MARGINAL
-                            else _RowOrderHelper
-                        )
-                    )
-                )
-            )
+            else _SortRowsByDerivedColumnHelper
+            if collation_method == CM.OPPOSING_INSERTION and dim_type in DT.ARRAY_TYPES
+            else _SortRowsByInsertedColumnHelper
+            if collation_method == CM.OPPOSING_INSERTION
+            else _SortRowsByLabelHelper
+            if collation_method == CM.LABEL
+            else _SortRowsByMarginalHelper
+            if collation_method == CM.MARGINAL
+            else _RowOrderHelper
         )
+        # fmt: on
         return HelperCls(dimensions, second_order_measures, format)._display_order
 
     @lazyproperty
@@ -155,6 +146,7 @@ def _measure(self):
             M.COLUMN_BASE_WEIGHTED: "column_weighted_bases",
             M.COLUMN_INDEX: "column_index",
             M.COLUMN_PERCENT: "column_proportions",
+            M.AUDIENCE_RATIO: "audience_ratio",
             M.COLUMN_PERCENT_MOE: "column_std_err",  # monotonic transform
             M.COLUMN_SHARE_SUM: "column_share_sum",
             M.COLUMN_STDDEV: "column_proportion_variances",  # monotonic transform

src/cr/cube/matrix/measure.py

@@ -33,6 +33,11 @@ def __init__(self, cube, dimensions, slice_idx):
         self._dimensions = dimensions
         self._slice_idx = slice_idx
 
+    @lazyproperty
+    def audience_ratio(self):
+        """_AudienceRatio measure object for this cube-result."""
+        return _AudienceRatio(self._dimensions, self, self._cube_measures)
+
     @lazyproperty
     def column_comparable_counts(self):
         """_ColumnComparableCounts measure object for this cube-result."""
@@ -830,6 +835,76 @@ def _weighted_base_blocks(self):
         return self._second_order_measures.column_weighted_bases.blocks
 
 
+class _AudienceRatio(_ColumnProportions):
+    """Provides the audience-ratio measure for a matrix.
+
+    This measure (also known as "Index") is a 2D np.float64 ndarray of the ratio of the
+    proportions of the first column to the proportions of the second column.
+
+    Audience ratio (Index) is a convenient way of showing the ratio of the Target % and
+    the Control % when we have a compared group analysis (aka profiles analysis).
+
+    NOTE: At the moment we only support 2 compare groups, means that we can only have 2
+    column max in the analysis. In case of ncol>2 we will return a 2D ndarray of nans as
+    if it were a non-valid audience ratio.
+    """
+
+    @lazyproperty
+    def _base_values(self):
+        """2D ndarray np.float64 of the base values of the audience ratio"""
+        # --- do not propagate divide-by-zero warnings to stderr ---
+        with np.errstate(divide="ignore", invalid="ignore"):
+            if not self._can_compute_measure:
+                return np.full(self._count_blocks[0][0].shape, np.nan)
+            base_values = self._count_blocks[0][0] / self._weighted_base_blocks[0][0]
+            values = (base_values[:, 0] / base_values[:, 1]) * 100
+            return np.column_stack((values, np.full_like(values, np.nan)))
+
+    @lazyproperty
+    def _can_compute_measure(self):
+        """Bool indicating whether audience ratio is computable.
+
+        If there are more than 2 columns, we return nans as a non-valid measure values
+        """
+        return False if self._count_blocks[0][0].shape[-1] != 2 else True
+
+    @lazyproperty
+    def _intersections(self):
+        """(n_row_subtotals, n_col_subtotals) ndarray of intersection values.
+
+        An intersection value arises where a row-subtotal crosses a column-subtotal.
+
+        Always nan because the audience ratio is not defined for the intersection
+        """
+        # --- do not propagate divide-by-zero warnings to stderr ---
+        return np.full(self._count_blocks[1][1].shape, np.nan)
+
+    @lazyproperty
+    def _subtotal_columns(self):
+        """2D np.float64 ndarray of audience ratio values.
+
+        This is the second "block" and has the shape (n_rows, n_col_subtotals).
+
+        Always empty because the audience ratio has no subtotal columns
+        """
+        # --- do not propagate divide-by-zero warnings to stderr ---
+        return np.empty(self._count_blocks[0][1].shape)
+
+    @lazyproperty
+    def _subtotal_rows(self):
+        """2D np.float64 ndarray of audience ratio values.
+
+        This is the third "block" and has the shape (n_row_subtotals, n_cols).
+        """
+        # --- do not propagate divide-by-zero warnings to stderr ---
+        with np.errstate(divide="ignore", invalid="ignore"):
+            if not self._can_compute_measure:
+                return np.full(self._count_blocks[1][0].shape, np.nan)
+            base_values = self._count_blocks[1][0] / self._weighted_base_blocks[1][0]
+            subtotal_rows = (base_values[:, 0] / base_values[:, 1]) * 100
+            return np.column_stack((subtotal_rows, np.full_like(subtotal_rows, np.nan)))
+
+
 class _ColumnProportionsSmoothed(_ColumnProportions, _SmoothedMeasure):
     """Provides the smoothed column-proportions measure for a matrix.