data-privacy 0.1.0__py3-none-any.whl

data_privacy/__init__.py

@@ -0,0 +1,7 @@
+
+from . import dataset, measure, anonymity, channel, mechanism, strategy
+
+__version__ = '0.1.0'
+
+__all__ = ["dataset", "measure", "anonymity", "channel", "mechanism", "strategy"]
+

data_privacy/anonymity.py

@@ -0,0 +1,19 @@
+import pandas as pd
+
+def max_kanonymity(D):
+    '''Outputs the maximum value of k for which D represents a k-anonymous dataset. D is
+    a pandas dataframe created using the make_channel function.'''
+    return D.astype(bool).sum(axis=0).min()
+
+def is_kanonymous(D, k):
+    '''Outputs true if the dataset D satisfies k-anonymity. D is a pandas dataframe
+    created using the make_channel function.'''
+    max_k = max_kanonymity(D)
+    return max_k >= k
+
+def vulnerable_identifiers(D, k):
+    '''Outputs the column names for which k-anonymity does not hold.'''
+    # k_values contains the k-anonymity value for each column
+    k_values = D.astype(bool).sum(axis=0)
+    # return the column names and k-anonymity values for which k_values are < k.
+    return k_values[k_values < k]

data_privacy/channel.py

@@ -0,0 +1,79 @@
+import pandas as pd
+import numpy as np
+import math
+from itertools import product
+import pyqif as pyq
+import privacybook.strategy as strategy
+
+def compose(C, D):
+    '''Constructs the perturbation channel corresponding to the composition of
+    the channels C and D. Assumes that the columns of C match the rows of D.'''
+    C_values = C.to_numpy()
+    D_values = D.to_numpy()
+    composition = np.matmul(C_values, D_values)
+    return pd.DataFrame(data=composition, index=C.index, columns=D.columns)
+
+def kroneckerN(C, n):
+    '''Computes the n-fold Kronecker product of channel C with itself.'''
+    # Use underlying pyqif library to kronecker the channel
+    Ch = C.to_numpy()
+    ChN = pyq.compose.kroneckerN(Ch, n)
+
+    # Compute cartesian product of labels
+    states = list(product(C.index, repeat=n))
+    idx = pd.MultiIndex.from_tuples(
+        states,
+        names=[f"X{i+1}" for i in range(n)]
+    )
+    # Put channel back together with labels
+    Kn = pd.DataFrame(ChN, index=idx, columns=idx)
+    return Kn
+
+def inputs_at_risk(C):
+    '''
+    Returns the row indices of the channel C for which the secrets can be identified completely.
+    A secret is fully identified if there exists a column for which this secret is the only non-zero
+    value in the column.
+    '''
+    # Assume C is a channel with secrets as row labels
+    # We first count the number of non-zero values in each column
+    counts = C.astype(bool).sum(axis=0)
+    # Now we find the secrets that correspond to single non-zero values in a column
+    inputs = counts.index[counts == 1]
+    return inputs
+
+def inputs_at_high_risk(C, p):
+    '''Returns a list of row indices (secrets) for which the adversary can guess the secret
+    with probability ≥ p under a uniform prior.
+    '''
+    # Compute the posterior matrix under uniform prior
+    u = pyq.probab.uniform(C.shape[0])
+    P = pyq.channel.posteriors(u, C.to_numpy())
+    P_df = pd.DataFrame(data=P, index=C.index, columns=C.columns)
+    maxes = P_df.max()
+    return maxes.index[maxes >  p]
+
+def inputs_at_linkage_risk(C, attrs):
+    '''Returns the secrets which can be perfectly identified by the QIDs in attrs.
+    '''
+    # Assume that C is a channel returned by make_channel.
+    # Assume also that attrs is a subset of the QIDs.
+
+    # Group the secrets by the attrs
+    groups = C.T.groupby(attrs).sum()
+
+    # Count how many QIDs are unique to a secret
+    summary = groups.astype(bool).T.sum()
+
+    vulnerable_attrs = summary.index[summary == 1]
+    vulnerable_secrets = C[vulnerable_attrs].astype(bool).sum(axis=1)
+    return vulnerable_secrets.index[vulnerable_secrets == 1]
+
+def inputs_at_inference_risk(C, D):
+    '''Returns the list of of secrets that are at risk from being inferred
+    through linking C and D.
+    '''
+    # Assume that C and D are channels created by make_channel.
+    # Assume that the outputs of C correspond with the inputs of D.
+    CD = strategy.linkage(C, D)
+    return inputs_at_risk(CD)

data_privacy/dataset.py

