S3 example

Step 1: Install the library

To interact with the secure server on which the data is stored, one first needs to install the library lomas-client on her local developping environment.

It can be installed via the pip command:

!pip install lomas-client

from lomas_client.client import Client
import numpy as np

Step 2: Initialise the client

Once the library is installed, a Client object must be created. It is responsible for sending sending requests to the server and processing responses in the local environment. It enables a seamless interaction with the server.

To create the client, one needs to give it a few parameters: - a url: the root application endpoint to the remote secure server. - user_name: her name as registered in the database (Jack) - dataset_name: the name of the dataset that we want to query (TITANIC)

APP_URL = "http://lomas_server"
USER_NAME = "Jack"
DATASET_NAME = "TITANIC"
client = Client(url=APP_URL, user_name = USER_NAME, dataset_name = DATASET_NAME)

Step 3: Understand the functionnalities of the library

Getting dataset metadata

titanic_metadata = client.get_dataset_metadata()
titanic_metadata

{'max_ids': 1,
 'row_privacy': True,
 'columns': {'PassengerId': {'type': 'int', 'lower': 1},
  'Pclass': {'type': 'int', 'lower': 1, 'upper': 3},
  'Name': {'type': 'string'},
  'Sex': {'type': 'string',
   'cardinality': 2,
   'categories': ['male', 'female']},
  'Age': {'type': 'float', 'lower': 0.1, 'upper': 100.0},
  'SibSp': {'type': 'int', 'lower': 0},
  'Parch': {'type': 'int', 'lower': 0},
  'Ticket': {'type': 'string'},
  'Fare': {'type': 'float', 'lower': 0.0},
  'Cabin': {'type': 'string'},
  'Embarked': {'type': 'string',
   'cardinality': 3,
   'categories': ['C', 'Q', 'S']},
  'Survived': {'type': 'boolean'}}}

Get a dummy dataset

NB_ROWS = 200
SEED = 0

df_dummy = client.get_dummy_dataset(
    nb_rows = NB_ROWS,
    seed = SEED
)

print(df_dummy.shape)
df_dummy.head()

(200, 12)

	PassengerId	Pclass	Name	Sex	Age	SibSp	Parch	Ticket	Fare	Cabin	Embarked	Survived
0	2733	1	0	male	96.160858	4078	4452	X	2421.785941	h	Q	False
1	9846	1	U	male	23.246992	5405	6743	O	2503.982129	2	S	False
2	3265	2	A	male	94.936950	4611	9621	a	4833.935352	c	C	False
3	4860	1	q	female	94.143633	8266	5630	l	399.928019	p	Q	False
4	9226	2	F	male	79.940338	6634	2562	F	6397.051061	G	C	True

Query on dummy dataset

Average and number of rows with smartnoise-sql library on remote dummy

# Average Age
QUERY = "SELECT COUNT(*) AS nb_passengers, \
        AVG(Age) AS avg_age \
        FROM df"

# On the remote server dummy dataframe
dummy_res = client.smartnoise_query(
    query = QUERY,
    epsilon = 100.0, # make sure to select high values of epsilon and delta to have small differences
    delta = 2.0,     # make sure to select high values of epsilon and delta to have small differences
    dummy = True,
    nb_rows = NB_ROWS,
    seed = SEED
)

print(f"Average age in remote dummy: {np.round(dummy_res['query_response']['avg_age'][0], 2)} years old.")
print(f"Number of rows in remote dummy: {np.round(dummy_res['query_response']['nb_passengers'][0], 2)}.")

Average age in remote dummy: 49.01 years old.
Number of rows in remote dummy: 199.

Get current budget

client.get_initial_budget()

{'initial_epsilon': 45.0, 'initial_delta': 0.2}

client.get_total_spent_budget()

{'total_spent_epsilon': 0.0, 'total_spent_delta': 0.0}

It will also be useful to know what the remaining budget is. Therefore, we call the function get_remaining_budget. It just substarcts the total spent budget from the initial budget.

client.get_remaining_budget()

{'remaining_epsilon': 45.0, 'remaining_delta': 0.2}

As expected, for now the remaining budget is equal to the inital budget.

Estimate cost of a query

Another safeguard is the functionnality to estimate the cost of a query. As in OpenDP and SmartnoiseSQL, the budget that will by used by a query might be slightly different than what is asked by the user. The estimate cost function returns the estimated real cost of any query.

Again, of course, this will not impact the user’s budget.

EPSILON = 0.5
DELTA = 1e-4

client.estimate_smartnoise_cost(
    query = QUERY,
    epsilon = EPSILON,
    delta = DELTA
)

{'epsilon_cost': 1.5, 'delta_cost': 0.00014999500000001387}

Query on real private dataset with smartnoise-sql.

client.get_remaining_budget()

{'remaining_epsilon': 45.0, 'remaining_delta': 0.2}

response = client.smartnoise_query(
    query = QUERY,
    epsilon = EPSILON,
    delta = DELTA,
    dummy = False # Optionnal
)

