opendp.mod module#

class opendp.mod.Measurement[source]#

Bases: opendp.mod.LP_AnyMeasurement

A differentially private unit of computation. A measurement contains a function and a privacy relation. The function releases a differentially-private release. The privacy relation maps from an input metric to an output measure.

Example

>>> from opendp.mod import Measurement
>>>
>>> # create an instance of Measurement using a constructor from the meas module
>>> from opendp.meas import make_base_geometric
>>> base_geometric: Measurement = make_base_geometric(scale=2., lower=0, upper=20)
>>>
>>> # invoke the measurement (invoke and __call__ are equivalent)
>>> base_geometric.invoke(100)  # -> 101
>>> base_geometric(100)  # -> 99
>>>
>>> # check the measurement's relation at
>>> #     (1, 0.5): (AbsoluteDistance<u32>, MaxDivergence)
>>> assert base_geometric.check(1, 0.5)
>>>
>>> # chain with a transformation from the trans module
>>> from opendp.trans import make_count
>>> from opendp.typing import SubstituteDistance
>>> chained = (
>>>     make_count(MI=SubstituteDistance, TI=int) >>
>>>     base_geometric
>>> )
>>>
>>> # the resulting measurement has the same features
>>> chained([1, 2, 3])  # -> 4
>>> # check the chained measurement's relation at
>>> #     (1, 0.5): (SubstituteDistance, MaxDivergence)
>>> assert chained.check(1, 0.5)
check(d_in, d_out, *, debug=False)[source]#

Check if the measurement satisfies the privacy relation at d_in, d_out.

Parameters
  • d_in – Distance in terms of the input metric.

  • d_out – Distance in terms of the output measure.

  • debug – Enable to raise Exceptions to help identify why the privacy relation failed.

Returns

If True, a release is differentially private at d_in, d_out.

Return type

bool

property input_carrier_type#

Retrieve the carrier type of the input domain. Any member of the input domain is a member of the carrier type.

Returns

carrier type

property input_distance_type#

Retrieve the distance type of the input metric. This may be any integral type for dataset metrics, or any numeric type for sensitivity metrics.

Returns

distance type

invoke(arg)[source]#

Create a differentially-private release with arg.

Parameters

arg – Input to the measurement.

Returns

differentially-private release

Raises

OpenDPException – packaged error from the core OpenDP library

property output_distance_type#

Retrieve the distance type of the output measure. This is the type that the budget is expressed in.

Returns

distance type

exception opendp.mod.OpenDPException(variant, message=None, inner_traceback=None)[source]#

Bases: Exception

General exception for errors originating from the underlying OpenDP library. The variant attribute corresponds to one of the following variants and can be matched on. Error variants may change in library updates.

Parameters
  • variant (str) –

  • message (str) –

  • inner_traceback (str) –

class opendp.mod.Transformation[source]#

Bases: opendp.mod.LP_AnyTransformation

A non-differentially private unit of computation. A transformation contains a function and a stability relation. The function maps from an input domain to an output domain. The stability relation maps from an input metric to an output metric.

Example

>>> from opendp.mod import Transformation
>>>
>>> # create an instance of Transformation using a constructor from the trans module
>>> from opendp.trans import make_count
>>> count: Transformation = make_count(MI=SymmetricDistance, TI=int)
>>>
>>> # invoke the transformation (invoke and __call__ are equivalent)
>>> count.invoke([1, 2, 3])  # -> 3
>>> count([1, 2, 3])  # -> 3
>>>
>>> # check the transformation's relation at
>>> #     (1, 1): (SymmetricDistance, AbsoluteDistance<u32>)
>>> assert count.check(1, 1)
>>>
>>> # chain with more transformations from the trans module
>>> from opendp.trans import make_split_lines, make_cast
>>> from opendp.typing import SymmetricDistance
>>> chained = (
>>>     make_split_lines(M=SymmetricDistance) >>
>>>     make_cast(M=SymmetricDistance, TI=str, TO=int) >>
>>>     count
>>> )
>>>
>>> # the resulting transformation has the same features
>>> chained("1\n2\n3")  # -> 3
>>> assert chained.check(1, 1)  # both chained transformations were 1-stable
check(d_in, d_out, *, debug=False)[source]#

Check if the transformation satisfies the stability relation at d_in, d_out.

Parameters
  • d_in – Distance in terms of the input metric.

  • d_out – Distance in terms of the output metric.

  • debug – Enable to raise Exceptions to help identify why the stability relation failed.

Returns

True if the relation passes. False if the relation failed.

Return type

bool

Raises

OpenDPException – packaged error from the core OpenDP library

property input_carrier_type#

Retrieve the carrier type of the input domain. Any member of the input domain is a member of the carrier type.

Returns

carrier type

property input_distance_type#

Retrieve the distance type of the input metric. This may be any integral type for dataset metrics, or any numeric type for sensitivity metrics.

Returns

distance type

invoke(arg)[source]#

Execute a non-differentially-private query with arg.

Parameters

arg – Input to the transformation.

Returns

non-differentially-private answer

Raises

OpenDPException – packaged error from the core OpenDP library

property output_distance_type#

Retrieve the distance type of the output metric. This may be any integral type for dataset metrics, or any numeric type for sensitivity metrics.

Returns

distance type

exception opendp.mod.UnknownTypeException[source]#

Bases: Exception