@@ -0,0 +1,33 @@
+import pandas as pd
+
+#
+# make_channel
+#
+# Inputs:
+# - inputTable: dataframe representing a dataset
+# - secretsList: array of column names representing secrets
+# - qidsList: array of column names representing QIDs
+#
+# Returns:
+#  - dataframe representing a channel: rows are labelled with
+# secrets and columns are labelled with QIDs
+#
+
+def make_channel(inputTable, secretsList, qidsList):
+    '''Create a channel from a tabular datasource given as a pandas frame.
+    The row and column labels are also provided as secretsList and qidsList
+    respectively.'''
+
+    # Group by QIDs + secrets → counts
+    counts = inputTable.groupby(qidsList + secretsList).size()
+
+    # Reshape into QID (columns) × Secret (rows)
+    channel = counts.unstack(level=qidsList, fill_value=0)
+
+    # Convert counts into probabilities
+    row_sums = channel.sum(axis=1)
+    prob_channel = channel.div(row_sums, axis="index")
+
+    return prob_channel
+
+

data_privacy/measure.py

@@ -0,0 +1,101 @@
+from scipy.spatial.distance import pdist, squareform
+import pyqif as pyq
+import numpy as np
+
+def quasi_identification_risk(D):
+    # Pre: D is a dataframe
+    c = D.to_numpy() # Convert DataFrame to NumPy array
+    u = pyq.probab.uniform(c.shape[0])
+
+    # Return average risk across all individuals
+    return pyq.measure.vg.posterior_bayes(u, c)
+
+#
+# This function computes the bayes capacity of the channel, which is the
+# sum of the column maxima.
+#
+def reidentification_risk(D):
+    '''Computes the Bayes' capacity for the channel DBN, which corresponds to the
+    leakage due to the channel for an adversary who wants to perform a reidentification
+    attack (guessing the secret exactly in 1 try). Ranges from 1 (no leak) to #columns in
+    channel (full leakage)'''
+    return quasi_identification_risk(D)
+    #ch = D.to_numpy()
+    #return pyq.measure.bayes_capacity(ch)
+
+#
+# Computes the posterior vulnerability of the attribute with respect to 
+# a uniform prior. This gives the probability of a successful property
+# inference against a given sensitive attribute for an adversary with no
+# prior knowledge.
+#
+def property_inference_risk(D, attr):
+    '''Computes the risk of inferring a sensitive attribute in the dataset D.
+    This assumes an adversary who has a uniform prior over all secrets.'''
+    attr_i = D.index.names.index(attr)
+    # Combine all rows with the same sensitive attribute
+    # by computing their mean (equivalent to uniform prior)
+    D_by_attr = D.groupby(level=[attr_i]).mean()
+    u = pyq.probab.uniform(D_by_attr.shape[0])
+    return pyq.measure.vg.posterior_bayes(u, D_by_attr.to_numpy())
+
+# 
+# Computes the risk of guessing the secret given knowledge of the attributes
+# in the attrs array, under a uniform prior. 
+#
+def linkability_risk(C, attrs):
+    '''Outputs the risk of reconstructing the full secret in channel C,
+    relative to linking via attributeList (quasi-identifiers).
+    A row is considered at risk if its projection on the attributeList is unique.
+    '''
+    # For this we assume C is a channel produced by make_channel.
+    # We assume attrs is a subset of the QIDs in C.
+
+    # Group the secrets by the attrs
+    groups = C.T.groupby(attrs).sum()
+
+    # Count how many QIDs are unique to a secret
+    summary = groups.astype(bool).T.sum()
+
+    # Identify the vulnerable secrets as ones which contain a single non-zero value
+    # Note that these are actually the QIDs since we have transposed the channel
+    vulnerable_attrs = summary.index[summary == 1]
+
+    # Add up all the probabilities for the vulnerable inputs.
+    prob = groups.loc[vulnerable_attrs, ].max(axis=1).sum()
+
+    # Now have to divide probability by size of secret space, equivalent to uniform prior
+    num_secrets = C.index.size
+    return prob / num_secrets
+
+
+def __dist_arr(C, values):
+    val_arr = np.array([ [i] for i in values ])
+    dists = pdist(val_arr)
+    # create the loss function which gives the abs distance between values of attr
+    dists_arr = squareform(dists)
+    return dists_arr
+
+def average_minimum_error(C, attr):
+    '''Computes the expected distance of the true value from the output value for
+    the given attribute in the channel D.'''
+    # C is a pandas dataframe representing a channel which takes secrets X to observations Y.
+    # We assume that the given attribute is numeric so we can compute a mean error
+    # between the guessed value of the attribute and the true value.
+    values = C.index.get_level_values(attr).to_numpy()
+    dists_arr = __dist_arr(C, values)
+    avg_uncertainty = pyq.measure.ul.posterior(pyq.probab.uniform(len(values)), C.to_numpy(), dists_arr)
+    return avg_uncertainty
+
+def likely_interval(D, attr, c):
+    '''Computes the probability that an adversary cannot infer the value of attr
+    to within bound c of its true value.'''
+    # The implementation of this uses the loss function from average_minimum_error
+    # and converts the distances to bits depending on c.
+    values = D.index.get_level_values(attr).to_numpy()
+    dists_arr = __dist_arr(D, values)
+    # convert distance matrix to bit matrix
+    bits_arr = np.array( [ [ int(i<c) for i in row] for row in dists_arr])
+    avg_uncertainty = pyq.measure.ul.posterior(pyq.probab.uniform(len(values)), D.to_numpy(), bits_arr)
+    return avg_uncertainty
+