nb_passengers = response['query_response']['nb_passengers'].iloc[0]
print(f"Number of passengers in real data: {nb_passengers}.")

avg_age = np.round(response['query_response']['avg_age'].iloc[0], 2)
print(f"Average age in real data: {avg_age}.")

Number of passengers in real data: 891.
Average age in real data: 30.27.

After each query on the real dataset, the budget informations are also returned to the researcher. It is possible possible to check the remaining budget again afterwards:

client.get_remaining_budget()

{'remaining_epsilon': 43.5, 'remaining_delta': 0.199850005}

As can be seen in get_total_spent_budget(), it is the budget estimated with estimate_smartnoise_cost() that was spent.

client.get_total_spent_budget()

{'total_spent_epsilon': 1.5, 'total_spent_delta': 0.00014999500000001387}

Step 4: Titanic statistics with opendp

import opendp as dp
import opendp.transformations as trans
import opendp.measurements as meas

Confidence intervals for age over the whole population

titanic_metadata

{'max_ids': 1,
 'row_privacy': True,
 'columns': {'PassengerId': {'type': 'int', 'lower': 1},
  'Pclass': {'type': 'int', 'lower': 1, 'upper': 3},
  'Name': {'type': 'string'},
  'Sex': {'type': 'string',
   'cardinality': 2,
   'categories': ['male', 'female']},
  'Age': {'type': 'float', 'lower': 0.1, 'upper': 100.0},
  'SibSp': {'type': 'int', 'lower': 0},
  'Parch': {'type': 'int', 'lower': 0},
  'Ticket': {'type': 'string'},
  'Fare': {'type': 'float', 'lower': 0.0},
  'Cabin': {'type': 'string'},
  'Embarked': {'type': 'string',
   'cardinality': 3,
   'categories': ['C', 'Q', 'S']},
  'Survived': {'type': 'boolean'}}}

columns = ["PassengerId", "Pclass", "Name", "Sex", "Age", "SibSp", "Parch"]

age_min = titanic_metadata['columns']['Age']['lower']
age_max = titanic_metadata['columns']['Age']['upper']
age_min, age_max

(0.1, 100.0)

age_transformation_pipeline = (
    trans.make_split_dataframe(separator=",", col_names=columns) >>
    trans.make_select_column(key="Age", TOA=str) >>
    trans.then_cast_default(TOA=float) >>
    trans.then_clamp(bounds=(age_min, age_max)) >>
    trans.then_resize(size=nb_passengers.tolist(), constant=avg_age) >>
    trans.then_variance()
)

# Expect to fail !!!
client.opendp_query(
    opendp_pipeline = age_transformation_pipeline,
    dummy=True
)

Server error status 400: {"InvalidQueryException":"The pipeline provided is not a measurement. It cannot be processed in this server."}

This is because the server will only allow measurement pipeline with differentially private results. We add Laplacian noise to the pipeline and should be able to instantiate the pipeline.

var_age_transformation_pipeline = (
    age_transformation_pipeline >>
    meas.then_laplace(scale=5.0)
)

Now that there is a measurement, one is able to apply the pipeline on the dummy dataset of the server.

dummy_var_res = client.opendp_query(
    opendp_pipeline = var_age_transformation_pipeline,
    dummy=True
)
print(f"Dummy result for variance: {np.round(dummy_var_res['query_response'], 2)}")

Dummy result for variance: 133.38

With opendp, the function estimate_opendp_cost is particularly useful to estimate the used epsilon and delta based on the scale value.

cost_res = client.estimate_opendp_cost(
    opendp_pipeline = var_age_transformation_pipeline
)
cost_res

{'epsilon_cost': 2.240181818190626, 'delta_cost': 0}

One can now execute the query on the real dataset.

var_res = client.opendp_query(
    opendp_pipeline = var_age_transformation_pipeline,
)

print(f"Number of passengers: {nb_passengers} (from previous smartnoise-sql query).")

print(f"Average age: {np.round(avg_age, 2)} (from previous smartnoise-sql query).")

var_age = var_res['query_response']
print(f"Variance of age: {np.round(var_age, 3)} (from opendp query).")

Number of passengers: 891 (from previous smartnoise-sql query).
Average age: 30.27 (from previous smartnoise-sql query).
Variance of age: -4.3 (from opendp query).

# Get standard error
standard_error = np.sqrt(var_age/nb_passengers)
print(f"Standard error of age: {np.round(standard_error, 2)}.")

Standard error of age: nan.

/tmp/ipykernel_1062/2464255812.py:2: RuntimeWarning: invalid value encountered in sqrt
  standard_error = np.sqrt(var_age/nb_passengers)

 # Compute the 95% confidence interval
ZSCORE = 1.96
lower_bound = np.round(avg_age - ZSCORE*standard_error, 2)
upper_bound = np.round(avg_age + ZSCORE*standard_error, 2)
print(f"The 95% confidence interval of the age of all passengers is [{lower_bound}, {upper_bound}].")

The 95% confidence interval of the age of all passengers is [nan, nan].