google-meridian 1.3.2__py3-none-any.whl → 1.5.0__py3-none-any.whl

schema/utils/date_range_bucketing.py

@@ -0,0 +1,117 @@
+# Copyright 2025 The Meridian Authors.
+#
+# 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.
+
+"""Helper classes for generating date intervals for various time buckets."""
+
+import abc
+from collections.abc import Iterator, Sequence
+import datetime
+from typing import TypeAlias
+
+
+__all__ = [
+    "DateRangeBucketer",
+    "MonthlyDateRangeGenerator",
+    "QuarterlyDateRangeGenerator",
+    "YearlyDateRangeGenerator",
+]
+
+
+DateInterval: TypeAlias = tuple[datetime.date, datetime.date]
+
+
+class DateRangeBucketer(abc.ABC):
+  """Generates `DateInterval` protos over a range of dates."""
+
+  def __init__(
+      self,
+      input_dates: Sequence[datetime.date],
+  ):
+    """Initializes the DateRangeBucketer with a sequence of dates.
+
+    Args:
+      input_dates: A sequence of `datetime.date` objects representing the range
+        of dates to generate intervals for.
+    """
+    if not all(
+        input_dates[i] < input_dates[i + 1] for i in range(len(input_dates) - 1)
+    ):
+      raise ValueError("`input_dates` must be strictly ascending dates.")
+
+    self._input_dates = input_dates
+
+  @abc.abstractmethod
+  def generate_date_intervals(self) -> Iterator[DateInterval]:
+    """Generates `DateInterval` protos for the class's input dates.
+
+    Each interval represents a month, quarter, or year, depending on the
+    instance of this class. An interval is excluded if the start date is not the
+    first available date (in `self._input_dates`) for the time bucket. The last
+    interval in `self._input_dates` is excluded in all cases.
+
+    Returns:
+      An iterator over generated `TimeInterval`s.
+    """
+    raise NotImplementedError()
+
+
+class MonthlyDateRangeGenerator(DateRangeBucketer):
+  """Generates monthly date intervals."""
+
+  def generate_date_intervals(self) -> Iterator[DateInterval]:
+    start_date = self._input_dates[0]
+
+    for date in self._input_dates:
+      if date.month != start_date.month:
+        if start_date.day <= 7:
+          yield (start_date, date)
+
+        start_date = date
+
+
+class QuarterlyDateRangeGenerator(DateRangeBucketer):
+  """Generates quarterly date intervals."""
+
+  def generate_date_intervals(self) -> Iterator[DateInterval]:
+    start_date = self._input_dates[0]
+    for date in self._input_dates:
+      start_date_quarter_number = (start_date.month - 1) // 3 + 1
+      current_date_quarter_number = (date.month - 1) // 3 + 1
+
+      if start_date_quarter_number != current_date_quarter_number:
+        # The interval is only included if the start date is the first date of
+        # the quarter that's present in `self._input_dates`. We can detect this
+        # date by checking whether it's in the first month of the quarter and
+        # falls in the first seven days of the month.
+        if (
+            start_date.day <= 7
+            and start_date.month == ((start_date_quarter_number - 1) * 3) + 1
+        ):
+          yield (start_date, date)
+
+        start_date = date
+
+
+class YearlyDateRangeGenerator(DateRangeBucketer):
+  """Generates yearly date intervals."""
+
+  def generate_date_intervals(self) -> Iterator[DateInterval]:
+    start_date = self._input_dates[0]
+
+    for date in self._input_dates:
+      if date.year != start_date.year:
+        if start_date.day <= 7 and start_date.month == 1:
+          yield (start_date, date)
+
+        start_date = date

schema/utils/proto_enum_converter.py

