cdpg_anonkit.noise
==================

.. py:module:: cdpg_anonkit.noise


Classes
-------

.. autoapisummary::

   cdpg_anonkit.noise.DifferentialPrivacy


Functions
---------

.. autoapisummary::

   cdpg_anonkit.noise.example_differential_privacy_usage


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

.. py:class:: DifferentialPrivacy(mechanism: Literal['laplace', 'gaussian', 'exponential'], epsilon: float = 1.0, delta: Optional[float] = None, sensitivity: Optional[float] = None)

   Differential Privacy mechanism with support for various noise addition strategies.

   Focuses on fundamental DP principles with extensibility in mind.


   .. py:attribute:: mechanism


   .. py:attribute:: epsilon
      :value: 1.0



   .. py:attribute:: delta
      :value: None



   .. py:attribute:: _sensitivity
      :value: None



   .. py:method:: clip_count(count: int, lower_bound: int = 0, upper_bound: Optional[int] = None) -> int
      :staticmethod:


      Clip the count to a specified range.

      This static method ensures that the count provided falls within the
      specified lower and upper bounds. If the upper bound is not provided,
      the count is clipped to the lower bound only.

      :param count: The original count to be clipped.
      :type count: int
      :param lower_bound: The minimum value to clip to, by default 0.
      :type lower_bound: int, optional
      :param upper_bound: The maximum value to clip to, by default None.
      :type upper_bound: Optional[int], optional

      :returns: The clipped count, constrained by the specified bounds.
      :rtype: int



   .. py:method:: compute_sensitivity(query_type: str = 'count', lower_bound: int = 0, upper_bound: Optional[int] = None) -> float

      Compute the sensitivity of a query based on its type and bounds.

      Sensitivity is a measure of how much the output of a query can change by
      modifying a single record in the dataset. It is crucial for determining
      the amount of noise to add in differential privacy mechanisms.

      :param query_type: The type of query for which sensitivity is being computed.
                         Currently supported: 'count'. Defaults to 'count'.
      :type query_type: str, optional
      :param lower_bound: The minimum value constraint for the query. Defaults to 0.
      :type lower_bound: int, optional
      :param upper_bound: The maximum value constraint for the query. If None, no upper
                          bound is considered. Defaults to None.
      :type upper_bound: Optional[int], optional

      :returns: The sensitivity of the query. For 'count' queries, this is 1.0.
      :rtype: float

      :raises ValueError: If the sensitivity computation for the specified query_type is
          not implemented.



   .. py:method:: add_noise(value: Union[int, float], sensitivity: Optional[float] = None, epsilon: Optional[float] = None) -> Union[int, float]

      Add noise to a given value according to the specified differential privacy mechanism.

      Depending on the mechanism set during initialization, this method will add
      noise to the input value to ensure differential privacy. Currently, the Laplace
      mechanism is implemented, with plans to support Gaussian and Exponential mechanisms.

      :param value: The original value to which noise will be added.
      :type value: Union[int, float]
      :param sensitivity: The sensitivity of the query. If not provided, the class-level sensitivity
                          will be used. Defaults to None.
      :type sensitivity: Optional[float], optional
      :param epsilon: The privacy budget. If not provided, the class-level epsilon will be used.
                      Defaults to None.
      :type epsilon: Optional[float], optional

      :returns: The value with added noise according to the specified mechanism.
      :rtype: Union[int, float]

      :raises ValueError: If the Gaussian mechanism is selected but delta is not specified.
          If the mechanism is unsupported.
      :raises NotImplementedError: If the Gaussian or Exponential mechanism is selected, as they are not yet implemented.



.. py:function:: example_differential_privacy_usage()

   Demonstrate usage of Differential Privacy with count query.

   Assumes IncrementalGroupbyAggregator has been used to compute base counts.