Module leapyear.analytics.classes¶
Classes related to LeapYear analyses.
Analysis Classes¶
This section documents classes that define and process analyses in the LeapYear system.
Main Classes¶

class
leapyear.analytics.classes.
Analysis
¶ Any analysis that can be performed on the LeapYear server.
It contains an analysis and a relation on which the analysis should be performed.

check
(*, cache=None, allow_max_budget_allocation=None, precise=None, **kwargs)¶ Check the analysis for errors.
If any errors are present, the function will raise a descriptive error. If no errors are found, then the function will return self.
 Return type
Analysis
[~_Result, ~_Model, ~_ModelMetadata]

run
(*, detach=False, cache=None, allow_max_budget_allocation=None, precise=None, rich_result=False, max_timeout_sec=300.0, minimum_dataset_size=None, **kwargs)¶ Run analysis.
 Parameters
detach (
bool
) – IfTrue
when the analysis is sent to the server, it will return immediately with an AsyncAnalysis object. The analysis will be evaluated in the background on the server. The client can check the result of the analysis later using the AsyncAnalysis object.cache (
Optional
[bool
]) – IfTrue
, then the first time this analysis is executed on the LeapYear server, the result will be cached. Subsequent calls to the identical analysis (withcache=True
) will fetch the cached version and not contribute to the security cost. IfNone
, the default caching behavior will be obtained from the connection.allow_max_budget_allocation (
Optional
[bool
]) – Default isTrue
. IfFalse
, raise anleapyear.exceptions.DataSetTooSmallException
when the randomness calibration system would run an analysis with the maximum privacy exposure per computation. IfNone
, the default value will be obtained from the connection.precise (
Optional
[bool
]) – WhenTrue
, request an answer with no noise added to the computation.rich_result (
bool
) – WhenTrue
, return a result with additional (potentially analysisspecific) metadata, including the privacy exposure expended in the process of performing the analysis. Defaults toFalse
.max_timeout_sec (
Optional
[float
]) – Whendetach=False
, specifies the maximum amount of time (in seconds) the user is willing to wait for a response. If set toNone
, the analysis will poll the server indefinitely. When computing on big data or longrunning machine learning tasks, we recommend using thedetach=True
feature and use the functions provided inAsyncAnalysis
. Defaults to 300 (5 minutes).minimum_dataset_size (
Optional
[int
]) – Whenminimum_dataset_size
is set, prevent computations on data sets that have fewer rows than the specified value. We recommend using this when an analysis could filter down to a small number of records, potentially consuming more privacy budget than is desired. Setting this will spend a small amount of privacy budget to estimate the number of rows involved in a computation. This value is superseded by an admindefinedminimum_dataset_size
parameter, if the admin’s value is larger.
 Returns
The result of the analysis. Multiple return types are possible.
 Return type
Union[_Model, AsyncAnalysis, RichResult[_Model, _ModelMetadata]]

maximum_privacy_exposure
(minimum_dataset_size=None)¶ Maximum privacy exposure associated with running this analysis.
Estimate the maximum incremental privacy exposure that could result from running this computation for the current user. The result is represented as a percentage of privacy exposure limit for each data source.
Note: Estimating maximum privacy exposure may incur a small amount of privacy exposure.
 Parameters
minimum_dataset_size (
Optional
[int
]) – Whenminimum_dataset_size
is set, prevent computations on data sets that have fewer rows than the specified value. Returns
A dictionary that maps a
TableIdentifier
to the estimated maximum fractional privacy exposure that running the analysis would incur for the associated table. Return type


class
leapyear.analytics.classes.
AsyncAnalysis
(async_job_id, analysis, rich_result)¶ Result of an asynchronous computation.
Represents an accessor for an asynchronous computation on the LeapYear server. It contains a unique async_job_id for a specific computation and a method to check the results of that computation at a later time.

check_status
()¶ Check the status of the given asynchronous job.
 Return type
AsyncJobStatus
[~JobResult]

cancel
()¶ Cancel the job.

wait_to_cancel
(**kwargs)¶ Wait for the given asynchronous job to finish.
Same as ‘wait’, but doesn’t error on cancellations. Takes the same arguments as ‘wait’.
 Return type
None

wait
(**kwargs)¶ Wait for the analysis to terminate using exponential backoff.
 Parameters
max_timeout_sec – Specifies the maximum amount of time (in seconds) the user is willing to wait for a response. If set to
None
,wait
will poll the server indefiniately. Defaults to 300.0 (5 minutes).initial_timeout_sec – The initial amount of time (in seconds) to wait before polling the server. Subsequent polling will wait
initial_timeout_sec * growth_factor
. Defaults to 1.0 (1 second).growth_factor – The exponential growth factor when polling the server for a completed job. Defaults to 1.0 (constant polling rate).
 Return type
Union
[~_Model,RichResult
[~_Model, ~_ModelMetadata]]

Analysis Subclasses¶
This section describes the subclasses of Analysis
, generally determined by what type of output they produce.