data_privacy/mechanism.py

@@ -0,0 +1,119 @@
+import pandas as pd
+import numpy as np
+import pyqif as pyq
+import math
+
+def bounded_noise(D, attr, noise):
+    '''Creates a customised bounded noise channel using the given noise
+    distribution. For example, noise which returns the same value with prob.
+    1/2, and returns the value +- 1 with prob. 1/4 (each) would look like:
+    noise=pd.Series([ 1/4, 1/2, 1/4], index=[-1, 0, 1]).'''
+    try:
+        attr_i = D.columns.names.index(attr)
+        noise_labels = noise.index
+        df = pd.DataFrame()
+        for col_i in range(len(D.columns)):
+            v = D.columns[col_i][attr_i] # the value of the attr to add noise to
+            if int(v) != v:
+                raise Exception("The given attribute is not numeric")
+            # Create a new channel with labels as noisy attrs, values
+            # are the probabilities.
+            def get_noisy_qid(noise_i):
+                qid = list(D.columns[col_i])
+                qid[attr_i] += noise_labels[noise_i]
+                return qid
+            tuples = list([ get_noisy_qid(idx) for idx in range(len(noise_labels))])
+            result = pd.MultiIndex.from_tuples(tuples, names=D.columns.names)
+            multirow = pd.Series(noise.to_numpy(), index=result, name=D.columns[col_i])
+            df = pd.concat([df, multirow.to_frame().T])
+        df = df.fillna(0)
+        # Fix up the names for the rows (secrets)
+        df.index = df.index.set_names(D.columns.names)
+        return df
+    except ValueError:
+        print("Error: no such attribute name: ", attr)
+    except Exception as inst:
+        print(inst)
+    return None
+
+
+def uniform_bounded_noise(D, attr, bound):
+    '''Computes a bounded noise channel for perturbing the attribute in a given channel D
+    using the given bound. For example, if bound=1 and attr="age", then each age in
+    the dataset D should be perturbed by either adding 1, returning unchanged or subtracting 1,
+    each with probability 1/3 (uniform).'''
+    noise_prob = 1.0 / (2 * bound + 1) # uniform prob over values
+    noise = pd.Series(noise_prob, index=list(range(-bound, bound+1)))
+    return bounded_noise(D, attr, noise)
+
+
+def random_response(D, attr, K, eps):
+    '''Given the dataset channel D and an attribute attr, computes the random
+    response channel applied to attr with range K and epsilon eps. Note that attr
+    (and K) can be categorical (string valued) or numeric.'''
+    # RR channel has entries q = 1 / (len(K) - 1 + e **eps) 
+    # and single entry p = e**eps/(len(K) - 1 + e ** eps)
+    q = 1 / (len(K) -1 + (math.e ** eps))
+    p = q * (math.e ** eps)
+    try:
+        attr_i = D.columns.names.index(attr)
+        df = pd.DataFrame()
+        for col_i in range(len(D.columns)):
+            v = D.columns[col_i][attr_i] # the value of the attr to add noise to
+            #if int(v) != v:
+            #    raise Exception("The given attribute is not numeric")
+            qid = list(D.columns[col_i]) # the value of the QID for this column
+            # We want to replace the value at index attr_i with the range of K
+            tuples = [ qid[:attr_i] + [noise_i] + qid[attr_i+1:] for noise_i in K]
+            result = pd.MultiIndex.from_tuples(tuples, names=D.columns.names)
+            # Random response noise is almost all the same
+            noise = [q] * len(K)
+            # We need the index of v in K
+            if not v in K:
+                raise Exception("The attribute " + str(v) + " lies outside the range " + str(K))
+            noise[K.index(v)] = p
+            multirow = pd.Series(noise, index=result, name=D.columns[col_i])
+            df = pd.concat([df, multirow.to_frame().T])
+        df = df.fillna(0)
+        # Fix up the names for the rows (secrets)
+        df.index = df.index.set_names(D.columns.names)
+        return df
+    except ValueError:
+        print("Error: no such attribute name: ", attr)
+    except Exception as inst:
+        print(inst)
+    return None
+
+def geometric(D, attr, K, eps):
+    '''Given the dataset channel D and a numeric attribute attr, computes the geometric
+    channel for adding noise to attr with range K and epsilon eps.'''
+    # We start by just generating geometric noise as a numpy array
+    G_channel = pyq.dp.ranged_geometric(K, eps)
+    try:
+        attr_i = D.columns.names.index(attr)
+        df = pd.DataFrame()
+        for col_i in range(len(D.columns)):
+            v = D.columns[col_i][attr_i] # the value of the attr to add noise to
+            if int(v) != v:
+                raise Exception("The given attribute is not numeric")
+            qid = list(D.columns[col_i]) # the value of the QID for this column
+            # We want to replace the value at index attr_i with the range of K
+            tuples = [ qid[:attr_i] + [noise_i] + qid[attr_i+1:] for noise_i in K]
+            result = pd.MultiIndex.from_tuples(tuples, names=D.columns.names)
+            # Get the noise from the correct row of the geometric mechanism
+            # We need the index of v in K
+            if not v in K:
+                raise Exception("The attribute " + str(v) + " lies outside the range " + str(K))
+            noise = G_channel[K.index(v)]
+            multirow = pd.Series(noise, index=result, name=D.columns[col_i])
+            df = pd.concat([df, multirow.to_frame().T])
+        df = df.fillna(0)
+        # Fix up the names for the rows (secrets)
+        df.index = df.index.set_names(D.columns.names)
+        return df
+    except ValueError:
+        print("Error: no such attribute name: ", attr)
+    except Exception as inst:
+        print(inst)
+    return None
+

