slacgs Package

Model

class slacgs.model.Model(params, max_n=8192, N=(2, 4, 8, 16, 32, 64, 128, 256, 512, 1024), dictionary=('LINEAR',))

Represents a Model for this Simulator for Loss Analysis of a Classifier.

This Model for SLACGS contains:

\(d\): dimensionality of the Model
\(\mathbf{\sigma} = \bigcup_{i=1}^{d} \sigma_i\) : list of standard deviations for each feature
\(\mathbf{\rho} = \bigcup_{i=1}^{d} \bigcup_{j=i+1}^{d} \rho_{ij}\): list of correlations between each pair of features
\(\mathbf{N} = \bigcup_{i=1}^{k} 2^i\), where \(k\) is the length of \(\mathbf{N}\) : list of cardinalities of the model
\(H\): dictionary of classifiers

Parameters:

params (list of numbers) – list containing the standard deviation vector \(\mathbf{\sigma}\) and the correlation vector \(\mathbf{\rho}\), formally \(\mathbf{\sigma} \cup \mathbf{\rho}\)
max_n (int) – upper bound cardinality for the set \(\mathbf{N}\)

Raises:

ValueError – if length of params is less than 3; if the length of params is not equal to the sum of the natural numbers from 1 to dim (dim = 2,3,4,…); if max_n is not a power of 2; if N is not a list of powers of 2; if dictionary is not a list of strings and is equal to [‘linear’]; if self.cov is not a positive definite matrix; if self.cov is not a symmetric matrix; if Sigma’s are not positive numbers; if Rho’s are not numbers between -1 and 1 if dictionary is not a valid list of strings (see enumtypes.py for valid strings); if abs(rho_13) is not smaller than sqrt((1 + rho_12) / 2)
TypeError – if params is not a list of numbers (floats or ints) or tuple of numbers (floats or ints); if max_n is not an int; if N is not a list of ints; if dictionary is not a list of strings (see enumtypes.py for valid strings);

Example

>>> model = Model([1, 1, 2, 0, 0, 0])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 1, 2, 0.5, 0, 0])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 1, 2, 0, 0.3, 0.3])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 1, 2, -0.2, -0.5, -0.5])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 1, 1, -0.1, 0.5, 0.5], max_n=2**15, N=[2**i for i in range(1,14)])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 2, 4, 0, 0.5, 0.5], max_n=2**10, N=[2**i for i in range(1,11)])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 1, 1, 2, 0.1, 0, 0, 0, 0, 0])
>>> model.save_data_points_plot_as_png()

>>> model = Model([1, 2, -0.1])
>>> model.save_data_points_plot_as_png()

plot_surrounding_ellipsis_and_ellipsoids() → Figure

Plots the ellipsoids for this model’s covariance matrix \(\Sigma\) and a dataset sample with \(n=1024\) sample points for \(d \in [2,3]\).

Parameters:: self (Model) – The model object.
Returns:: The matplotlib Figure object.
Return type:: Figure
Raises:: ValueError – if cov is not a 3x3 matrix; if cov is not a positive definite matrix; if cov is not a symmetric matrix;

Warning

This method is available only for 3D models.

Example

>>> from slacgs.model import Model
>>> model = Model((1, 1, 2, 0.5, 0, 0))
>>> plot_fig = model.data_points_plot

save_data_points_plot_as_png(export_path=None, verbose=True)

Save a matplotlib Figure object as a PNG image.

Parameters:

export_path (str) – The file path where the PNG image will be saved.
verbose (bool) – If True, print the export path.

Returns:

None

Warning

this method is available only for 3D models.

upload_data_points_plot_to_google_drive(gdc, verbose=True)

Upload a matplotlib Figure object as a PNG image to Google Drive.

Parameters:

gdc (GoogleDriveClient) – The Google Drive client object.
verbose (bool) – If True, print the export path.

Returns:

None

Warning

this method is available only for 3D models.

Simulator

class slacgs.simulator.Simulator(model: Model, dims=None, dims_to_compare=None, loss_types=('EMPIRICAL_TRAIN', 'THEORETICAL', 'EMPIRICAL_TEST'), test_samples_amt=1024, step_size=5, max_steps=200, min_steps=100, precision=1e-06, augmentation_until_n=1024, verbose=True)

Represents a Simulator for a Classifier Loss Analysis on Gaussian samples in order to evaluate Trade Off Between Samples and Features in Classification Problems on multivariate Gaussian Generated Samples.

This Simulator for a SLACGS’ Model Contains:

\(m\): a Model object for SLACGS
\(\mathbf{d}\): an array of dimensionalities \(d_i\) to be simulated
\(\mathbf{d_{comp}}\): a pair of dimensionalities \((d_a, d_b)\) to be compared
\(\mathbf{L_{types}}\): a list of Loss functions \(L\) to be estimated for each dimensionality \(d\)
\(n_{test}\): the number of test samples \(x_{test}\) to be generated for dataset \(D_{test}\)

Also contins args for the simulation:

\(n_{aug}\): upper bound cardinality to apply data augmentation> Defined as \(arg_{augmentation\_until\_n}\)
\(cte_{aug}(n)\): augmenttation factor to multiply the number of datasets generated for a cardinality of \(n\) samples. It is defined as \(\frac{\sqrt{n_{aug}}}{\sqrt{n}}\), if \(n < n_{aug}\), else it equals \(1\)
\(r_{step}(n)\): number of rounds (iterations) per simulation step for a cardinality of \(n\) samples. Defined as \(arg_{step\_size}*cte_{aug}(n)\)
\(max_{steps}(n)\): maximum number of simulation steps for a cardinality of \(n\) samples. Defined as \(arg_{max\_steps}*cte_{aug}(n)\)
\(min_{steps}(n)\): minimum number of simulation steps for a cardinality of \(n\) samples. Defined as \(arg_{min\_steps}*cte_{aug}(n)\)
\(\epsilon\): precision for the simulation stop criteria. Defined as \(arg_{precision}\)

Loss convergence stop criterias:

\(\Delta L_{train}(n,d) < \epsilon\): difference between \(E[L_{train}]\) calculated on two consecutive steps must be less than \(\epsilon\) for a cardinality of \(n\) samples and a dimensionality of \(d\) features
\(\Delta L_{test}(n,d) < \epsilon\): difference between \(E[L_{test}]\) calculated on two consecutive steps must be less than \(\epsilon\) for a cardinality of \(n\) samples and a dimensionality of \(d\) features
\(\Delta L_{theoretical}(n,d) < \epsilon\): difference between \(E[L_{theoretical}]\) calculated on two consecutive steps must be less than \(\epsilon\) for a cardinality of \(n\) samples and a dimensionality of \(d\) features

After simulation for each cardinality n in N is finished, some tests are performed to check if simulation should be continued for one more cardinality \(n = max(N)*2\):

test if intersection point between \(L_d(n)\) and \(L_{d-1}(n)\) has been found and continue simulation if not
test if Loss Functions are not yet converged and continue simulation if not, \(\forall d \in \mathbf{d},\ L_{d}(n) - L_{d}(n-1) < 10^{-3}\)

Parameters:

model (Model) – \(m\): Linear Classifier Loss Analysis Model
dims (list) – \(\mathbf{d}\): dimensionalities to be simulated
dims_to_compare (list) – \(\mathbf{d_{comp}}\): a pair of dimensionalities \((d_a, d_b)\) to be compared
loss_types (list) – \(\mathbf{L_{types}}\): a list of Loss functions \(L\) to be estimated for each dimensionality \(d\)
test_samples_amt (int) – \(n_{test}\): the number of test samples \(x_{test}\) to be generated for dataset \(D_{test}\)
step_size (int) – \(arg_{step\_size}\) number of datasets generated in one simulation step equals \(r_{step}(n)\), if \(n < n_{aug}\), else it equals \(arg_{step\_size}\)
max_steps (int) – \(arg_{max\_steps}\) max number of steps per \(n \in N\)
min_steps (int) – \(arg_{min\_steps}\) min number of steps per \(n \in N\)
precision (float) – \(\epsilon\) stop criteria. For each cardinality \(n\) The Loss estimation for each dimensionality \(d\) and Loss function \(L_{type}\) must be converged when \(\Delta L_{type}(n,d) < \epsilon\)
augmentation_until_n (int) – \(n_{aug}\): upper bound cardinality to apply data augmentation> Defined as \(arg_{augmentation\_until\_n}\)

Raises:

TypeError – if model is not a Model object; if dims is not a list or tuple of integers; if loss_types is not a list or tuple of strings; if test_samples_amt is not an integer; if iters_per_step is not an integer; if max_steps is not an integer; if min_steps is not an integer; if precision is not a float; if augmentation_until_n is not an integer; if verbose is not a boolean;
ValueError – if max_steps < min_steps; if precision < 0 or if precision > 1; if augmentation_until_n < 1024; if test_samples_amt < 2; if iters_per_step < 1; if max_steps < 10; if min_steps < 1 if loss_types is not a valid list or tuple of strings (see enumtypes.py for valid strings) or if loss_types is empty; if dims is not a valid list or tuple of integers or if dims is empty;

Examples

>>> from slacgs import Model

>>> param = [1,1,2,0,0,0]
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)
>>> slacgs = Simulator(model, step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)
>>> slacgs.run() 

>>> param = [1,1,2,-0.1,0,0]
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)
>>> slacgs = Simulator(model, step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)
>>> slacgs.run() 

>>> param = [1,1,2,0,-0.4,-0.4]
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)
>>> slacgs = Simulator(model, step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)
>>> slacgs.run() 

>>> param = [1,1,2,-0.1,-0.4,-0.4]
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)
>>> slacgs = Simulator(model, step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)
>>> slacgs.run() 

>>> param = [1,2,-0.1]
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)
>>> slacgs = Simulator(model, dims=(1,2), step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)
>>> slacgs.run() 

>>> param = [1,1,1,2,0,0,0,0,0,0]
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)
>>> slacgs = Simulator(model, dims=(3,4), step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)
>>> slacgs.run() 

generate_dataset(n, i)

This method generates all simulation required datasets for all dimensionalities \(d\) set to be simulated, given:

covariance matrix \(\Sigma_{d \times d}\) contained in the simulator object
class means \(\mathbf{\mu_{(+)}}\) and \(\mathbf{\mu_{(+)}}\) contained in the simulator object
random seed \(i\)
cardinality \(n\)

Required Simulation Datasets:

\(D = D_{train} \cup D_{test}\) : dataset
\(D_{train} = D_{(+)train} \cup D_{(-)train}\) : training set
\(D_{test} = D_{(+)test} \cup D_{(-)test}\) : test set
\(D_{(+)train} = (\mathbf{X}_{(+)train}, \mathbf{y}_{(+)train})\) : training set for class \((+)\)
\(D_{(-)train} = (\mathbf{X}_{(-)train}, \mathbf{y}_{(-)train})\) : training set for class \((-)\)
\(D_{(+)test} = (\mathbf{X}_{(+)test}, \mathbf{y}_{(+)test})\) : test set for class \((+)\)
\(D_{(-)test} = (\mathbf{X}_{(-)test}, \mathbf{y}_{(-)test})\) : test set for class \((-)\)

Gaussian Distribution Parameters:

\(\mathbf{\Sigma_{d \times d}}\) : covariance matrix \(d \times d\) for training and test sets for both classes
\(n\) : cardinality for training and test sets for both classes
\(\mathbf{\mu_{(+)}}\) : mean vector for class \((+)\)
\(\mathbf{\mu_{(-)}}\) : mean vector for class \((-)\)
\(\mathbf{\mu_{(+)}} = \bigcup_{i=1}^{d} \mu_{(+)i}\)
\(\mathbf{\mu_{(+)}} = \bigcup_{i=1}^{d} \mu_{(-)i}\)
\(\mu_{(+)i} = 1\) and \(\mu_{(-)i} = -1\), for \(i \in [1,...,d]\)
\(\mathbf{\mu_{(-)}} = [\mu_{(-)i}]\) for \(i \in [1,...,d] = [\mu_{-1}, ..., \mu_{-d}] = [1,...,1]_{1 \times d}\)
\(\mathbf{\mu_{(+)}} = [\mu_{(+)i}]\) for \(i \in [1,...,d] = [\mu_{+1}, ..., \mu_{+d}] = [-1,...,-1]_{1 \times d}\)

Parameters:

self (Simulator) – self object of the class Simulator
n (int) – cardinality \(n\) for training and testing sets for both classes
i (int) – random seed \(i\)

Returns:

A dictionary containing all required simulation datasets for all dimensionalities \(d\) set to be simulated, represented by \(D_{(+)train}\), \(D_{(-)train}\), \(D_{(+)test}\), \(D_{(-)test}\).

Return type:

dict

loss_bayes_empirical(d)

This function estimates numerically the bayes error rate for a classifier \(h\) in dictionary \(H\).