class
leapyear.analytics.classes.
BoundsAnalysis
¶ Analysis that results in a lower and upper bound.

class
leapyear.analytics.classes.
ClusteringAnalysis
¶ Analysis that results in a clustering model.

class
leapyear.analytics.classes.
ConfusionModelAnalysis
¶ Analysis that results in a ConfusionCurve object.

class
leapyear.analytics.classes.
CountAnalysis
¶ Analysis that results in a scalar count value.

class
leapyear.analytics.classes.
CountAnalysisWithRI
¶ Analysis that computes a scalar count value.
The user can request additional information about the computation with
run(rich_result=True)
. ARandomizationInterval
object will be generated.

class
leapyear.analytics.classes.
CrossValidationAnalysis
¶ Analysis that results in multiple results of the same type.

class
leapyear.analytics.classes.
DescribeAnalysis
¶ Analysis that produces a model describing a dataset.

class
leapyear.analytics.classes.
FailAnalysis
¶ An analysis that always fails.

class
leapyear.analytics.classes.
ForestModelAnalysis
¶ Analysis that results in a forest model.

class
leapyear.analytics.classes.
GradientBoostedTreeClassifierModelAnalysis
¶ Gradient boosted tree classifier analysis.
When executed, this analysis returns a model object of class
GradientBoostedTreeClassifier
.

class
leapyear.analytics.classes.
GroupbyAggAnalysis
¶ Analysis that results in a
GroupbyAgg
.

class
leapyear.analytics.classes.
GenLinAnalysis
¶ Analysis that results in a generalized linear model.

class
leapyear.analytics.classes.
Histogram2DAnalysis
¶ Analysis that results in a 2d histogram.

class
leapyear.analytics.classes.
HistogramAnalysis
¶ Analysis that results in a histogram.

class
leapyear.analytics.classes.
HyperOptAnalysis
¶ Analysis that returns the result of hyperparameter optimization.

class
leapyear.analytics.classes.
MatrixAnalysis
¶ Analysis that results in a matrix of float values.

class
leapyear.analytics.classes.
ScalarAnalysis
¶ Analysis that results in a scalar float value.

class
leapyear.analytics.classes.
ScalarAnalysisWithRI
¶ Analysis that computes a scalar value.
The user can request additional information about the computation with
run(rich_result=True)
. In this case, aRandomizationInterval
object will be generated.This likely interval is likely to include the exact value of the computation on the data sample.

class
leapyear.analytics.classes.
ScalarFromHistogramAnalysis
¶ Analysis that uses a histogram to compute a scalar value.

class
leapyear.analytics.classes.
SleepAnalysis
¶ An analysis that will sleep for a set amount of microseconds.

class
leapyear.analytics.classes.
TypeAnalysis
¶ Analysis that results list of counts associated with types.
Rich Results¶
This section documents classes related to rich results and privacy exposure measurements.

class
leapyear.analytics.classes.
RandomizationInterval
¶ An interval estimating the uncertainty in the exact answer, given randomized output.
A
RandomizationInterval
can be generated for a subset of the analyses offered by LeapYear by running an analysis withrun(rich_result = True)
.The interval between
low
andhigh
is expected to include the exact value of the computation on the data sample with the statedconfidence_level
(e.g. 95%). Parameters
confidence_level – The confidence that the exact answer lies within the interval.
low – The lower bound of the interval.
high – The upper bound of the interval.
estimation_method –
The method used to compute the interval depends on analysis type.
With
'bayesian'
method, the randomization interval is obtained using a posterior distribution analysis based on noninformative prior, the knowledge of randomized output and the scale of the randomization effect applied.With
'approximate'
method, the randomization interval is estimated using simplified simulation process.Note
The
'approximate'
estimation method tends to produce biased intervals for small data samples.

class
leapyear.analytics.classes.
PrivacyExposure
¶ A raw measure of privacy exposure for a collection of tables.
This is represented by a dictionary, mapping a
TableIdentifier
to the total privacy exposure that has been expended for the table corresponding to theTableIdentifier
.

class
leapyear.analytics.classes.
FractionalPrivacyExposure
¶ A fractional measure of privacy exposure for a collection of tables.
This is represented by a dictionary, mapping a
TableIdentifier
to the fraction of total privacy exposure that has been expended for the table corresponding to theTableIdentifier
.
Aggregate Results¶
This section documents classes related to aggregate resuls from group by operations.

class
leapyear.analytics.classes.
GroupbyAgg
¶ A GroupBy Aggregate.

to_dataframe
(groups_as_index=True)¶ Convert to a pandas DataFrame.
 Parameters
groups_as_index (bool, optional) – Whether the groupBy columns should be the
MultiIndex
of the resultingDataFrame
. IfFalse
, then the groupBy columns are made into columns of the output. By default True. Returns
A
pandas
DataFrame
, with a multiindex corresponding to the key columns of the groupBy operation ifgroups_as_index
= True. Return type
pd.DataFrame