@@ -0,0 +1,127 @@
+# Copyright 2025 The Meridian Authors.
+#
+# 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.
+
+"""A generic class for converting between Protobuf enums and strings."""
+
+from typing import Generic, Type, TypeVar
+import warnings
+
+import bidict
+
+
+EnumType = TypeVar("EnumType")
+DefaultType = TypeVar("DefaultType")
+
+
+class ProtoEnumConverter(Generic[EnumType, DefaultType]):
+  """Class for converting between proto enums and strings."""
+
+  def __init__(
+      self,
+      enum_message: Type[EnumType],
+      enum_display_name: str,
+      mapping: bidict.bidict,
+      enum_unspecified: EnumType,
+      default_when_unspecified: DefaultType,
+  ):
+    """Initializes the ProtoEnumConverter.
+
+    Arguments:
+      enum_message: The proto enum message definition.
+      enum_display_name: The loggable proto enum message name.
+      mapping: The mapping between the proto enum name and the string
+        representation.
+      enum_unspecified: The enum value that corresponds to unspecified.
+      default_when_unspecified: The default value that should be returned when
+        the proto enum is unspecified.
+    """
+    self.enum_message = enum_message
+    self.enum_display_name = enum_display_name
+    self.mapping = mapping
+    self.enum_unspecified = enum_unspecified
+    self.default_when_unspecified = default_when_unspecified
+
+  def to_proto(self, string_value: str | None) -> EnumType:
+    """Converts a string to its corresponding proto enum.
+
+    Args:
+      string_value: The string to convert to a proto enum.
+
+    Returns:
+      The corresponding proto enum or enum_unspecified when the enum message
+      doesn't exist.
+
+    Raises:
+      ValueError when given string is not found in the mapping.
+    """
+    if string_value is None:
+      return self.enum_unspecified
+
+    proto_name = self.mapping.get(string_value)
+    if proto_name:
+      try:
+        return self.enum_message.Value(proto_name)
+      except ValueError:
+        warnings.warn(
+            "Invalid %s value: %s. Resolving to %s."
+            % (
+                self.enum_message.DESCRIPTOR.name,
+                string_value,
+                self.enum_message.Name(self.enum_unspecified),
+            )
+        )
+        return self.enum_unspecified
+    else:
+      raise ValueError(
+          f"Unmatched {self.enum_message.DESCRIPTOR.name} value:"
+          f" {string_value}."
+      )
+
+  def from_proto(self, proto_enum: EnumType) -> str | DefaultType:
+    """Converts a proto enum to its string representation.
+
+    Args:
+      proto_enum: The enum value to convert to its string representation
+
+    Returns:
+      The string representation of the given proto_enum or the default value
+      when the proto enum is unspecified.
+
+    Raises:
+      ValueError when given proto enum is not found in the mapping.
+    """
+    if proto_enum == self.enum_unspecified:
+      warnings.warn(
+          "%s is unspecified. Resolving to default: %s."
+          % (
+              self.enum_display_name,
+              self.enum_message.Name(self.enum_unspecified),
+          )
+      )
+      return self.default_when_unspecified
+
+    try:
+      proto_name = self.enum_message.Name(proto_enum)
+    except ValueError as e:
+      raise ValueError(
+          f"Invalid {self.enum_message.DESCRIPTOR.name} proto enum value:"
+          f" {proto_enum}."
+      ) from e
+
+    try:
+      return self.mapping.inv[proto_name]
+    except KeyError as e:
+      raise KeyError(
+          f"Protobuf enum name '{proto_name}' is not configured in the mapping."
+      ) from e

google_meridian-1.3.2.dist-info/RECORD

