bw_temporalis.utils
===================

.. py:module:: bw_temporalis.utils


Exceptions
----------

.. autoapisummary::

   bw_temporalis.utils.IncongruentDistribution


Functions
---------

.. autoapisummary::

   bw_temporalis.utils.check_database_exchanges
   bw_temporalis.utils.easy_datetime_distribution
   bw_temporalis.utils.easy_timedelta_distribution
   bw_temporalis.utils.get_version_tuple
   bw_temporalis.utils.normalized_data_array


Module Contents
---------------

.. py:exception:: IncongruentDistribution

   Bases: :py:obj:`Exception`


   The sum of `TemporalDistribution` values is different than the exchange

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: check_database_exchanges(database_label: str) -> None

   Check the sum of an exchange ``TemporalDistribution.amount`` is close to its ``amount`` value.

   :raises IncongruentDistribution: If the two values are more than 1 percent different

   :param database_label: Name of database to check
   :type database_label: str


.. py:function:: easy_datetime_distribution(start: str, end: str, steps: int | None = 50, kind: str | None = 'uniform', param: float | None = None) -> bw_temporalis.temporal_distribution.TemporalDistribution

   Generate a datetime `TemporalDistribution` with a few input parameters.

   Can generate distributions whose `amount` values are uniformly,
   triangularly, or normally distributed. Please build more complicated
   distributions manually.

   Only the `amount` values are distributed, the resulting distribution
   `date` values are uniformly spaced from `start` to `end`.

   For triangular distributions, `param` is the mode (optional), and should
   be given in the same reference system as `start` and `stop`. The `param`
   value should be in the same format as `start` and `end`, e.g.
   "2023-01-01".

   For normal distributions, `param` is the standard deviation in relation
   to a standardized distribution with mu = 0. `param` is not used for the uniform distribution.

   :raises ValueError: If the input parameters prevent construction of valide `TemporalDistribution`.

   :param start: Datetime marking the start (inclusive) of the distribution, e.g. "now", "2023-02-01", "2023-03-02T12:34:56"
   :type start: str
   :param end: Datetime marking the end (inclusive) of the distribution, e.g. "now", "2023-02-01", "2023-03-02T12:34:56"
   :type end: str
   :param steps: Number of values in discrete distribution. Normally not more than 50 or 100.
   :type steps: int, optional
   :param kind: Distribution type. Must be one of "uniform", "triangular", or "normal"
   :type kind: str, optional
   :param param: Input parameter to define triangular or normal distribution
   :type param: float, optional

   :rtype: A `TemporalDistribution` instance.


.. py:function:: easy_timedelta_distribution(start: int, end: int, resolution: str, steps: int | None = 50, kind: str | None = 'uniform', param: float | None = None) -> bw_temporalis.temporal_distribution.TemporalDistribution

   Generate a timedelta `TemporalDistribution` with a few input parameters.

   Can generate distributions whose `amount` values are uniformly, triangularly, or normally distributed. Please build more complicated distributions manually.

   Only the `amount` values are distributed, the resulting distribution `date` values are uniformly spaced from `start` to `end`.

   For triangular distributions, `param` is the mode (optional). For lognormal distributions, `param` is the standard deviation (required). `param` is not used for the uniform distribution.

   :raises ValueError: If the input parameters prevent construction of valide `TemporalDistribution`.

   :param start: Start (inclusive) of the distribution in `resolution` units
   :type start: int
   :param end: End (inclusive) of the distribution in `resolution` units
   :type end: int
   :param resolution: Resolution of the created `timedelta64` array. One of `Y` (year), `M` (month), `D` (day), `h` (hour), `m` (minute), `s` (second)
   :type resolution: str
   :param steps: Number of values in discrete distribution. Normally not more than 50 or 100.
   :type steps: int, optional
   :param kind: Distribution type. Must be one of "uniform", "triangular", or "normal"
   :type kind: str, optional
   :param param: Input parameter to define triangular or normal distribution
   :type param: float, optional

   :rtype: A `TemporalDistribution` instance.


.. py:function:: get_version_tuple() -> tuple

.. py:function:: normalized_data_array(steps: int, kind: str, param: float | None) -> numpy.typing.NDArray[int]