data_privacy/strategy.py

@@ -0,0 +1,21 @@
+import pandas as pd
+import numpy as np
+import pyqif as pyq
+
+def intersection(C, D):
+    '''Constructs the intersection attack channel for an adversary who
+    has access to 2 channels C, D on the same inputs. Corresponds to a
+    parallel composition of channels.'''
+    #Pre: Channels C, D must have the same number of rows
+    CD = pyq.compose.parallel(C.to_numpy(), D.to_numpy())
+    # Recompute the columns
+    cols = np.array(np.meshgrid(C.columns.names, D.columns.names)).T.reshape(-1, 2)
+    return pd.DataFrame(data=CD, index=D.index, columns=cols)
+
+def linkage(C, D):
+    '''Computes the linkage attack matrix which utilises the
+    correlation between observations on C and inputs on D.
+    '''
+    # Assume that C and D are channels created using make_channel
+    return C.dot(D)
+

data_privacy-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: data-privacy
+Version: 0.1.0
+Summary: Utilities for ...
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Dynamic: license-file
+
+# A First Course in Data Privacy
+
+This is the codebase supporting the textbook on privacy for undergraduates.
+

data_privacy-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+data_privacy/__init__.py,sha256=5wK7gZFJryHPu7-Tq4tjw6cNwBW6Zg9EIZiCOmxj3Zs,180
+data_privacy/anonymity.py,sha256=CRSNdCvbDsThDYFPF-S1Q-nx79_D-TAVKB-b2U-ArfY,780
+data_privacy/channel.py,sha256=ZEXO1jW604ThQaG7FFyiL0M8DsSocJcVFd4UpFDVsrU,2970
+data_privacy/dataset.py,sha256=g99DQUlUf3iqX96cjDFOvZaf8jn-1yv0c8cHVgIkI6E,934
+data_privacy/measure.py,sha256=hpyb_OW96qwyAeMMvemHM3_HB8uhx9h36SMhInUYZIM,4315
+data_privacy/mechanism.py,sha256=VTDgt9EoHzStvOzqIGgIDzGuCL2PdKMCTA-Sl5No0DE,5577
+data_privacy/strategy.py,sha256=o8tEEcnen7rTFDVUU7U6zDPhhq6CsOi2stM0LeBOYLM,792
+data_privacy-0.1.0.dist-info/licenses/LICENSE,sha256=ayCLTzh9dbPVd0dkMqrBEF-NgtcQ8s_UwPHsjpeHiEw,1063
+data_privacy-0.1.0.dist-info/METADATA,sha256=_B3WqcJHQu9yUc00JSuLzfwdURn3AObMdJQW507iCGo,366
+data_privacy-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+data_privacy-0.1.0.dist-info/top_level.txt,sha256=dFbMTVofI5JaKcs3t3ka489mQbJw9te7rECLaxQ4894,13
+data_privacy-0.1.0.dist-info/RECORD,,

data_privacy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

data_privacy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Topete
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data_privacy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+data_privacy