@@ -1,76 +0,0 @@
-google_meridian-1.3.2.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-meridian/__init__.py,sha256=0fOT5oNZF7-pbiWWGUefV-ysafttieG079m1ijMFQO8,861
-meridian/constants.py,sha256=idvYuDmoULgHvVG5kGJb2j2VAdBF6BeOwDfKLP14-Fo,20322
-meridian/version.py,sha256=eMNUh0AywCHr0ZyrDyJchcddVsAyWWKKHuXI0VxLScE,644
-meridian/analysis/__init__.py,sha256=AM7xpqoeC-mmY4tPIyHisjQ2MICI7v3jSri--DhDqXA,874
-meridian/analysis/analyzer.py,sha256=qGKYoEpWC6pDf2sDrwLhpa2putDnpUzbBpuNqL1lGi4,219910
-meridian/analysis/optimizer.py,sha256=6OqJg8T09g4GqJc6_DnYDJsBAlY4ToUb3MRtS0EH4Nc,126316
-meridian/analysis/summarizer.py,sha256=pah0osYYJFQTf2Fn7-nnvxlBupf9cfaKW87bcqRO1A4,19036
-meridian/analysis/summary_text.py,sha256=I_smDkZJYp2j77ea-9AIbgeraDa7-qUYyb-IthP2qO4,12438
-meridian/analysis/test_utils.py,sha256=aZq88pxtpMHwhcpfYz8nHhR0Alhi_OvgS9qBR4LBgO0,78346
-meridian/analysis/visualizer.py,sha256=_z5vSnXyv3Zx4tmKLyevnMolzLzUzNFcNInOipEmMok,94092
-meridian/analysis/review/__init__.py,sha256=cF24EbhiVSs-tvtRf59uVin39tu6aCTTCaeEdv6ISZ8,804
-meridian/analysis/review/checks.py,sha256=QEUVwC8L9Pif3y0B_OVAUpZeN6EnFGKH2oXA_dsdgbc,26893
-meridian/analysis/review/configs.py,sha256=5JJ8v6n22GNBmE78xNX6jwdjkZz2qar4Q9YTcVqzcoI,3653
-meridian/analysis/review/constants.py,sha256=9tnnc_vAaJi9mnZ0GrRr86RsVq5fyhBaEtIvOLNmn8A,1498
-meridian/analysis/review/results.py,sha256=ZZiAdFrqySzcbjrCEacBLQS_ddiklZ34yD1BWns5SYI,17418
-meridian/analysis/review/reviewer.py,sha256=BcfmqHjp-30iZBlrzWfXDN1IJU-UIjINxZ7lsrj5Mts,6675
-meridian/backend/__init__.py,sha256=i2XOZnIPo3xAKpMGT39-4CVnVdf4cJyO0jB9FEE4zlQ,41337
-meridian/backend/config.py,sha256=B9VQnhBfg9RW04GNbt7F5uCugByenoJzt-keFLLYEp8,3561
-meridian/backend/test_utils.py,sha256=oJNosF_x_BzNuia8LzLFb_YfjGWHRCzR5FXNN5KQ8sw,13738
-meridian/data/__init__.py,sha256=StIe-wfYnnbfUbKtZHwnAQcRQUS8XCZk_PCaEzw90Ww,929
-meridian/data/arg_builder.py,sha256=Kqlt88bOqFj6D3xNwvWo4MBwNwcDFHzd-wMfEOmLoPU,3741
-meridian/data/data_frame_input_data_builder.py,sha256=_hexZMFAuAowgo6FaOGElHSFHqhGnHQwEEBcwnT3zUE,27295
-meridian/data/input_data.py,sha256=Qlxm4El6h1SRPsWDqZoKkOcMtrjiRWr3z8sU2mtghRA,43151
-meridian/data/input_data_builder.py,sha256=tbZjVXPDfmtndVyJA0fmzGzZwZb0RCEjXOTXb-ga8Nc,25648
-meridian/data/load.py,sha256=ETX8Z62Gk6JcxFxvyB4XQhpNcRSqBRIO4_sTAN58mCY,40172
-meridian/data/nd_array_input_data_builder.py,sha256=lfpmnENGuSGKyUd7bDGAwoLqHqteOKmHdKl0VI2wCQA,16341
-meridian/data/test_utils.py,sha256=mw-QPTP15oXf32I7cxMe8iSFBLB3seqEiITZMTz_Eg8,59838
-meridian/data/time_coordinates.py,sha256=C5A5fscSLjPH6G9YT8OspgIlCrkMY7y8dMFEt3tNSnE,9874
-meridian/mlflow/__init__.py,sha256=elwXUqPQYi7VF9PYjelU1tydfcUrmtuoq6eJCOnV9bk,693
-meridian/mlflow/autolog.py,sha256=SZsrynLjozcyrAFCNWiqchSa2yOszVnwFBGz23BmWUU,6379
-meridian/model/__init__.py,sha256=mhF5VkRxvwamRa_0AihgbFuXLMueRCK-Je_ZZvU5IFw,1013
-meridian/model/adstock_hill.py,sha256=HoRKjyL03pCTBz6Utof9wEvlQCFM43BvrEW_oupj7NU,17688
-meridian/model/knots.py,sha256=B78oTQ97Zd0aON4CnhMPqJZ4eamy6d-esKMWqoDf9uQ,27273
-meridian/model/media.py,sha256=skjy4Vd8LfDQWlqR_2lJ1qbG9UcS1dow5W45BAu4qk8,14599
-meridian/model/model.py,sha256=jMtfl7woWtJ8M8AX42QeZ5hUS8hlhPdZ-9OU8KahjKA,68984
-meridian/model/model_test_data.py,sha256=XGBz8RGdCsjAUOmgxX3CfWSj-_hdq2Lc8saFCqmImwM,23901
-meridian/model/posterior_sampler.py,sha256=f3MayglIgBeBjWeXJU_RgT9cCugcjJ3aEjHqaWPsTbg,26806
-meridian/model/prior_distribution.py,sha256=ZArW4uXIPPQL6hRWiGZUzcHktbkjE_vOklvlbp9LR64,57662
-meridian/model/prior_sampler.py,sha256=iLvCefhA4WY0ENcnLK9471WUZPPyzQ1je58MRjxKv74,25460
-meridian/model/spec.py,sha256=VlK6WJiPo2lzOF0O2judtJ6O3uEw7wYL5AT8bioq4gE,19188
-meridian/model/transformers.py,sha256=HxlVJitxP-wu-NOHU0tArFUZ4NAO3c7adAYj4Zvqnvo,8363
-meridian/model/eda/__init__.py,sha256=bMj9kd2LWU_LQZAjQv54FFggzdv4CKRYblvc-0cHXc4,768
-meridian/model/eda/constants.py,sha256=Kt8x8hvC2WkeEtW0Wmid8GkqZbh_p6NdiZ_A5V3qzwM,1031
-meridian/model/eda/eda_engine.py,sha256=AxvKxdH8Q_TWlGZ58bWcfGMSgxkHZ2wrHloPuzS5C4Y,73324
-meridian/model/eda/eda_outcome.py,sha256=cR9M49e6bDrBNxHOThW3aQlX5gZCOENC7GBljKQx7OY,6475
-meridian/model/eda/eda_spec.py,sha256=diieYyZH0ee3ZLy0rGFMcWrrgiUrz2HctMwOrmtJR6w,2871
-meridian/templates/card.html.jinja,sha256=gaQSHh8xN-LqHzI-xsHaORsaeOD7hnxkq-Fcw-ytZ8M,1284
-meridian/templates/chart.html.jinja,sha256=j8rNLOfXxKx4f5TpP9_W8uCM8zKys8ga75jv-XCny2g,1086
-meridian/templates/chips.html.jinja,sha256=IhPmAI7qZkXj5NeLUKVMCSKFzwv9yR8Qq140t36U10A,1030
-meridian/templates/formatter.py,sha256=75KtZA2y6iyxpkVM3CLmpUtJ1-umBP9xXxdXkkSZcr8,7547
-meridian/templates/formatter_test.py,sha256=nlefFTQaSArNyZWzGUuzCKtt3P3PJNZFmkGm0XMYwBY,8543
-meridian/templates/insights.html.jinja,sha256=IRm49X49HZX-rc6z0uZmpsA_1JLD83UhI2BacOanHLY,606
-meridian/templates/stats.html.jinja,sha256=JMRC_W2PyReU30ISOd8uv2ugDpYmSU3XtPk2OTsaQus,772
-meridian/templates/style.css,sha256=O7YCKVqXgK4Ms3nnGmCVW4hILn4GCBRe4e15XJaP4ww,5492
-meridian/templates/style.scss,sha256=he5jXpGatNfI6vtNbqdENapLiwIlXjqIBkKwxNVEvyw,5076
-meridian/templates/summary.html.jinja,sha256=kR4nQc-oGBwXN6buKcf_wPaoWASomR4fT4gJ1iD9hYw,1775
-meridian/templates/table.html.jinja,sha256=ibgnjdKCjS2qbq61lxqwtlb7JigDrc2m42RDdQvQnKQ,1176
-schema/__init__.py,sha256=grEfsjrcPRzhd89ZXLggnBnrryl97bsayKWP1ue1ffE,1206
-schema/serde/__init__.py,sha256=xyydIcWB5IUpcn3wu1m9HL1fK4gMWURbwTyRsQtolF0,975
-schema/serde/constants.py,sha256=aYtD_RuA0GCkpC4TIQq3VjMqEc837Wn-TlJNm-yn_4Y,1842
-schema/serde/distribution.py,sha256=jy3h6JD1TSs4gwociMis814sz_Fm2kFQ2UbkgjYJW9k,19347
-schema/serde/eda_spec.py,sha256=uOqBeZpUU3Dzzc19rU1LjHWmUhRmVcx8oIZvZfVJHT8,7180
-schema/serde/function_registry.py,sha256=GbgC5_9NDcA9Y7nqmdJ-4-LK5JPhhfI50Lmfy5ZBJOg,4858
-schema/serde/hyperparameters.py,sha256=Igm-PZmIozrsKZH6c-XkrU_Nlf8OAuxpnJJfv7W1SfQ,13524
-schema/serde/inference_data.py,sha256=DrwE9hU8LMrl0z8W_sUSIaPrRdym_lu0iOqpT4KZxsA,3623
-schema/serde/marketing_data.py,sha256=yb-fRTe84Sjg7-v3wsvYRRXvrxLSFWSenO0_ikMvUpk,44845
-schema/serde/meridian_serde.py,sha256=ZG05JaBG4LW8mhl-Cunje9Q6xyR4tyNTtLYedzMBYjA,15985
-schema/serde/serde.py,sha256=8vUqhJxvZgX9UY3rXTyWJznRgapwDzzaHXDHwV_kKTA,1612
-schema/serde/test_data.py,sha256=7hfEWyvZ9WcAkVAOXt6elX8stJlsfhfd-ASlHo9SRb8,107342
-schema/utils/__init__.py,sha256=AkC4NMbmXC3PFBY9dFYxlf3qFsxt5OOBVdc9zmFXsC8,675
-schema/utils/time_record.py,sha256=-KzHFjvSBUUXsfESPAfcJP_VFxaFLqj90Ac0kgKWfpI,4624
-google_meridian-1.3.2.dist-info/METADATA,sha256=BHbc_4zpZ5EBv1urcvQR_brE9WEJaia4F1ZLYaA8sG0,9545
-google_meridian-1.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-google_meridian-1.3.2.dist-info/top_level.txt,sha256=yWkWDLV_UUanhKmk_xNPiKNdPDl1oyU1sBYwEnhaSf4,16
-google_meridian-1.3.2.dist-info/RECORD,,