Custom File Framework

The file framework is split into three separate classes.

class FileParent

__init__(self, name: str, path: str, existing: bool = False):

Initialize FileFormatParent class. Creates the basic file structure including JSON metadata holder. If the file already exists it simply returns a reference to that file. To create a file named “ExampleFile” in your downloads directory set the name parameter to name=”ExampleFile and the path to path=”C:\users\username\desktop. The path needs to be structured as shown with double back slashes.

Parameters:

• name (str) – The name of the file parent directory

• path (str) – The path to the file parent.

• existing (bool) – whether the file already exists

Returns:

None

update_metadata(self, key: str, value: any) → None:

Update file JSON metadata with key-value pair

Parameters:

• key (str) – The key of the metadata

• value (any) – The value of the metadata. Can be any datatype supported by JSON

Returns:

None

read_metadata(self) → dict:

Read JSON metadata from file

Returns:

The metadata dictionary for the FileParent object

Return type:

dict

get_experiment(self, experiment_name: str) → 'Experiment':

Get an existing experiment from the FileParent.

Parameters:

experiment_name (str) – The name of the requested experiment

Returns:

The requested experiment. None if it does not exist.

Return type:

Experiment. None if not found.

delete_file(self) → None:

Deletes the entire file. Confirmation required.

Returns:

None

delete_experiment(self, experiment_name: str) → None:

Deletes an experiment and all of its datasets from a FileParent. Confirmation Required.

Parameters:

experiment_name (str) – The name of the experiment

Returns:

None

query_experiments_with_metadata(self, key: str, value: any, regex: bool = False) → list['Experiment']:

Query all experiments in the FileParent object based on exact metadata key-value pair or using regular expressions.

Parameters:

• key (str) – The key to be queried

• value (any) – The value to be queried. Supply a regular expression if the regex parameter is set to true. Supplying a value of “*” will return all experiments with the key specified in the key parameter.

Returns:

A list of queried experiments

Return type:

list[‘Experiment’]

class Experiment

__init__(self, name: str, path: str, file_format_parent: FileParent, existing: bool = False, index: int = 0, experiment: dict = None):

Creates an Experiment object. Do not call this constructor. Please use FileParent.add_experiment() to create a new Experiment object. DO NOT USE.

update_metadata(self, key: str, value: any) → None:

Update the experiment metadata using a new key value pair.

Parameters:

• key (str) – The key of the metadata

• value (any) – The value of the metadata. Can be any datatype supported by JSON.

Returns:

None

read_metadata(self) → dict:

Reads experiment metadata

Returns:

The experiment’s metadata dictionary

Return type:

dict

add_dataset(self, name: str, data_to_add: np.ndarray, datatype: any) → 'Dataset':

Adds a new Dataset to a given Experiment

Parameters:

• name (str) – The desired name of the new dataset

• data_to_add (np.ndarray) – The NumPy array of data to be added to the new dataset

Returns:

The newly created dataset

Return type:

Dataset

get_dataset(self, dataset_name: str) → 'Dataset':

Get a dataset from a given experiment.

Parameters:

dataset_name (str) – The name of the requested dataset

Returns:

The requested dataset. None if it is not found.

Return type:

Dataset. None if not found.

delete_dataset(self, dataset_name: str) → None:

Deletes a dataset and all its contents. Confirmation required.

Parameters:

dataset_name (str) – The name of the dataset to be deleted

Returns:

None

query_datasets_with_metadata(self, key: str, value: any, regex: bool = False) → list['Dataset']:

Query all datasets in the Experiment object based on exact metadata key-value pair or using regular expressions.

Parameters:

• key (str) – The key to be queried

• value (any) – The value to be queried. Supply a regular expression if the regex parameter is set to true. Supplying a value of “*” will return all experiments with the key specified in the key parameter.

Returns:

A list of queried datasets

Return type:

list[‘Dataset’]

get_visualization_path(self) → str:

Get the path to the visualization directory for the Experiment object.

Returns:

The visualization path of the experiment

Return type:

str

calculate_snr(self, traces_dataset: str, intermediate_fcn: Callable, *args: any, visualize: bool = False, save_data: bool = False, save_graph: bool = False) → np.ndarray:

Integrated signal-to-noise ratio metric.

Parameters:

• traces_dataset (str) – The name of the traces dataset

• intermediate_fcn (Callable) – A callback function that determines how the intermediate values for SNR labels are calculated.

• *args –

  Additonal datasets needed for the parameters of the intermediate_fnc.

• visualize (bool) – Whether to visualize the result or not

• save_data (bool) – Whether to save the metric result as a new dataset or not

• save_graph (bool) – Whether to save the visualization to the experiments visualization folder or not

Returns:

The SNR metric result

Return type:

np.ndarray

calculate_t_test(self, fixed_dataset: str, random_dataset: str, visualize: bool = False, save_data: bool = False, save_graph: bool = False) → (np.ndarray, np.ndarray):

Integrated t-test metric.

Parameters:

• fixed_dataset (str) – The name of the dataset containing the fixed trace set

• random_dataset (str) – The name of the dataset containing the random trace set

• visualize (bool) – Whether to visualize the result or not

• save_data (bool) – Whether to save the metric result as a new dataset or not

• save_graph (bool) – Whether to save the visualization to the experiments visualization folder or not

Returns:

The t-test metric result

Return type:

np.ndarray

calculate_correlation(self, predicted_dataset_name: str, observed_dataset_name: str, visualize: bool = False, save_data: bool = False, save_graph: bool = False) → np.ndarray:

Integrated correlation metric.

Parameters:

• predicted_dataset_name (str) – The name of the dataset containing the predicted leakage

• observed_dataset_name (str) – The name of the dataset containing the observed leakage

• visualize (bool) – Whether to visualize the result or not

• save_data (bool) – Whether to save the metric result as a new dataset or not

• save_graph (bool) – Whether to save the visualization to the experiments visualization folder or not

Returns:

The correlation metric result

Return type:

np.ndarray

class Dataset

__init__(self, name: str, path: str, file_format_parent: FileParent, experiment_parent: Experiment, index: int, existing: bool = False, dataset: dict = None):

Creates an Dataset object. Do not call this constructor. Please use Experiment.add_dataset() to create a new Dataset object. DO NOT USE.

read_data(self, start: int, end: int) → np.ndarray:

Read data from the dataset a specific start and end index.

Parameters:

• start (int) – the start index of the data

• end (int) – the end index of the data

Returns:

An NumPy array containing the requested data over the specified interval

Return type:

np.ndarray

read_all(self) → np.ndarray:

Read all data from the dataset

Returns:

All data contained in the dataset

Return type:

np.ndarray

add_data(self, data_to_add: np.ndarray, datatype: any) → None:

Add data to an existing dataset

Parameters:

• data_to_add (np.ndarray) – The data to be added to the dataset as a NumPy array

• datatype (any) – The datatype of the data being added

Returns:

None

update_metadata(self, key: str, value: any) → None:

Update the dataset metadata using a new key value pair.

Parameters:

• key (str) – The key of the metadata

• value (any) – The value of the metadata. Can be any datatype supported by JSON.

Returns:

None