When cardinality \(n\) is large enough, a loss function \(L(h)\) converges to the bayes error rate for a given dimensionality \(d\).
We can estimate the Bayes Error Rate by averaging loss \(L(h)\) values for sufficiently large \(n\).
The best choice is to opt for averaging \(\hat{L}(\hat{h}^{(D)})\) and \(\hat{L}(\hat{h}^{(D)},D')\) for a Dataset \(D\) with sufficiently large cardinality \(n\).

Let \(\hat{h}^{(D)}\) be the best empirical classifier in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples, i.e., the classifier \(h\) in \(H\) with the minimum empirical error rate. Under these conditions, we can define three error rates:

\(L(\hat{h}^{(D)}) =\) the theoretical error rate of the classifier \(\hat{h}^{(D)}\)
\(\hat{L}(\hat{h}^{(D)}) =\) the empirical error rate of the classifier \(\hat{h}^{(D)}\)
\(\hat{L}(\hat{h}^{(D)},D') =\) the empirical error rate of the classifier \(\hat{h}^{(D)}\) using a test dataset \(D'\)

The Bayes Error (also: Bayes Risk) is defined as the minimum theoretical achievable error rate:

\(\min_{h\in H} L(h) =\) the smallest theoretically achievable error rate for a classifier \(h\) in dictionary \(H\).

Parameters:

self (Simulator) – self object of the class Simulator
d (int) – dimensionality \(d\) for which the bayes error rate is estimated

Returns:

An estimation for the smallest theoretically achievable error rate for a classifier \(h\) in dictionary \(H\) for the given covariance matrix \(\Sigma_{d \times d}\), also called Bayes Error Rate (or Bayes Risk), represented by \(\min_{h\in H} L(h)\).

Return type:

float

print_N_progress(n: int, max_iter: int, iter_per_step: int, datapoints_fig: Figure, datapoints_plot_png_path)

Prints the progress of the simulation for a given n ∈ N and a given number of iterations per step (step_size). The progress is printed in the terminal and a plot of the ellipsoids for this model’s covariance matrix and a dataset sample with n=1024 sample points is shown.

Parameters:

n – cardinality of the dataset
max_iter – max number of iterations per n ∈ N
iter_per_step – number of datasets generated in one simulation step equals step_size*sqrt(augmentation_until_n)/sqrt(n), if n < augmentation_until_n, else it equals step_size
datapoints_fig – a plot of the ellipsoids for this model’s covariance matrix and a dataset sample with n=1024 sample points

print_step_report(i, iter_per_step, loss_sum, iter_N)

Parameters:

self (Simulator) – self object of the class Simulator
i – current iteration
iter_per_step – iterations per step
loss_sum – loss sum
iter_N – iterations per n

run()

run the simulation

Parameters:: self (Simulator) – simulation object
Returns:: simulation report object
Return type:: Report

slacgs.simulator.cls(): Clears the terminal screen.

slacgs.simulator.dist_from_origin_to_intersect_btwn_norm_ellip_and_main_diag(cov)

This function calculates the distance from origin \([0,0,...,0]_{1 \times d}\) to the intersection point between the normalized ellipsoid and the main diagonal \([1,1,...,1]_{1 \times d}\), given:

the covariance matrix \(\Sigma_{d \times d}\) of the ellipsoid

A Model to Understand the Behavior of Bayes’ Risk in Two Dimensions

Suppose that only \(X1\) and \(X2\) are present. Let’s consider an ellipse in \(\mathbb{R}^2\) (say, centered at the origin \((0,0)\)) whose equation is

\[x^T \Sigma^{-1} x = 1.\]

For each class, we have an ellipse, and for each ellipse, we have a centroid. The line that joins the two centroids \((1,1)\) and \((-1,-1)\) is the set of all vectors in \(\mathbb{R}^2\) of the type

\[(c,c),\]

whose two coordinates are equal. This line cuts the mentioned ellipse at some point that has two equal and positive coordinates,

\[\begin{split}(c_2,c_2) \cdot \Sigma^{-1} \left(\begin{array}{c} c_2 \\ c_2 \end{array}\right) = 1.\end{split}\]

Let \(d_2\) be the distance from this point to the origin,

\[d_2 = \sqrt{2} c_2.\]

The greater this distance, the lower the discriminative power of the classifier, with \(X_1\) and \(X_2\) present.

For the general case, we have

\[d_{dim} = \sqrt{dim} c_{dim}.,\ dim = 1,2,3,...\]

Comparing Scenarios with Two and Three Attributes

How to use \(d_3\) and \(d_2\) to create, from the matrix \(\Sigma\), an indicator of the additional discrimination potential of \(X_3\) given that \(X_1\) and \(X_2\) are already present? The indicator we are proposing is \(d_2/d_3\),

\[U_3(\mathbf{\mu}_1, \mathbf{\mu}_2, \mathbf{\Sigma}) = \frac{d_2}{d_3} = \sqrt{\frac{2}{3}} \frac{c_2}{c_3},\]

where \(U_3\) is a utility metric of attribute 3.

Let \(R_2\) be the Bayes risk with 2 attributes, and \(R_3\) the corresponding risk with 3 attributes. Empirically, we verify that the ratio between the risks is an increasing and smooth function of the above utility function, that is,

\[\frac{R_2}{R_3} = \varphi(U_3),\]

where the function \(\varphi(\cdot)\) is an increasing and smooth function.

param cov:: covariance matrix \(\Sigma_{d \times d}\) of the ellipsoid
type cov:: list
returns:: distance from origin \([0,...,0]_{1 \times d}\) to the intersection point between the normalized ellipsoid and the main diagonal \([1,...,1]_{1 \times d}\).
rtype:: float

slacgs.simulator.h_error_rate(h_bias, h_weights, cov)

This function calculates the probability of error for a linear classifier \(h\) trained by Dataset \(D\) generated by a Gaussian distribution, given:

weights vector \(\mathbf{w}\) of the classifier \(h\);
the bias \(b\) of the classifier \(h\);
the covariance matrix \(\Sigma_{d \times d}\) used to generate the trainning dataset \(D\).

Linear Classifier?

“\(h(\mathbf{x}) = \mathbf{w} \cdot \mathbf{x} + b\)” is a linear classifier.
The hyperplane \(h\) defined by this equation represents the decision boundary that separates classes in a linearly separable space.
The hypothesis space \(H\) consists of all possible linear classifiers.

The linear classifier function \(h(\mathbf{x})\) returns a scalar value that represents a linear combination of the input data point \(\mathbf{x}\) and the weight vector \(\mathbf{w}\), plus a bias term \(b\). In the context of binary classification (wich is the case in this experiment), this value can be interpreted as the raw score or decision boundary for classifying an input. If you apply a threshold, such as 0, you can make a binary decision:

If \(h(\mathbf{x}) \geq 0\), then classify the input as one class (e.g., class 1).
If \(h(\mathbf{x}) < 0\), then classify the input as the other class (e.g., class 0).

The minimum probability of error for a linear classifier \(h\) trained by Dataset \(D\) generated by a Gaussian distribution is given by:

\(P(Error) = \frac{1}{2} (1 - \Phi({Distance}(+))) + \frac{1}{2}(1 - \Phi(Distance(-)))\)
\(P(Error) = \frac{1}{2} (1 - \Phi( \frac{|1 + b - (w_0 + ... + w_{d-1})|}{\sqrt{\Delta}})) + \frac{1}{2}(1 - \Phi(\frac{|1 - b - (w_0 + ... + w_{d-1})|}{\sqrt{\Delta}}))\)

Where:

\(d\) is the dimensionality of the classifier \(h\)
\(\mathbf{w}\) is the weights vector of the classifier \(h\)
\(\mathbf{w} = [w_0, ..., w_{d-1}]\)
\(b\) is the bias of the classifier \(h\)
\(\lambda\) is the Lower-triangular Cholesky factor of \(\Sigma_{d \times d}\)
\(\mathbf{\delta} = [\delta_i]\) for \(i \in [1,...,d] = [\delta_0,...,\delta_{d}]\)
\(\mathbf{\delta} = (\mathbf{w}|[-1]) \cdot \lambda^T = [w_0, ..., w_{d-1},-1]\cdot \lambda^T\)
\(\Delta = \sum_{\delta_i \in \mathbf{\delta}} \delta_i^2 = \delta_0^2 + ... + \delta_{d}^2\)
\(\Phi(\cdot)\) is the cumulative distribution function of a Gaussian with zero mean and variance one.
\(Distance(+)\) and \(Distance(-)\) are the distances from the hyperplane \(h\) to the mean of the positive and negative classes, \(\mathbf{\mu_{(+)}}\) and \(\mathbf{\mu_{(-)}}\), respectively.
\(\mathbf{\mu_{(+)}}\) : mean vector for class \((+)\)
\(\mathbf{\mu_{(-)}}\) : mean vector for class \((-)\)
\(\mathbf{\mu_{(+)}} = \bigcup_{i=1}^{d} \mu_{(+)i}\)
\(\mathbf{\mu_{(-)}} = \bigcup_{i=1}^{d} \mu_{(-)i}\)
\(\mu_{(+)i} = 1\) and \(\mu_{(-)i} = -1\), for \(i \in [1,...,d]\)
\(\mathbf{\mu_{(-)}} = [\mu_{(-)i}]_{1 \times d}\) for \(i \in [1,...,d]_{1 \times d} = [\mu_{-1}, ..., \mu_{-d}] = [1,...,1]_{1 \times d}\)
\(\mathbf{\mu_{(+)}} = [\mu_{(+)i}]_{1 \times d}\) for \(i \in [1,...,d]_{1 \times d} = [\mu_{+1}, ..., \mu_{+d}] = [-1,...,-1]_{1 \times d}\)

Parameters:

h_bias (float) – bias of the classifier \(h(\mathbf{x})\)
h_weights (list) – weights of the classifier \(h(\mathbf{x})\)
cov (list[list]) – covariance matrix of the gaussian samples used to train the model

Returns:

probability of error for the classifier \(h(\mathbf{x})\) trained with the gaussian samples generated with the covariance matrix \(\Sigma_{d \times d}\) and means \(\mu_{(+)}=[1,...,1]\) and \(\mu_=[-1,...,-1]\)

Return type:

float

slacgs.simulator.linear_svm_train(dim, training_set)

This function trains a linear SVM model and find the best empirical linear classifier \(\hat{h}^{(D)}\) in the hypothesis space \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples, given:

Training set \(D = D_{(+)train} \cup D_{(-)train}\)
dimensionality \(d\), \(d\) < nuber of features in the dataset

Linear Classifier?

“\(h(\mathbf{x}) = \mathbf{w} \cdot \mathbf{x} + b\)” is a linear classifier.
The hyperplane \(h\) defined by this equation represents the decision boundary that separates classes in a linearly separable space.
The hypothesis space \(H\) consists of all possible linear classifiers.

Parameters:

self (Simulator) – this simulator
dim (int) – dimensionality of the model, \(d\) features
training_set (dict) – dataset \(D\) to train the model

Returns:

trained SVM model containing the best empirical hyperplane \(h\) in the hypothesis space \(H\) for the given dataset \(D\) with \(d\) features and \(n\) samples

Return type:

sklearn.svm._classes.SVC

slacgs.simulator.loss_bayes_analytical(cov)

calculate the theoretical Bayes Error Rate (or Bayes Risk) analytically, given:

covariance matrix \(\Sigma_{d \times d}\) of a Gaussian distribution

The Bayes Error (also: Bayes Risk) is defined as the minimum theoretical achievable error rate:

\(\min_{h\in H} L(h) =\) the smallest theoretically achievable error rate for a classifier \(h\) in dictionary \(H\).

Warning

This function is only valid for 1D, 2D and 3D gaussian models.

Parameters:: cov (list[list] or np.ndarray) – covariance matrix \(\Sigma_{d \times d}\)
Returns:: The smallest theoretically achievable error rate for a classifier \(h\) in dictionary \(H\) for the given covariance matrix \(\Sigma_{d \times d}\), also called Bayes Error Rate (or Bayes Risk), represented by \(\min_{h\in H} L(h)\).
Return type:: float

slacgs.simulator.loss_empirical(clf, dataset_test)

this function calculates an empirical loss \(\hat{L}(h)\), given:

SVM trained model containing the best empirical classifier \(\hat{h}^{(D)}\) in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples.
a test set \(D_{test} = D_{(+)test} \cup D_{(-)test}\)

For each classifier \(h\) in \(H\), we can calculate its empirical error rate \(\hat{L}(h)\), i.e., its proportion of misclassified observations in the dataset \(D\):

\(\hat{L}(h) = \frac{1}{n} \sum_{i=1}^{n} 1(y_i \neq h(x_i))\)

Let \(\hat{h}^{(D)}\) be the best empirical classifier in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples, i.e., the classifier in \(H\) with the minimum empirical error rate. Under these conditions, we can define two error rates:

\(\hat{L}(\hat{h}^{(D)}) =\) the empirical error rate of the classifier \(\hat{h}^{(D)}\), when \(D_{test} = D_{train}\)
\(\hat{L}(\hat{h}^{(D)},D') =\) the empirical error rate of the classifier \(\hat{h}^{(D)}\) using a test dataset \(D'\), when \(D_{test} \neq D_{train}\)

Parameters:

clf (sklearn.svm.SVC) – SVM trained model containing the best empirical classifier \(\hat{h}^{(D)}\) in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples.
dataset_test (dict) – a test set \(D_{test} = D_{(+)test} \cup D_{(-)test}\)

Returns:

empirical error rate of the classifier \(\hat{h}^{(D)}\), \(\hat{L}(\hat{h}^{(D)})\) when \(D_{test} = D_{train}\) or \(\hat{L}(\hat{h}^{(D)},D')\) when \(D_{test} \neq D_{train}\)

Return type:

float

slacgs.simulator.loss_theoretical(h_clf, cov)

Using probability theory, calculates the theoretical loss for given:

sklearn SVM trained model containing the best linear classifier \(h\) in the hypothesis space \(H\) for the given training dataset \(D\) with \(d\) features and \(n\) samples
covariance matrix \(\Sigma\) of the dataset \(D\)

Linear Classifier?

“\(h(\mathbf{x}) = \mathbf{w} \cdot \mathbf{x} + b\)” is a linear classifier.
The hyperplane \(h\) defined by this equation represents the decision boundary that separates classes in a linearly separable space.
The hypothesis space \(H\) consists of all possible linear classifiers.

Let \(\hat{h}^{(D)}\) be the best empirical classifier in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples, i.e., the classifier in \(H\) with the minimum empirical error rate. Under these conditions, we can define theoretical error rate as:

\(L(\hat{h}^{(D)}) =\) the theoretical error rate of the classifier \(\hat{h}^{(D)}\)

Parameters:

h_clf (sklearn.svm._classes.SVC) – SVM trained classifier containing the best empirical classifier \(\hat{h}^{(D)}\) in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples
cov (list[list] or np.ndarray) – covariance matrix \(\Sigma_{d \times d}\) of the gaussian samples used to train the SVM model

Returns:

theoretical loss for classifier \(\hat{h}^{(D)}\)

Return type:

float

Raises:

TypeError – if h_clf is not a sklearn.svm._classes.SVC if cov is not a list of lists or np.ndarray
ValueError – if h_clf is not a linear classifier if h_clf is not a trained scikit-learn SVM model if cov is not a positive definite matrix

Report

class slacgs.report.Report(sim)

Report of the executed simulations

Parameters:: sim (Simulator) – Simulator object

sim

Simulator object

Type:: Simulator

iter_N

Number of iterations for each dimension and loss type

Type:: dict

max_iter_N

Maximum number of iterations for each dimension

Type:: list

loss_N

Loss for each dimension and loss type

Type:: dict

loss_bayes

Bayes loss for each dimension

Type:: dict

d

distance from origin to the intersection point between the normalized ellipsoid and the main diagonal for each dimension

Type:: dict

duration

Duration of the simulation

Type:: float

time_spent

Time spent for each dimension and loss type

Type:: dict

sim_tag

Simulator object attributes

Type:: dict

model_tag

Model object attributes

Type:: dict

loss_plot

Loss plot

Type:: matplotlib.figure.Figure

Raises:: TypeError – If sim is not a Simulator object

compile_N(dims=(2, 3))

return N* images for report compilation. N* is a threshold beyond which the presence of a new feature X_d becomes advantageous, if the other features [X_0…X_d-1] are already present.

Self:: report object
Parameters:: dims (tuple of int or list of int) – a pair of dimensionalyties to be compared
Returns:: N* images for report compilation
Return type:: dict

compile_compare(dims=None)

return compare_report images for pair of compared dimensionalyties

Parameters:: dims (tuple of int or list of int) – a pair of dimensionalyties to be compared
Returns:: compare_report images for pair of compared dimensionalyties
Return type:: tuple[dict, dict, dict[int | str, str], dict[int | str, Any], dict, dict[str, Any], dict[str, Any]]

compile_delta_L_()

return \(∆L\) estimations

Stochastic error:

\(∆L_1 = L(\hat{h}(D)) − min_{h∈H} L(h)\)

Estimation error of \(L(\hat{h}(D))\):

\(∆L_2 = |L(\hat{h}(D)) − \hat{L}(\hat{h}(D))|\)

Parameters:: self (Report) – report object
Returns:: delta_L_ = (delta_L1, delta_L2)
Return type:: tuple of dicts

intersection_point_(dims, loss_type)

return intersection points between Loss curves of a pair of compared dimensionalyties

Parameters:

self (Report) – report object
dims (tuple of int or list of int) – a pair of dimensionalyties to be compared

Param:

loss estimation method

Returns:

intersection points between Loss curves of a pair of compared dimensionalyties

Return type:

list of lists

plot_with_intersection()

plot Loss curves of a pair of compared dimensionalyties with intersection points between them

Returns:: The figure object.
Return type:: matplotlib.figure.Figure

print_N_star(dims_to_compare=None)

Print N_star for theoretical and empirical loss

Parameters:

dims_to_compare (list of int or tuple of int) – list of dimensionalities to be compared

Returns:

None

Raises:

TypeError – if dims_to_compare is not a list of int or tuple of int;
ValueError – if the number of compared dimensionalities is not 2; if the list of dioemnsionalities to be compared is not a subset of the list of simulated dimensionalities

print_report(dims_to_compare=None)

Print report

Parameters:

dims_to_compare (list of int or tuple of int) – list of dimensionalities to be compared

Returns:

None

Raises:

TypeError – if dims_to_compare is not a list of int or tuple of int;
ValueError – if the number of compared dimensionalities is not 2; if the list of dioemnsionalities to be compared is not a subset of the list of simulated dimensionalities

save_loss_plot_as_png(export_path=None, verbose=True)

Save a matplotlib Figure object as a PNG image.

Parameters:

export_path (str) – The file path where the PNG image will be saved.
verbose (bool) – If True, print the export path.

Returns:

None

upload_loss_plot_to_drive(gdc, verbose=True)

Upload a matplotlib Figure object as a PNG image to Google Drive.

Parameters:

gdc (GoogleDriveClient) – The GoogleDriveClient object.
verbose (bool) – If True, print the export path.

Returns:

None

write_to_spreadsheet(gc, dims_to_compare=None, verbose=True)

Write results to a Google Spreadsheet

Parameters:

self (Report) – object of class Report
gc (GspreadClient) – gspread client object
dims_to_compare (list of int or tuple of int) – list of dimensionalities to be compared
verbose (bool) – print output

Returns:

None

Return type:

None

Raises:

TypeError – if dims_to_compare is not a list of int or tuple of int;
ValueError – if the number of compared dimensionalities is not 2; if the list of dioemnsionalities to be compared is not a subset of the list of simulated dimensionalities

Example:

>>> import os
>>> from slacgs import Model
>>> from slacgs import Simulator
>>> from slacgs import GspreadClient
>>> from slacgs import doctest_next_parameter

>>> ## run simulation for parameter
>>> ### choose your own parameter
>>> ### param = [1, 1, 2, 0, 0, 0]

>>> ### get parameter from demo.dodoctest_next_parameter()
>>> set_report_service_conf(slacgs_password, gdrive_user_email)
>>> param, _ = doctest_next_parameter()

>>> ## create model object
>>> model = Model(param, N=[2**i for i in range(1,11)], max_n=1024)

>>> ## create simulator object
>>> slacgs = Simulator(model, step_size=1, max_steps=10, min_steps=5, precision=1e-4, augmentation_until_n = 1024, verbose=False)

>>> ## run simulation
>>> slacgs.run() 

>>> ## define spreadsheet title
>>> ## spreadsheet_title = 'title of spreadsheet'
>>> _, spreadsheet_title = doctest_next_parameter()

>>> ## create GspreadClient object
>>> gc = GspreadClient(spreadsheet_title)

>>> ## write simulation results to spreadsheet
>>> slacgs.report.write_to_spreadsheet(gc, verbose=False)

Enumtypes

class slacgs.enumtypes.DictionaryType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Implemented Dictionary Types

- LINEAR: dictionary with linear classifiers

class slacgs.enumtypes.LossType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Implemented Loss Functions

“\(h(\mathbf{x}) = \mathbf{w} \cdot \mathbf{x} + b\)” is a linear classifier.
The hyperplane \(h\) defined by this equation represents the decision boundary that separates classes in a linearly separable space.
The hypothesis space \(H\) consists of all possible linear classifiers.

Let \(\hat{h}^{(D)}\) be the best empirical classifier in the dictionary \(H\) for the dataset \(D\) with \(d\) features and \(n\) samples, i.e., the classifier \(h\) in \(H\) with the minimum empirical error rate. Under these conditions, we can define three error rates:

\(L(\hat{h}^{(D)}) =\) the theoretical error rate of the classifier \(\hat{h}^{(D)}\)
\(\hat{L}(\hat{h}^{(D)}) =\) the empirical error rate of the classifier \(\hat{h}^{(D)}\)
\(\hat{L}(\hat{h}^{(D)},D') =\) the empirical error rate of the classifier \(\hat{h}^{(D)}\) using a test dataset \(D'\)

The Bayes Error (also: Bayes Risk) is defined as the minimum theoretical achievable error rate:

\(\min_{h\in H} L(h) =\) the smallest theoretically achievable error rate for a classifier \(h\) in dictionary \(H\).

- THEORETICAL: estimated using probability theory

- EMPIRICALTRAIN: estimated using empirical approach with train data

- EMPIRICALTEST: estimated using empirical approach with test data

Gspread_client

class slacgs.gspread_client.GspreadClient(pygsheets_service, spreadsheet_title, verbose=True)

GspreadClient performs operations using gspread, a Python API for Google Sheets. It is used to write simulation results to a spreadsheet.

Constructor for GspreadClient class.

Parameters:

pygsheets_service (Client) – pygsheets service
spreadsheet_title (str) – title of the spreadsheet
verbose (bool, optional) – print messages to console, defaults to True

Raises:

TypeError – if pygsheets_service is not a pygsheets.service.client.Client object if spredsheet_title is not a string if verbose is not a boolean
ValueError – if spredsheet_title is empty

param_not_in_home(params)

check if params is already in home sheet

Parameters:: params (list[float] or tuple[float]) – list of parameters containing Sigmas and Rhos
Returns:: True if params is not in home sheet, False otherwise
Return type:: bool

print_first_call_to_spreadsheet_writing_service()

Decorator that prints a message to console when a method of GspreadClient is called for the first time. :param fn: function to be decorated :type fn: function

Returns:: decorated function
Return type:: function

Gdrive_client

class slacgs.gdrive_client.GdriveClient(drive_service=None, spreadsheet_service=None, gdrive_account_email=None)

perform operations on Google Drive.

Constructor for GdriveClient class.

Parameters:

drive_service (googleapiclient.discovery.Resource) – Google Drive API Resource object.
spreadsheet_service (googleapiclient.discovery.Resource) – Google Sheets API Resource object.
gdrive_account_email (str) – email of the Google account to be used to share reports folder.

Raises:

TypeError – if drive_service is not a googleapiclient.discovery.Resource object; if sheets_service is not a googleapiclient.discovery.Resource object; if gdrive_account_email is not a string.
ValueError – if gdrive_account_email is not a valid email address.

check_spreadsheet_existence(name)

Check if a spreadsheet with the given name exists.

Parameters:: name (str) – name of the spreadsheet.
Returns:: True if a spreadsheet with the given name exists, False otherwise.
Return type:: bool
Raises:: ValueError – if name is not a string.

create_folder(folder_name, parent_folder_id=None, verbose=True)

Create a new folder with the given name. If parent_folder_id is not None, the folder will be created inside the folder with the given ID.

Parameters:

folder_name (str) – name of the folder.
parent_folder_id (str) – ID of the parent folder.
verbose (bool) – whether to print the path of the created folder.

Returns:

ID of the created folder.

Return type:

str

Raises:

ValueError – if folder_name or parent_folder_id is not a string.

create_spreadsheet(name, verbose=True)

Create a new spreadsheet with the given name.

Parameters:

name (str) – name of the spreadsheet.
verbose (bool) – if True, print a message after creating the spreadsheet.

Returns:

ID of the created spreadsheet.

Return type:

str

Raises:

ValueError – if name is not a string.

delete_file(file_id)

Delete a file.

Parameters:: file_id (str) – ID of the file.

delete_folder(folder_id)

Delete a folder.

Parameters:: folder_id (str) – ID of the folder.
Raises:: ValueError – if folder_id is not a string.

delete_spreadsheet(spreadsheet_id)

Delete a spreadsheet.

Parameters:: spreadsheet_id (str) – ID of the spreadsheet to be deleted.
Raises:: ValueError – if spreadsheet_id is not a string.

file_exists_by_path(file_path)

Check if a file with the given path exists.

Parameters:: file_path (str) – The path to the file you want to check.
Returns:: True if the file exists, False otherwise.
Raises:: ValueError – If file_path is not a string.

file_exists_in_folder(file_name, folder_id)

Check if a file with the given name exists in the given folder.

Parameters:

file_name (str) – The name of the file you want to check.
folder_id (str) – The ID of the folder you want to check.

Returns:

True if the file exists, False otherwise.

Raises:

ValueError – If file_name or folder_id is not a string.

folder_exists(report_folder_name)

Check if a folder with the given name exists.

Parameters:: report_folder_name (str) – name of the folder.
Returns:: True if a folder with the given name exists, False otherwise.
Return type:: bool
Raises:: ValueError – if report_folder_name is not a string.

folder_exists_by_path(folder_path)

Check if a folder with the given path exists.

Parameters:: folder_path (str) – The path to the folder you want to check.
Returns:: True if the folder exists, False otherwise.
Raises:: ValueError – If folder_path is not a string.

get_file_id_by_path(file_path)

Get the ID of a file.

Parameters:: file_path (str) – path of the file.
Returns:: ID of the file.
Return type:: str
Raises:: ValueError – if file_path is not a string.

get_folder_id_by_name(folder_name)

Get the ID of a folder by its name. If no folder with the given name is found, return None.

Parameters:

folder_name (str) – name of the folder.
folder_name – name of the folder.

Returns:

ID of the folder with the given name.

Return type:

str or None

Raises:

ValueError – if folder_name is not a string.

Returns:

get_folder_id_by_path(folder_path)

Get the ID of a folder by its path.

Parameters:: folder_path (str) – The path to the folder you want to get the ID of.
Returns:: The ID of the folder.
Raises:: ValueError – If folder_path is not a string.

get_folder_path(folder_id)

Get the path of a folder.

Parameters:: folder_id (str) – ID of the folder.
Returns:: path of the folder.
Return type:: str
Raises:: ValueError – if folder_id is not a string.

get_root_folder_id()

Get the ID of the root folder.

Returns:: ID of the root folder.
Return type:: str

get_spreadsheet_id_by_name(name)

Get the ID of a spreadsheet with the given name.

Parameters:: name (str) – name of the spreadsheet.
Returns:: ID of the spreadsheet with the given name.
Return type:: str
Raises:: ValueError – if name is not a string.

get_spreadsheet_path_by_id(spreadsheet_id)

Get the path of a spreadsheet by its ID.

Parameters:: spreadsheet_id (str) – ID of the spreadsheet.
Returns:: path of the spreadsheet with the given ID.
Return type:: str
Raises:: ValueError – if spreadsheet_id is not a string.

move_file_to_folder(file_id, folder_id, verbose=True)

Move a file to a folder.

Parameters:

file_id (str) – ID of the file to be moved.
folder_id (str) – ID of the folder to which the file will be moved.
verbose (bool) – whether to print messages about the operation status.

Raises:

ValueError – if file_id or folder_id is not a string.

move_folder_to_another_folder(folder_id, new_parent_folder_id, verbose=True)

Move a folder to another folder.

Parameters:

folder_id (str) – ID of the folder to be moved.
new_parent_folder_id (str) – ID of the folder to which the folder will be moved.
verbose (bool) – whether to print messages about the operation status.

Returns:

None

Return type:

None

Raises:

ValueError – if folder_id or new_parent_folder_id is not a string.

share_folder_with_gdrive_account(folder_id, verbose=True)

Share a folder with the GDrive account.

Parameters:

folder_id (str) – ID of the folder.
verbose (bool) – whether to print messages or not.

Returns:

None

Return type:

None

Raises:

ValueError – if folder_id is not a string.

upload_file_to_drive(file_path, folder_id, verbose=True)

Uploads a file to a Google Drive folder.

Parameters:

file_path (str) – The path to the file you want to upload.
folder_id (str) – The ID of the Google Drive folder where you want to upload the file.

Utils

slacgs.utils.cls(): Clears the terminal screen. Works on both Windows and Linux.

slacgs.utils.get_grandparent_folder_path()

Get the grandparent folder path of the current script.

Returns:: The grandparent folder path of the current script.
Return type:: str

slacgs.utils.get_key(password=None)

Get the key. :param password: The password to decrypt the key. :type password: str

Returns:: The key content.
Return type:: str

slacgs.utils.get_parent_folder_path()

Get the parent folder path of the current script.

Returns:: The parent folder path of the current script.
Return type:: str

slacgs.utils.get_user_folder_path()

Returns the user’s home folder in any operating system.

Returns:: The user’s home folder.
Return type:: str

slacgs.utils.is_colab_notebook()

Check if the environment is a Google Colab notebook.

Returns:: True if the environment is a Google Colab notebook, False otherwise.
Return type:: bool

slacgs.utils.is_jupyter_notebook()

Check if the environment is a Jupyter notebook.

Returns:: True if the environment is a Jupyter notebook, False otherwise.
Return type:: bool

slacgs.utils.is_notebook()

Check if the environment is a notebook.

Returns:: True if the environment is a notebook, False otherwise.
Return type:: bool

slacgs.utils.set_report_service_conf(path_to_google_cloud_service_account_api_key=None, user_google_account_email=None, slacgs_password=None)

Set the report service configuration. This function must be called before using the report service dependencies models (e.g. GspreadClient, GdriveClient).

Parameters:

slacgs_password (str) – The password used to enable our Report Service. Defaults to None.
user_google_account_email (str) – The user email used to authenticate the Google services. Defaults to None.
path_to_google_cloud_service_account_api_key (str) – The Google Cloud Service Account API Json Key used to build your own Report Service. Must be able to access Google Drive and Google Sheets API’s. Defaults to None.

Returns:

None

Raises:

TypeError – If slags_password is not a string.
TypeError – If user_google_account_email is not a string.
TypeError – If google_cloud_service_account_api_key is not a string.

Observations:: If slags_password or user_google_account_email is None, then the user will be prompted to enter the password or email. If google_cloud_service_account_api_key is given, then the password will be ignored.

slacgs.utils.report_service_conf = {'drive_service': None, 'images_path': 'C:\\Users\\paulraz\\slags\\images\\', 'pygsheets_service': None, 'reports_path': 'C:\\Users\\paulraz\\slags\\reports\\', 'spreadsheet_service': None, 'user_email': None}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Demo

slacgs.demo.add_simulation_to_custom_scenario_spreadsheet(params, scenario_number, dims_to_simulate=None, dims_to_compare=None, verbose=True)

add a simulation to a custom scenario spreadsheet

Parameters:

params (list[float|int] or tuple[float|int]) – a list containnong Sigmas and Rhos
scenario_number (int) – scenario number
dims_to_simulate (list[int] or tuple[int]) – dimensionalities to simulate (if None, all dimensionalities will be simulated) (default: None)
dims_to_compare (list[int] or tuple[int]) – dimensionalities to compare (if None, the last two dimensionalities of dims_to_simulate will be compared) (default: None)
verbose (bool) – whether to print progress to console output (default: True)

Returns:

True if successful, False otherwise

Return type:

bool

Raises:

TypeError – if params is not a list[float|int] or tuple[float|int]; if scenario_number is not an int; if dims_to_simulate is not a list[int] or tuple[int]; if dims_to_compare is not a list[int] or tuple[int]
ValueError – if scenario_number is < 5; if dims_to_compare is not a subset of dims_to_simulate; if dims_to_compare length is not 2

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> params = (1, 1, 3, -0.2, 0, 0)
>>> scenario_number = 5
>>> add_simulation_to_custom_scenario_spreadsheet(params, scenario_number)

slacgs.demo.add_simulation_to_custom_scenario_spreadsheet_test(params, scenario_number, dims_to_simulate=None, dims_to_compare=None, verbose=True)

add a simulation to a custom test scenario

Parameters:

params (list[float|int] or tuple[float|int]) – a list containnong Sigmas and Rhos
scenario_number (int) – scenario number
dims_to_simulate (list[int] or tuple[int]) – dimensionalities to simulate (if None, all dimensionalities will be simulated) (default: None)
dims_to_compare (list[int] or tuple[int]) – dimensionalities to compare (if None, the last two dimensionalities of dims_to_simulate will be compared) (default: None)
verbose (bool) – whether to print progress to console output (default: True)

Returns:

True if successful, False otherwise

Return type:

bool

Raises:

TypeError – if params is not a list[float|int] or tuple[float|int]; if scenario_number is not an int; if dims_to_simulate is not a list[int] or tuple[int]; if dims_to_compare is not a list[int] or tuple[int]
ValueError – if scenario_number is < 5; if dims_to_compare is not a subset of dims_to_simulate; if dims_to_compare length is not 2

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> params = (1, 1, 3, -0.2, 0, 0)
>>> scenario_number = 5
>>> add_simulation_to_custom_scenario_spreadsheet_test(params, scenario_number)

slacgs.demo.add_simulation_to_experiment_scenario_spreadsheet(params, scenario_number, verbose=True)

add simulation results to one of the experiment scenario spreadsheets

Parameters:

params (list[float|int] or tuple[float|int]) – a list containnong Sigmas and Rhos
scenario_number (int) – scenario number
verbose (bool) – if True, print simulation progress (default: True)

Returns:

None

Raises:

TypeError – if scenario is not an int; if params is not a list[int|float] or tuple[int|float]
ValueError – if params is not a valid parameter list; if scenario is not between 1 and 4

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> scenario_number = 1
>>> params = [1, 1, 2.1, 0, 0, 0]
>>> add_simulation_to_experiment_scenario_spreadsheet_test(params, scenario_number)

>>> scenario_number = 2
>>> params = [1, 1, 2, -0.15, 0, 0]
>>> add_simulation_to_experiment_scenario_spreadsheet_test(params, scenario_number)

>>> scenario_number = 3
>>> params = [1, 1, 2, 0, 0.15, 0.15]
>>> add_simulation_to_experiment_scenario_spreadsheet_test(params, scenario_number)

>>> scenario_number = 4
>>> params = [1, 1, 2, -0.1, 0.15, 0.15]
>>> add_simulation_to_experiment_scenario_spreadsheet_test(params, scenario_number)

slacgs.demo.doctest_next_parameter()

return the next parameter to be simulated on doctests, and also the adequate spreadsheet title

Returns:: PARAM, SPREADSHEET_TITLE
Return type:: tuple
Example:

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> params, spreadsheet_title = doctest_next_parameter()

slacgs.demo.print_experiment_scenarios(): Print the experiment scenarios parameters in a table.

slacgs.demo.run_custom_scenario(scenario_list, scenario_number, dims_to_simulate=None, dims_to_compare=None, verbose=True)

run a custom scenario and write the results to a Google Spreadsheet shared with the user. A Scenario is a list with params to simulate.

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

scenario_list (list[list[float|int]] or tuple[list[float|int]]) – scenario list
scenario_number (int) – scenario number
dims_to_simulate (list[int] or tuple[int]) – dimensionalities to simulate (if None, all possible dimensionalities will be simulated) (default: None)
dims_to_compare (list[int] or tuple[int]) – dimensionalities to compare (if None, the last two dimensionalities of dims_to_simulate will be compared) (default: None)
verbose (bool) – whether to print messages to stdout or not

Returns:

True if simulation was successful

Return type:

bool

Raises:

TypeError – if scenario_list is not a list[list[float|int]] or tuple[list[float|int]]; if scenario_number is not an int; if dims_to_simulate is not a list[int] or tuple[int]; if dims_to_compare is not a list[int] or tuple[int];
ValueError – if scenario_number is not a valid scenario number; if dims_to_compare is not a subset of dims_to_simulate; if dims_to_compare length is not 2;

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> scenario_list = [[1,1,3,round(0.1*rho,1),0,0] for rho in range(-1,2)]
>>> scenario_number = 5
>>> run_custom_scenario(scenario_list, scenario_number)

slacgs.demo.run_custom_scenario_test(scenario_list, scenario_number, dims_to_simulate=None, dims_to_compare=None, verbose=True)

run a custom test scenario and write the results to a Google Spreadsheet shared with the user. A Scenario is a list with params to simulate.

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

scenario_list (list[list[float|int]] or tuple[list[float|int]]) – scenario list
scenario_number (int) – scenario number
dims_to_simulate (list[int] or tuple[int]) – dimensionalities to simulate (if None, all possible dimensionalities will be simulated) (default: None)
dims_to_compare (list[int] or tuple[int]) – dimensionalities to compare (if None, the last two dimensionalities of dims_to_simulate will be compared) (default: None)
verbose (bool) – whether to print messages to stdout or not

Returns:

True if simulation was successful

Return type:

bool

Raises:

TypeError – if scenario_list is not a list[list[float|int]] or tuple[list[float|int]]; if scenario_number is not an int; if dims_to_simulate is not a list[int] or tuple[int]; if dims_to_compare is not a list[int] or tuple[int];
ValueError – if scenario_number is not a valid scenario number; if dims_to_compare is not a subset of dims_to_simulate; if dims_to_compare length is not 2;

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> scenario_list = [[1,1,3,round(0.1*rho,1),0,0] for rho in range(-1,2)]
>>> scenario_number = 5
>>> run_custom_scenario_test(scenario_list, scenario_number)

slacgs.demo.run_custom_simulation(params, dims_to_simulate=None, dims_to_compare=None, verbose=True)

run a custom simulation for any dimensionality and cardinality

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

params (list[float|int] or tuple[float|int]) – a list containnong Sigmas and Rhos
dims_to_simulate (list[int] or tuple[int]) – dimensionalities to simulate (if None, all dimensionalities will be simulated) (default: None)
dims_to_compare (list[int] or tuple[int]) – dimensionalities to compare (if None, the last two dimensionalities of dims_to_simulate will be compared) (default: None)
verbose (bool) – whether to print progress to console output (default: True)

Returns:

True if successful, False otherwise

Return type:

bool

Raises:

TypeError – if params is not a list[float|int] or tuple[float|int]; if dims_to_compare is not a list[int] or tuple[int]
ValueError – if dims_to_compare length is not 2; if dims_to_compare is not a subset of dims_to_simulate

Examples

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> ## 2 features
>>> params = [1, 2, 0.4]
>>> run_custom_simulation(params)

>>> ## 3 features
>>> params = [1, 1, 4, -0.2, 0.1, 0.1]
>>> run_custom_simulation(params)

>>> ## 4 features
>>> params = [1, 1, 1, 2, 0, 0, 0, 0, 0, 0]
>>> run_custom_simulation(params)

>>> ## 5 features
>>> params = [1, 1, 2, 2, 2, -0.3, -0.2, -0.1, 0, 0.1, 0.2, 0.2, 0, 0, 0]
>>> dims_to_compare = (2, 5)
>>> run_custom_simulation(params, dims_to_compare)

>>> ## 6 features
>>> params = [1, 2, 3, 4, 5, 6, -0.3, -0.3, -0.2, -0.2, -0.1, -0.1, 0, 0, 0.1, 0.1, 0.2, 0.2, 0.3, 0.3, 0.4]
>>> run_custom_simulation(params)

slacgs.demo.run_custom_simulation_test(params, dims_to_simulate=None, dims_to_compare=None, verbose=True)

run a custom simulation for any dimensionality and cardinality

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

params (list[float|int] or tuple[float|int]) – a list containnong Sigmas and Rhos
dims_to_simulate (list[int] or tuple[int]) – dimensionalities to simulate (if None, all dimensionalities will be simulated) (default: None)
dims_to_compare (list[int] or tuple[int]) – dimensionalities to compare (if None, the last two dimensionalities of dims_to_simulate will be compared) (default: None)
verbose (bool) – whether to print progress to console output (default: True)

Returns:

True if successful, False otherwise

Return type:

bool

Raises:

TypeError – if params is not a list[float|int] or tuple[float|int]; if dims_to_compare is not a list[int] or tuple[int]
ValueError – if dims_to_compare length is not 2; if dims_to_compare is not a subset of dims_to_simulate

Example:

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> ## 2 features
>>> params = [1, 2, 0.4]
>>> run_custom_simulation_test(params, dims_to_compare)

>>> ## 3 features
>>> params = [1, 1, 4, -0.2, 0.1, 0.1]
>>> run_custom_simulation_test(params, dims_to_compare)

>>> ## 4 features
>>> params = [1, 1, 1, 2, 0, 0, 0, 0, 0, 0]
>>> dims_to_compare = (3, 4)
>>> run_custom_simulation_test(params, dims_to_compare)

>>> ## 5 features
>>> params = [1, 1, 2, 2, 2, -0.3, -0.2, -0.1, 0, 0.1, 0.2, 0.2, 0, 0, 0]
>>> dims_to_compare = (2, 5)
>>> run_custom_simulation_test(params, dims_to_compare)

>>> params = [1, 2, 3, 4, 5, 6, -0.3, -0.3, -0.2, -0.2, -0.1, -0.1, 0, 0, 0.1, 0.1, 0.2, 0.2, 0.3, 0.3, 0.4]
>>> run_custom_simulation_test(params)

slacgs.demo.run_experiment(start_scenario=1, verbose=True)

run all simulations in all experiment scenarios

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Dimensions simulated:

1D: 1 feature
2D: 2 features
3D: 3 features

Dimensions compared:

2D vs 3D: 2 features vs 3 features

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

start_scenario – scenario to start the experiment
verbose – if True, prints messages to console output

Returns:

0 if all parameters have been simulated

Raises:

ValueError – if start_scenario is not between 1 and 4
TypeError – if start_scenario is not an int

Examples

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> run_experiment()

slacgs.demo.run_experiment_simulation(start_scenario=1, verbose=True)

run a simulation for one of the experiment scenarios and return True if there are still parameters to be simulated and False otherwise.

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Dimensions simulated:

1D: 1 feature
2D: 2 features
3D: 3 features

Dimensions compared:

2D vs 3D: 2 features vs 3 features

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

start_scenario (int) – scenario to start the simulation (default is 1)
verbose (bool) – if True, print simulation progress to stdout (default is True)

Returns:

True if there are still parameters to be simulated and False otherwise

Return type:

bool

Raises:

ValueError – if start_scenario is not between 1 and 4
TypeError – if start_scenario is not an int

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> run_experiment_simulation()

slacgs.demo.run_experiment_simulation_test(start_scenario=1, verbose=True)

run a simulation test for one of the experiment scenarios and return True if there are still parameters to be simulated and False otherwise.

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Dimensions simulated:

1D: 1 feature
2D: 2 features
3D: 3 features

Dimensions compared:

2D vs 3D: 2 features vs 3 features

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

start_scenario (int) – scenario to start the simulation test
verbose (bool) – if True, print simulation progress to stdout (default is True)

Returns:

True if there are still parameters to be simulated and False otherwise

Return type:

bool

Raises:

ValueError – if start_scenario is not between 1 and 4
TypeError – if start_scenario is not an int

Example

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> run_experiment_simulation_test(verbose=False)

slacgs.demo.run_experiment_test(start_scenario=1, verbose=True)

run all simulations in all experiment scenarios

Reports with results will be stored in a Google Spreadsheet for each: Experiment Scenario, Custom Experiment Scenario and another one for the Custom Simulations.
The Spreadsheets are stored in a Google Drive folder named ‘slacgs.demo.<user_email>’ owned by slacgs’ google service account and shared with the user’s Google Drive account.
Also, images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Reports Exported:

Loss Report: Contains mainly results focused on Loss Functions evaluations for each dimensionality of the model.
Compare Resport: Contains mainly results focused on comparing the performance of the Model using 2 features and 3 features.
Home Report (Scenario): Contains results from all simulations in a Scenario and links to the other reports. (available only for comparison between 2D and 3D)

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.
Simulation Data plot .png: Contains a plot with the data points (n = 1024, dims=[2,3] ) generated for a Model in a Simulation.
Simulation Loss plot .png: Contains a plot with the loss values (Theoretical, Empirical with Train Data, Empirical with Test data) generated for a Model in a Simulation.

Loss Functions:

Theoretical Loss: estimated using probability theory
Empirical Loss with Train Data: estimated using empirical approach with train data
Empirical Loss with Test Data: estimated using empirical approach with test data

Dimensions simulated:

1D: 1 feature
2D: 2 features
3D: 3 features

Dimensions compared:

2D vs 3D: 2 features vs 3 features

Cardinalities simulated:

N = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024] (+ [2048, 4096, 8192] if L_3 > L_2)

Parameters:

start_scenario – scenario to start the experiment test
verbose – if True, prints messages to console output

Returns:

0 if all parameters have been simulated

Raises:

ValueError – if start_scenario is not between 1 and 4
TypeError – if start_scenario is not an int

Examples

>>> from slacgs.demo import *

>>> # opt-1. set report service configuration with your own google cloud service account key file
>>> PATH_TO_KEY_FILE = '/path/to/your/google/cloud/service/account/key/file.json'
>>> set_report_service_conf(PATH_TO_KEY_FILE)

>>> # opt-2 set report service configuration to use slacgs' server if you have the access password
>>> set_report_service_conf()

>>> run_experiment_test()

slacgs.demo.save_scenario_figures_as_gif(scenario, scenario_number, export_path=None, duration=200, loop=0, verbose=True)

Save a list of matplotlib Figure objects as an animated GIF.

images with data visualization will be exported to a local folder inside user’s local folder (<user>/slacgs/images/ or /content/slacgs/images (for G-colab) )

Images Exported (<user>/slacgs/images/ or /content/slacgs/images [for G-colab] ):

Scenario Data plots .gif: Contains a gif with all plots with the data points (n = 1024, dims=[2,3] ) generated for all Models in an Experiment Scenario.

Parameters:

scenario (list[tuple[float|int]]) – A list of parameter sets to simulate.
scenario_number (int) – The scenario number.
export_path (str) – The file path where the animated GIF will be saved.
duration (int, optional) – The duration (in milliseconds) between frames. Default is 200ms.
loop (int, optional) – The number of loops for the animation. Use 0 for infinite looping (default).

Returns:

None

slacgs.demo.start_google_drive_service(password=None, user_email=None)

start Google Drive Client for demo report service

Parameters:

password (str) – password for slacgs report service
user_email (str) – email for Google Drive account to be used for report service

Notes

if password and user_email are None, the report_service_conf dictionary will be used to get the password and user_email