API Reference

This section provides detailed documentation for all ACRO classes, functions, and modules.

Core Classes

ACRO Classes

• ACRO Class
  • ACRO
  • Method Reference
• Records Class
  • Records Class
  • Record Class
  • Module-Level Functions

ACRO Class

The main entry point. Inherits from Tables and Regression mixins which provide the analysis methods.

class acro.ACRO(config='default', suppress=False, mitigation=None, round_base=None, federated=None)

Bases: Tables, Regression

ACRO: Automatic Checking of Research Outputs.

Attributes:

configdict

Safe parameters and their values.

resultsRecords

The current outputs including the results of checks.

mitigationstr

Return the current mitigation strategy.

round_baseint

Return the base used by the round mitigation strategy.

suppressbool

Return True iff the active mitigation strategy is ‘suppress’.

Parameters:

• config (str)

• suppress (bool)

• mitigation (str | None)

• round_base (int | None)

• federated (bool | None)

Methods

add_comments(output, comment)	Add a comment to an output.
add_exception(output, reason)	Add an exception request to an output.
crosstab(index, columns[, values, rownames, ...])	Compute a simple cross tabulation of two (or more) factors.
custom_output(filename[, comment])	Add an unsupported output to the results dictionary.
disable_rounding()	Turn rounding off.
disable_suppression()	Turn suppression off during a session.
enable_rounding([base])	Turn rounding on.
enable_suppression()	Turn suppression on during a session.
finalise([path, ext, interactive])	Create a results file for checking.
hist(data, column[, by_val, grid, ...])	Create a histogram from a single column.
logit(endog, exog[, missing, check_rank])	Fits Logit model.
logitr(formula, data[, subset, drop_cols])	Fits Logit model from a formula and dataframe.
ols(endog[, exog, missing, hasconst])	Fits Ordinary Least Squares Regression.
olsr(formula, data[, subset, drop_cols])	Fits Ordinary Least Squares Regression from a formula and dataframe.
pie(data, column[, filename])	Create a pie chart from a categorical column.
pivot_table(data[, values, index, columns, ...])	Create a spreadsheet-style pivot table as a DataFrame.
print_outputs()	Print the current results dictionary.
probit(endog, exog[, missing, check_rank])	Fits Probit model.
probitr(formula, data[, subset, drop_cols])	Fits Probit model from a formula and dataframe.
remove_output(key)	Remove an output from the results.
rename_output(old, new)	Rename an output.
show_fair_summaries()	Print IDs and FAIR summaries for all outputs in session.
surv_func(time, status, output[, entry, ...])	Estimate the survival function.

Examples

>>> acro = ACRO()
>>> results = acro.ols(
...     y, x
... )
>>> results.summary()
>>> acro.finalise(
...     "MYFOLDER",
...     "json",
... )

__init__(config='default', suppress=False, mitigation=None, round_base=None, federated=None)

Construct a new ACRO object and reads parameters from config.

Parameters:

configstr

Name of a yaml configuration file with safe parameters.

suppressbool, default False

Whether to automatically apply suppression (back-compat alias for mitigation="suppress"). Ignored when mitigation is set.

mitigationstr, optional

The disclosure-control strategy to apply, one of "none", "suppress", "round". When None, derived from suppress.

round_baseint, optional

The base to round to when mitigation="round". Defaults to the safe_round_base value from the yaml config.

federatedbool, optional

Whether to run in federated mode. When True, no SDC checks are performed; instead, evidence is collected and written to evidence.json for a trusted aggregator to review. When None, falls back to the yaml config value (default False). In standalone mode (False), outputs are checked and a results.json file is created.

Parameters:

• config (str)

• suppress (bool)

• mitigation (str | None)

• round_base (int | None)

• federated (bool | None)

Return type:

None

Notes

Federated vs Standalone Mode:

• Standalone (default): ACRO checks outputs locally and produces results.json with pass/fail/review statuses.

• Federated mode: ACRO collects evidence in evidence.json without performing checks, for later review by a trusted aggregator.

Examples

>>> import acro
>>> # Standalone mode with suppression
>>> acro_session = acro.ACRO(suppress=True)
>>>
>>> # Federated mode for TRE aggregator
>>> acro_fed = acro.ACRO(federated=True)
>>>
>>> # Custom configuration
>>> acro_custom = acro.ACRO(config="my_config", mitigation="round")

property round_base: int

Return the base used by the round mitigation strategy.

finalise(path='outputs', ext='json', interactive=False)

Create a results file for checking.

Parameters:

pathstr

Name of a folder to save outputs.

extstr

Extension of the results file. Valid extensions: {json, xlsx}.

interactivebool

Whether to prompt the user to request exceptions for failing outputs.

Returns:

Records

Object storing the outputs.

Parameters:

• path (str)

• ext (str)

• interactive (bool)

Return type:

Records | None

remove_output(key)

Remove an output from the results.

Parameters:

keystr

Key specifying which output to remove, e.g., ‘output_0’.

Parameters:

key (str)

Return type:

None

print_outputs()

Print the current results dictionary.

Returns:

str

String representation of all outputs.

Return type:

str

custom_output(filename, comment='')

Add an unsupported output to the results dictionary.

Parameters:

filenamestr

The name of the file that will be added to the list of the outputs.

commentstr

An optional comment.

Returns:

bool

False if the file extension is blocked, True otherwise.

Parameters:

• filename (str)

• comment (str)

Return type:

bool

rename_output(old, new)

Rename an output.

Parameters:

oldstr

The old name of the output.

newstr

The new name of the output.

Parameters:

• old (str)

• new (str)

Return type:

None

add_comments(output, comment)

Add a comment to an output.

Parameters:

outputstr

The name of the output.

commentstr

The comment.

Parameters:

• output (str)

• comment (str)

Return type:

None

add_exception(output, reason)

Add an exception request to an output.

Parameters:

outputstr

The name of the output.

reasonstr

The comment.

Parameters:

• output (str)

• reason (str)

Return type:

None

enable_suppression()

Turn suppression on during a session.

Return type:

None

disable_suppression()

Turn suppression off during a session.

Return type:

None

enable_rounding(base=None)

Turn rounding on. Overwrites any prior suppress=True (not restored on disable_rounding).

Parameters:

base (int | None)

Return type:

None

disable_rounding()

Turn rounding off. Always falls back to mitigation=’none’ (prior suppress not restored).

Return type:

None

crosstab(index, columns, values=None, rownames=None, colnames=None, aggfunc=None, margins=False, margins_name='All', dropna=True, normalize=False, show_suppressed=False)

Compute a simple cross tabulation of two (or more) factors.

By default, computes a frequency table of the factors unless an array of values and an aggregation function are passed.

Parameters:

indexarray-like, Series, or list of arrays/Series

Values to group by in the rows.

columnsarray-like, Series, or list of arrays/Series

Values to group by in the columns.

valuesarray-like, optional

Array of values to aggregate according to the factors. Requires aggfunc be specified.

rownamessequence, default None

If passed, must match number of row arrays passed.

colnamessequence, default None

If passed, must match number of column arrays passed.

aggfuncstr, optional

If specified, requires values be specified as well.

marginsbool, default False

Add row/column margins (subtotals).

margins_namestr, default ‘All’

Name of the row/column that will contain the totals when margins is True.

dropnabool, default True

Do not include columns whose entries are all NaN. THIS IS FORCED TO BE FALSE for SDC reasons

normalizebool, {‘all’, ‘index’, ‘columns’}, or {0,1}, default False

Normalize by dividing all values by the sum of values. - If passed ‘all’ or True, will normalize over all values. - If passed ‘index’ will normalize over each row. - If passed ‘columns’ will normalize over each column. - If margins is True, will also normalize margin values.

show_suppressedbool. default False

Deprecated in v.10, only present for backwards compatibility how the totals are being calculated when the suppression is true

Returns:

DataFrame

Cross tabulation of the data.

Parameters:

• index (Any)

• columns (Any)

• values (Any)

• rownames (Any)

• colnames (Any)

• aggfunc (str | list[str] | None)

• margins (bool)

• margins_name (str)

• dropna (bool)

• normalize (bool | str)

• show_suppressed (bool)

Return type:

DataFrame

hist(data, column, by_val=None, grid=True, xlabelsize=None, xrot=None, ylabelsize=None, yrot=None, axis=None, sharex=False, sharey=False, figsize=None, layout=None, bins=10, backend=None, legend=False, filename='histogram.png', **kwargs)

Create a histogram from a single column.

The dataset and the column’s name should be passed to the function as parameters. If more than one column is used the histogram will not be calculated.

To save the histogram plot to a file, the user can specify a filename otherwise ‘histogram.png’ will be used as the filename. A number will be appended automatically to the filename to avoid overwriting the files.

Parameters:

dataDataFrame

The pandas object holding the data.

columnstr

The column that will be used to plot the histogram.

by_valobject, optional

If passed, then used to form histograms for separate groups.

gridbool, default True

Whether to show axis grid lines.

xlabelsizeint, default None

If specified changes the x-axis label size.

xrotfloat, default None

Rotation of x axis labels. For example, a value of 90 displays the x labels rotated 90 degrees clockwise.

ylabelsizeint, default None

If specified changes the y-axis label size.

yrotfloat, default None

Rotation of y axis labels. For example, a value of 90 displays the y labels rotated 90 degrees clockwise.

axisMatplotlib axes object, default None

The axes to plot the histogram on.

sharexbool, default True if ax is None else False

In case subplots=True, share x axis and set some x axis labels to invisible; defaults to True if ax is None otherwise False if an ax is passed in. Note that passing in both an ax and sharex=True will alter all x axis labels for all subplots in a figure.

shareybool, default False

In case subplots=True, share y axis and set some y axis labels to invisible.

figsizetuple, optional

The size in inches of the figure to create. Uses the value in matplotlib.rcParams by default.

layouttuple, optional

Tuple of (rows, columns) for the layout of the histograms.

binsint or sequence, default 10

Number of histogram bins to be used. If an integer is given, bins + 1 bin edges are calculated and returned. If bins is a sequence, gives bin edges, including left edge of first bin and right edge of last bin.

backendstr, default None

Backend to use instead of the backend specified in the option plotting.backend. For instance, ‘matplotlib’. Alternatively, to specify the plotting.backend for the whole session, set pd.options.plotting.backend.

legendbool, default False

Whether to show the legend.

filename:

The name of the file where the plot will be saved.

Returns:

matplotlib.Axes

The histogram.

str

The name of the file where the histogram is saved.

Parameters:

• data (DataFrame)

• column (str)

• by_val (Any)

• grid (bool)

• xlabelsize (int | None)

• xrot (float | None)

• ylabelsize (int | None)

• yrot (float | None)

• axis (Any)

• sharex (bool)

• sharey (bool)

• figsize (tuple[float, float] | None)

• layout (tuple[int, int] | None)

• bins (int | Any)

• backend (str | None)

• legend (bool)

• filename (str)

• kwargs (Any)

Return type:

str | None

Notes

When zeros_are_disclosive is set to False in the config, empty bins (count == 0) are excluded from the disclosure threshold check. This avoids flagging histograms as disclosive solely because outliers in a wide-spread column produced empty tail bins.

logit(endog, exog, missing=None, check_rank=True)

Fits Logit model.

Parameters:

endogarray_like

A 1-d endogenous response variable. The dependent variable.

exogarray_like

A nobs x k array where nobs is the number of observations and k is the number of regressors. An intercept is not included by default and should be added by the user.

missingstr | None

Available options are ‘none’, ‘drop’, and ‘raise’. If ‘none’, no nan checking is done. If ‘drop’, any observations with nans are dropped. If ‘raise’, an error is raised. Default is ‘none’.

check_rankbool

Check exog rank to determine model degrees of freedom. Default is True. Setting to False reduces model initialization time when exog.shape[1] is large.

Returns:

BinaryResultsWrapper

Results.

Parameters:

• endog (ArrayLike)

• exog (ArrayLike)

• missing (str | None)

• check_rank (bool)

Return type:

BinaryResultsWrapper

logitr(formula, data, subset=None, drop_cols=None, *args, **kwargs)

Fits Logit model from a formula and dataframe.

Parameters:

formulastr or generic Formula object

The formula specifying the model.

dataarray_like

The data for the model. See Notes.

subsetarray_like

An array-like object of booleans, integers, or index values that indicate the subset of df to use in the model. Assumes df is a pandas.DataFrame.

drop_colsarray_like

Columns to drop from the design matrix. Cannot be used to drop terms involving categoricals.

*args

Additional positional argument that are passed to the model.

**kwargs

These are passed to the model with one exception. The eval_env keyword is passed to patsy. It can be either a patsy:patsy.EvalEnvironment object or an integer indicating the depth of the namespace to use. For example, the default eval_env=0 uses the calling namespace. If you wish to use a “clean” environment set eval_env=-1.

Returns:

RegressionResultsWrapper

Results.

Parameters:

• formula (str)

• data (Any)

• subset (Any)

• drop_cols (Any)

• args (Any)

• kwargs (Any)

Return type:

RegressionResultsWrapper

Notes

data must define __getitem__ with the keys in the formula terms args and kwargs are passed on to the model instantiation. E.g., a numpy structured or rec array, a dictionary, or a pandas DataFrame. Arguments are passed in the same order as statsmodels.

property mitigation: str

Return the current mitigation strategy.

ols(endog, exog=None, missing='none', hasconst=None, **kwargs)

Fits Ordinary Least Squares Regression.

Parameters:

endogarray_like

A 1-d endogenous response variable. The dependent variable.

exogarray_like

A nobs x k array where nobs is the number of observations and k is the number of regressors. An intercept is not included by default and should be added by the user.

missingstr

Available options are ‘none’, ‘drop’, and ‘raise’. If ‘none’, no nan checking is done. If ‘drop’, any observations with nans are dropped. If ‘raise’, an error is raised. Default is ‘none’.

hasconstNone or bool

Indicates whether the RHS includes a user-supplied constant. If True, a constant is not checked for and k_constant is set to 1 and all result statistics are calculated as if a constant is present. If False, a constant is not checked for and k_constant is set to 0.

**kwargs

Extra arguments that are used to set model properties when using the formula interface.

Returns:

RegressionResultsWrapper

Results.

Parameters:

• endog (ArrayLike)

• exog (ArrayLike | None)

• missing (str)

• hasconst (bool | None)

• kwargs (Any)

Return type:

RegressionResultsWrapper

olsr(formula, data, subset=None, drop_cols=None, *args, **kwargs)

Fits Ordinary Least Squares Regression from a formula and dataframe.

Parameters:

formulastr or generic Formula object

The formula specifying the model.

dataarray_like

The data for the model. See Notes.

subsetarray_like

An array-like object of booleans, integers, or index values that indicate the subset of df to use in the model. Assumes df is a pandas.DataFrame.

drop_colsarray_like

Columns to drop from the design matrix. Cannot be used to drop terms involving categoricals.

*args

Additional positional argument that are passed to the model.

**kwargs

These are passed to the model with one exception. The eval_env keyword is passed to patsy. It can be either a patsy:patsy.EvalEnvironment object or an integer indicating the depth of the namespace to use. For example, the default eval_env=0 uses the calling namespace. If you wish to use a “clean” environment set eval_env=-1.

Returns:

RegressionResultsWrapper

Results.

Parameters:

• formula (str)

• data (Any)

• subset (Any)

• drop_cols (Any)

• args (Any)

• kwargs (Any)

Return type:

RegressionResultsWrapper

Notes

data must define __getitem__ with the keys in the formula terms args and kwargs are passed on to the model instantiation. E.g., a numpy structured or rec array, a dictionary, or a pandas DataFrame. Arguments are passed in the same order as statsmodels.

pie(data, column, filename='pie.png', **kwargs)

Create a pie chart from a categorical column.

Per-category counts are computed using value_counts(). If any category has fewer observations than THRESHOLD, the output is marked as “fail” and the chart is suppressed when suppress=True. Otherwise the chart is produced and marked as “review”.

The chart is saved to the artifacts directory with a unique incrementing number appended to avoid overwriting existing files.

Parameters:

dataDataFrame

The pandas DataFrame holding the data.

columnstr

The column whose category proportions will be plotted.

filenamestr, default ‘pie.png’

The name of the file where the chart will be saved.

**kwargs

Additional keyword arguments forwarded to matplotlib.axes.Axes.pie().

Returns:

str

The path to the saved pie chart file.

Parameters:

• data (DataFrame)

• column (str)

• filename (str)

• kwargs (Any)

Return type:

str | None

pivot_table(data, values=None, index=None, columns=None, aggfunc='mean', fill_value=None, margins=False, dropna=True, margins_name='All', observed=False, sort=True, **kwargs)

Create a spreadsheet-style pivot table as a DataFrame.

The levels in the pivot table will be stored in MultiIndex objects (hierarchical indexes) on the index and columns of the result DataFrame.

To provide consistent behaviour with different aggregation functions, ‘empty’ rows or columns -i.e. that are all NaN or 0 (count,sum) are removed.

Parameters:

dataDataFrame

The DataFrame to operate on.

valuescolumn, optional

Column to aggregate, optional.

indexcolumn, Grouper, array, or list of the previous

If an array is passed, it must be the same length as the data. The list can contain any of the other types (except list). Keys to group by on the pivot table index. If an array is passed, it is being used as the same manner as column values.

columnscolumn, Grouper, array, or list of the previous

If an array is passed, it must be the same length as the data. The list can contain any of the other types (except list). Keys to group by on the pivot table column. If an array is passed, it is being used as the same manner as column values.

aggfuncstr | list[str], default ‘mean’

If list of strings passed, the resulting pivot table will have hierarchical columns whose top level are the function names (inferred from the function objects themselves).

fill_valuescalar, default None

Value to replace missing values with (in the resulting pivot table, after aggregation).

marginsbool, default False

Add all row / columns (e.g. for subtotal / grand totals).

dropnabool, default True

Do not include columns whose entries are all NaN.

margins_namestr, default ‘All’

Name of the row / column that will contain the totals when margins is True.

observedbool, default False

This only applies if any of the groupers are Categoricals. If True: only show observed values for categorical groupers. If False: show all values for categorical groupers.

sortbool, default True

Specifies if the result should be sorted.

**kwargsdict|None default =None

Optional keyword arguments to pass to aggfunc.

Returns:

DataFrame

Cross tabulation of the data.

Parameters:

• data (DataFrame)

• values (Any)

• index (Any)

• columns (Any)

• aggfunc (str | list[str])

• fill_value (Any)

• margins (bool)

• dropna (bool)

• margins_name (str)

• observed (bool)

• sort (bool)

• kwargs (dict)

Return type:

DataFrame

probit(endog, exog, missing=None, check_rank=True)

Fits Probit model.

Parameters:

endogarray_like

A 1-d endogenous response variable. The dependent variable.

exogarray_like

A nobs x k array where nobs is the number of observations and k is the number of regressors. An intercept is not included by default and should be added by the user.

missingstr | None

Available options are ‘none’, ‘drop’, and ‘raise’. If ‘none’, no nan checking is done. If ‘drop’, any observations with nans are dropped. If ‘raise’, an error is raised. Default is ‘none’.

check_rankbool

Check exog rank to determine model degrees of freedom. Default is True. Setting to False reduces model initialization time when exog.shape[1] is large.

Returns:

BinaryResultsWrapper

Results.

Parameters:

• endog (ArrayLike)

• exog (ArrayLike)

• missing (str | None)

• check_rank (bool)

Return type:

BinaryResultsWrapper

probitr(formula, data, subset=None, drop_cols=None, *args, **kwargs)

Fits Probit model from a formula and dataframe.

Parameters:

formulastr or generic Formula object

The formula specifying the model.

dataarray_like

The data for the model. See Notes.

subsetarray_like

An array-like object of booleans, integers, or index values that indicate the subset of df to use in the model. Assumes df is a pandas.DataFrame.

drop_colsarray_like

Columns to drop from the design matrix. Cannot be used to drop terms involving categoricals.

*args

Additional positional argument that are passed to the model.

**kwargs

These are passed to the model with one exception. The eval_env keyword is passed to patsy. It can be either a patsy:patsy.EvalEnvironment object or an integer indicating the depth of the namespace to use. For example, the default eval_env=0 uses the calling namespace. If you wish to use a “clean” environment set eval_env=-1.

Returns:

RegressionResultsWrapper

Results.

Parameters:

• formula (str)

• data (Any)

• subset (Any)

• drop_cols (Any)

• args (Any)

• kwargs (Any)

Return type:

RegressionResultsWrapper

Notes

data must define __getitem__ with the keys in the formula terms args and kwargs are passed on to the model instantiation. E.g., a numpy structured or rec array, a dictionary, or a pandas DataFrame. Arguments are passed in the same order as statsmodels.

show_fair_summaries()

Print IDs and FAIR summaries for all outputs in session.

Returns a formatted string containing metadata about each output, including dependent and independent variables tracked during analysis.

Returns:

str

Formatted summary of all outputs with their FAIR dictionaries.

Return type:

str

Examples

>>> import acro
>>> session = acro.ACRO()
>>> session.ols(y, X)
>>> print(session.show_fair_summaries())
output_0
dependent : income
independent : ['age', 'education']

property suppress: bool

Return True iff the active mitigation strategy is ‘suppress’.

surv_func(time, status, output, entry=None, title=None, freq_weights=None, exog=None, bw_factor=1.0, filename='kaplan-meier.png')

Estimate the survival function.

Parameters:

timearray_like

An array of times (censoring times or event times)

statusarray_like

Status at the event time, status==1 is the ‘event’ (e.g. death, failure), meaning the event occurs at the given value in time; status==0 indicates that censoring has occurred, meaning that the event occurs after the given value in time.

outputstr

A string determine the type of output. Available options are ‘table’, ‘plot’.

entryarray_like, optional An array of entry times for handling

left truncation (the subject is not in the risk set on or before the entry time)

titlestr

Optional title used for plots and summary output.

freq_weightsarray_like

Optional frequency weights

exogarray_like

Optional, if present used to account for violation of independent censoring.

bw_factorfloat

Band-width multiplier for kernel-based estimation. Only used if exog is provided.

filenamestr

The name of the file where the plot will be saved. Only used if the output is a plot.

Returns:

DataFrame

The survival table.

Parameters:

• time (Any)

• status (Any)

• output (str)

• entry (Any)

• title (Any)

• freq_weights (Any)

• exog (Any)

• bw_factor (float)

• filename (str)

Return type:

DataFrame | tuple[Any, str] | None

Ontology-Driven Checking Classes

The classes below form ACRO’s internal disclosure-checking pipeline. Most users will never instantiate these directly they are created and managed by the ACRO class. They are documented here for developers and TRE administrators.

SDCChecks

class acro.sdcchecks.SDCChecks(risk_appetite)

Bases: object

Implements range of SDC checks.

All the information is read from json files that are separately generated from the online ontology .ttl file (because they can’t be read from inside the TRE).

The constructor is fed the risk appetite for the session on creation.

All methods implementing checks have common format:

Parameters are

name:str

the ‘family name’ of the type of analysis determines what needs to be run

model: Any

can be statsmodel or the details (rows,columns,values) to create a table

Returns: tuple

string (status for that check) string: summary of that check Any: check details as

single values (e.g. Dof) or a mask showing cell-by cell results for a table

Methods

check_all_same(name, evidence, model)	Check whether all values in cells are the same.
check_linked_table(name, evidence, model)	Check for presence of linked tables.
check_min_threshold(name, evidence, model)	Check for small numbers of respondents in cells.
check_missing(name, evidence, model)	Check whether any cells have missing values.
check_model_dof(name, evidence, model)	Check model DOF.
check_nk_dominance(name, evidence, model)	Check for NK dominance within each cell.
check_ppercent_dominance(name, evidence, model)	Check for PQ dominance within each cell.
check_presence_of_zero(name, evidence, model)	Check for presence of cells with values zero.
check_required_zero(name, evidence, model)	Test whether a check for zeros is required (i.e., whether class disclosure is relevant for this dataset).
get_evidence_forall_analyses(analyses, model)	Collate the evidence needed to do SDC for all the analyses requested by a query.
get_sdctokens_for_analysis(statname)	Get list of sdc tokens to run for a given analysis.
manual_check(name, evidence, model)	Report that a manual check is needed.
run_checks_for_analysis(analysis_name, ...)	Given a set of evidence, run all the checks needed for a given type of analysis and report outcomes.

Parameters:

risk_appetite (dict)

__init__(risk_appetite)

Construct object and load knowledge from json files.

Parameters:

risk_appetitedict

Dictionary of risk appetite values

TODO

move risk_appetite from constructor to model class as it is in TableModelDetails class anyway

Parameters:

risk_appetite (dict)

Return type:

None

get_sdctokens_for_analysis(statname)

Get list of sdc tokens to run for a given analysis.

Parameters:

statnamestr

Analysis prefix label for a statbarnsdc analysis type.

Returns:

dict

SDC terms to be saved.

Parameters:

statname (str)

Return type:

dict

get_evidence_forall_analyses(analyses, model)

Collate the evidence needed to do SDC for all the analyses requested by a query.

Parameters:

• analyses (list[str])

• model (Any)

Return type:

SDCEvidence

run_checks_for_analysis(analysis_name, evidence, model)

Given a set of evidence, run all the checks needed for a given type of analysis and report outcomes.

Parameters:

analysis_namestr

name of the type of analysis should match a type of analysis from statbarnsdc ontology

evidenceSDCEvidence

evidence collected in previous stage

modelAny

either the trained model (for regression etc) or sufficient details to recreate a table TODO restrict to either TableModelDetails (from table_utils) or appropriate statsmodels classes

Returns:

overall_statusstr

‘fail’, ‘review’, or ‘pass’

summariesstring

concatenation of summaries for each check run

outcomesdict[str,Any]

dictionary of outcomes with keys for the check and values which might be:

numbers (e.g. Dof), or masks (Dataframes),

depending on the check and the type of model e.g. regression vs table

sdc_dictdetails of the sdc processes

dict with one key (for now) “check_status” where the value is itself a dict of checkname (str): status (str)

Parameters:

• analysis_name (str)

• evidence (SDCEvidence)

• model (Any)

Return type:

ChecksResults

check_model_dof(name, evidence, model)

Check model DOF.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

model

A statsmodels model.

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

float

the residual degrees of freedom.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (Any)

Return type:

tuple[str, str, int]

check_all_same(name, evidence, model)

Check whether all values in cells are the same.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_missing(name, evidence, model)

Check whether any cells have missing values.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_min_threshold(name, evidence, model)

Check for small numbers of respondents in cells.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modeldict

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

manual_check(name, evidence, model)

Report that a manual check is needed.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_nk_dominance(name, evidence, model)

Check for NK dominance within each cell.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_ppercent_dominance(name, evidence, model)

Check for PQ dominance within each cell.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_linked_table(name, evidence, model)

Check for presence of linked tables.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_required_zero(name, evidence, model)

Test whether a check for zeros is required (i.e., whether class disclosure is relevant for this dataset).

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

check_presence_of_zero(name, evidence, model)

Check for presence of cells with values zero.

Parameters:

namestr

The name of the model.

evidenceSDCEvidence

The collected evidence object.

modelTableModelDetails

definition of a table

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the check.

pandas DataFrame

binary mask with same config as the underlying table.

Parameters:

• name (str)

• evidence (SDCEvidence)

• model (TableModelDetails)

Return type:

tuple[str, str, DataFrame]

SDCEvidence

class acro.sdcchecks.SDCEvidence(dof=None, interim_tables=<factory>, other_evidence=<factory>, variable_type_dict=<factory>)

Bases: object

Class for evidence needed to run risk assessment checks for an analysis.

Attributes:

dof

Parameters:

• dof (Any)

• interim_tables (dict[str, DataFrame])

• other_evidence (dict[str, Any])

• variable_type_dict (dict[str, Any])

Methods

populate_dof(model)	Populate dof for any sort of model.
populate_from_list(evidence_needed, model)	Populate dataclass for a given model-analyses combination.

dof: Any = None

interim_tables: dict[str, DataFrame]

other_evidence: dict[str, Any]

variable_type_dict: dict[str, Any]

populate_dof(model)

Populate dof for any sort of model.

Parameters:

model (Any)

Return type:

None

populate_from_list(evidence_needed, model)

Populate dataclass for a given model-analyses combination.

Parameters:

• evidence_needed (set)

• model (Any)

Return type:

None

__init__(dof=None, interim_tables=<factory>, other_evidence=<factory>, variable_type_dict=<factory>)

Parameters:

• dof (Any)

• interim_tables (dict[str, DataFrame])

• other_evidence (dict[str, Any])

• variable_type_dict (dict[str, Any])

Return type:

None

ChecksResults

class acro.sdcchecks.ChecksResults(overall_status, summaries, outcomes, fair_dict)

Bases: object

Class holding results of running checks for an analysis.

overall_statusstr

‘fail’, ‘review’, or ‘pass’

summariesstring

concatenation of summaries for each check run.

outcomesdict[str,Any]

dictionary of outcomes with keys for the check and values which might be: numbers (e.g. Dof), or masks (Dataframes), depending on the check and the type of model e.g. regression vs table

fair_dict: details of the sdc processes

dict with one key (for now) `check_status where the value is itself a dict

Parameters:

• overall_status (str)

• summaries (str)

• outcomes (dict[str, Any])

• fair_dict (dict)

overall_status: str

summaries: str

outcomes: dict[str, Any]

fair_dict: dict

__init__(overall_status, summaries, outcomes, fair_dict)

Parameters:

• overall_status (str)

• summaries (str)

• outcomes (dict[str, Any])

• fair_dict (dict)

Return type:

None

ManyChecksResults

class acro.sdcchecks.ManyChecksResults(allchecksresults=<factory>)

Bases: object

Class for running checks on multiple analysis.

Methods

get_overall_fair()	Get overall FAIR analysis for set of analyses.
get_overall_status()	Get overall risk status for set of analyses.
get_overall_summary()	Get overall summary from multiple statistics.
get_table_sdc()	Return the SDC dictionary for a table using the suppression masks.

Parameters:

allchecksresults (dict[str, ChecksResults])

allchecksresults: dict[str, ChecksResults]

get_overall_summary()

Get overall summary from multiple statistics.

Returns:

str

Summary of checks, excluding those that pass.

Return type:

str

get_overall_status()

Get overall risk status for set of analyses.

Return type:

str

get_overall_fair()

Get overall FAIR analysis for set of analyses.

Return type:

dict[str, dict]

get_table_sdc()

Return the SDC dictionary for a table using the suppression masks.

Return type:

dict[str, Any]

__init__(allchecksresults=<factory>)

Parameters:

allchecksresults (dict[str, ChecksResults])

Return type:

None

TableModelDetails

class acro.tablemodeldetails.TableModelDetails(index=None, columns=None, values=None, command=None, thekwargs=None, risk_appetite=None)

Bases: object

Class for details needed to create a table.

FOR NOW this will effectively hold copies of all the data needed

Methods

get_allfalse_table()	Create a data frame filled with false of same size as underlying table.
get_count_table()	Make count table as specified by model.
get_crosstab_args()	Get arguments for a call to crosstab.
get_crosstab_kwargs()	Get kwargs in format for a crosstab call.
get_dimension_names()	Names from joint list of rows and columns.
get_pivot_data()	Extract data relevant to pivot_table into new DataFrame.
get_table_newagg(newaggfunc)	Make table as specified by model but with new agg func.
get_variable_type_dict()	Get dict listing dependent and independent variables from metadata catalogue.
get_zeros_table()	Create a data frame filled with zeros of same size as underlying table.

Parameters:

• index (list | None)

• columns (list | None)

• values (pd.Series | None)

• command (str)

• thekwargs (dict | None)

• risk_appetite (dict)

variable_data: dict = {}

df_resid: int = 0

__init__(index=None, columns=None, values=None, command=None, thekwargs=None, risk_appetite=None)

Construct the TableModelDescriptor for a table/ array type analysis.

Parameters:

indexlist

index series names

columnslist

columns series names

valuespd.Series

the values series (measure) for the table, if any

thekwargsdict

specifiers for table and command

risk_appetitedict

statement of TREs risk appetite

commandstr

“crosstab” or “pivot_table”

Parameters:

• index (list | None)

• columns (list | None)

• values (Series | None)

• command (str | None)

• thekwargs (dict | None)

• risk_appetite (dict | None)

Return type:

None

kwargs: dict = {}

risk_appetite: dict = {}

command: str = ''

model_type: str = 'table'

get_pivot_data()

Extract data relevant to pivot_table into new DataFrame.

Assumes preprocessing has happened, so index and columns in model should both have been converted into lists of Series.

Creates dummy column if there is only one column

Returns:

DataFrame

DataFrame containing copies of pandas series needed to calculate the pivot_table.

Return type:

DataFrame

get_crosstab_args()

Get arguments for a call to crosstab.

create dummy column if needed

Return type:

tuple

get_crosstab_kwargs()

Get kwargs in format for a crosstab call.

Return type:

dict[str, Any]

get_dimension_names()

Names from joint list of rows and columns.

uncomment to provide dummy names if needed - but this should have been done earlier

Return type:

list[str]

get_variable_type_dict()

Get dict listing dependent and independent variables from metadata catalogue.

Returns:

dict

holding name of dependent variable and list of independent (exogenous) variables

Return type:

dict[str, Any]

get_count_table()

Make count table as specified by model.

Return type:

DataFrame

get_table_newagg(newaggfunc)

Make table as specified by model but with new agg func.

Parameters:

newaggfunc (Callable)

Return type:

DataFrame

get_zeros_table()

Create a data frame filled with zeros of same size as underlying table.

Return type:

DataFrame

get_allfalse_table()

Create a data frame filled with false of same size as underlying table.

Return type:

DataFrame

Record Management

Record Classes

class acro.record.Records(blocked_extensions=None)

Bases: object

Stores data related to a collection of output records.

Methods

add([status, output_type, properties, sdc, ...])	Add an output to the results.
add_comments(output, comment)	Add a comment to an output.
add_custom(filename[, comment])	Add an unsupported output to the results dictionary.
add_exception(output, reason)	Add an exception request to an output.
finalise(path, ext[, interactive])	Create a results file for checking.
finalise_evidence(path[, evidence_store])	Serialise federated evidence to CSV files and return the manifest dict.
finalise_excel(path)	Write outputs to an excel spreadsheet.
finalise_json(path)	Write outputs to a JSON file.
get(key)	Return a specified output from the results.
get_index(index)	Return the output at the specified position.
get_keys()	Return the list of available output keys.
print()	Print the current results.
remove(key)	Remove an output from the results.
rename(old, new)	Rename an output.
validate_outputs()	Prompt researcher to complete any required fields.
write_checksums(path)	Write checksums for each file to checksums folder.

Parameters:

blocked_extensions (list[str] | None)

__init__(blocked_extensions=None)

Construct a new object for storing multiple records.

Parameters:

blocked_extensions (list[str] | None)

Return type:

None

add(status='', output_type='', properties=None, sdc=None, fair=None, command='', summary='', outcome=None, output=None, comments=None)

Add an output to the results.

Parameters:

statusstr

SDC status: {“pass”, “fail”, “review”}

output_typestr

Type of output, e.g., “regression”

propertiesdict

Dictionary containing structured output data.

sdcdict

Dictionary containing SDC results.

fairdict

Dictionary containing FAIR description of analysis

commandstr

String representation of the operation performed.

summarystr

String summarising the ACRO checks.

outcomeDataFrame

DataFrame describing the details of ACRO checks.

outputlist[str | list[DataFrame]

List of output DataFrames.

commentslist[str] | None, default None

List of strings entered by the user to add comments to the output.

Parameters:

• status (str)

• output_type (str)

• properties (dict | None)

• sdc (dict | None)

• fair (dict | None)

• command (str)

• summary (str)

• outcome (DataFrame | None)

• output (list[str] | list[DataFrame] | None)

• comments (list[str] | None)

Return type:

None

remove(key)

Remove an output from the results.

Parameters:

keystr

Key specifying which output to remove, e.g., ‘output_0’.

Parameters:

key (str)

Return type:

None

get(key)

Return a specified output from the results.

Parameters:

keystr

Key specifying which output to return, e.g., ‘output_0’.

Returns:

Record

The requested output.

Parameters:

key (str)

Return type:

Record

get_keys()

Return the list of available output keys.

Returns:

list[str]

List of output names.

Return type:

list[str]

get_index(index)

Return the output at the specified position.

Parameters:

indexint

Position of the output to return.

Returns:

Record

The requested output.

Parameters:

index (int)

Return type:

Record

add_custom(filename, comment=None)

Add an unsupported output to the results dictionary.

Parameters:

filenamestr

The name of the file that will be added to the list of the outputs.

commentstr | None, default None

An optional comment.

Returns:

bool

False if the file extension is blocked, True otherwise.

Parameters:

• filename (str)

• comment (str | None)

Return type:

bool

rename(old, new)

Rename an output.

Parameters:

oldstr

The old name of the output.

newstr

The new name of the output.

Parameters:

• old (str)

• new (str)

Return type:

None

add_comments(output, comment)

Add a comment to an output.

Parameters:

outputstr

The name of the output.

commentstr

The comment.

Parameters:

• output (str)

• comment (str)

Return type:

None

add_exception(output, reason)

Add an exception request to an output.

Parameters:

outputstr

The name of the output.

reasonstr

The reason the output should be released.

Parameters:

• output (str)

• reason (str)

Return type:

None

print()

Print the current results.

Returns:

str

String representation of all outputs.

Return type:

str

validate_outputs()

Prompt researcher to complete any required fields.

Return type:

None

finalise(path, ext, interactive=False)

Create a results file for checking.

Parameters:

pathstr

Name of a folder to save outputs.

extstr

Extension of the results file. Valid extensions: {json, xlsx}.

interactiveBool

Whether to prompt the user to request exceptions for failing outputs.

Parameters:

• path (str)

• ext (str)

• interactive (bool)

Return type:

None

finalise_json(path)

Write outputs to a JSON file.

Parameters:

pathstr

Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

finalise_excel(path)

Write outputs to an excel spreadsheet.

Parameters:

pathstr

Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

finalise_evidence(path, evidence_store=None)

Serialise federated evidence to CSV files and return the manifest dict.

Each interim table (DataFrame) is saved as a separate CSV file in path. The returned dictionary is suitable for writing to evidence.json.

Parameters:

pathstr

Directory where CSV files and evidence.json will be written.

evidence_storedict, optional

The evidence dictionary to serialise. When None an empty dict is used, producing an empty manifest. Callers should pass getattr(self_acro, "_federated_evidence", {}).

Returns:

dict

Manifest describing every output’s evidence and the CSV filenames.

Parameters:

• path (str)

• evidence_store (dict | None)

Return type:

dict

write_checksums(path)

Write checksums for each file to checksums folder.

Parameters:

pathstr

Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

Record Module

Records

ACRO: Output storage and serialization.

acro.record.load_outcome(outcome)

Return a DataFrame from an outcome dictionary.

Parameters:

outcomedict

The outcome to load as a DataFrame.

Parameters:

outcome (dict[str, Any])

Return type:

DataFrame

acro.record.load_output(path, output)

Return a loaded output.

Parameters:

pathstr

The path to the output folder (with results.json).

outputlist[str]

The output to load.

Returns:

list[str] | list[DataFrame]

The loaded output field.

Parameters:

• path (str)

• output (list[str])

Return type:

list[str] | list[DataFrame]

class acro.record.Record(uid, status, output_type, properties, sdc, fair, command, summary, outcome, output, comments=None)

Stores data related to a single output record.

Attributes:

uidstr

Unique identifier.

statusstr

SDC status: {“pass”, “fail”, “review”}

output_typestr

Type of output, e.g., “regression”

propertiesdict

Dictionary containing structured output data.

sdcdict

Dictionary containing SDC results.

fairdict

Dictionary containing FAIR description of SDC process

commandstr

String representation of the operation performed.

summarystr

String summarising the ACRO checks.

outcomeDataFrame

DataFrame describing the details of ACRO checks.

outputAny

List of output DataFrames.

commentslist[str]

List of strings entered by the user to add comments to the output.

exceptionstr

Description of why an exception to fail/review should be granted.

timestampstr

Time the record was created in ISO format.

Parameters:

• uid (str)

• status (str)

• output_type (str)

• properties (dict)

• sdc (dict)

• fair (dict)

• command (str)

• summary (str)

• outcome (DataFrame)

• output (list[str] | list[DataFrame])

• comments (list[str] | None)

Methods

serialize_output([path])

Serialize outputs.

__init__(uid, status, output_type, properties, sdc, fair, command, summary, outcome, output, comments=None)

Construct a new output record.

Parameters:

uidstr

Unique identifier.

statusstr

SDC status: {“pass”, “fail”, “review”}

output_typestr

Type of output, e.g., “regression”

propertiesdict

Dictionary containing structured output data.

sdcdict

Dictionary containing SDC results.

fairdict

Dictionary containing FAIR description of SDC process

commandstr

String representation of the operation performed.

summarystr

String summarising the ACRO checks.

outcomeDataFrame

DataFrame describing the details of ACRO checks.

outputlist[str] | list[DataFrame]

List of output DataFrames.

commentslist[str] | None, default None

List of strings entered by the user to add comments to the output.

Parameters:

• uid (str)

• status (str)

• output_type (str)

• properties (dict)

• sdc (dict)

• fair (dict)

• command (str)

• summary (str)

• outcome (DataFrame)

• output (list[str] | list[DataFrame])

• comments (list[str] | None)

Return type:

None

serialize_output(path='outputs')

Serialize outputs.

Parameters:

pathstr, default ‘outputs’

Name of the folder that outputs are to be written.

Returns:

list[str]

List of filepaths of the written outputs.

Parameters:

path (str)

Return type:

list[str]

class acro.record.Records(blocked_extensions=None)

Stores data related to a collection of output records.

Methods

add([status, output_type, properties, sdc, ...])	Add an output to the results.
add_comments(output, comment)	Add a comment to an output.
add_custom(filename[, comment])	Add an unsupported output to the results dictionary.
add_exception(output, reason)	Add an exception request to an output.
finalise(path, ext[, interactive])	Create a results file for checking.
finalise_evidence(path[, evidence_store])	Serialise federated evidence to CSV files and return the manifest dict.
finalise_excel(path)	Write outputs to an excel spreadsheet.
finalise_json(path)	Write outputs to a JSON file.
get(key)	Return a specified output from the results.
get_index(index)	Return the output at the specified position.
get_keys()	Return the list of available output keys.
print()	Print the current results.
remove(key)	Remove an output from the results.
rename(old, new)	Rename an output.
validate_outputs()	Prompt researcher to complete any required fields.
write_checksums(path)	Write checksums for each file to checksums folder.

Parameters:

blocked_extensions (list[str] | None)

__init__(blocked_extensions=None)

Construct a new object for storing multiple records.

Parameters:

blocked_extensions (list[str] | None)

Return type:

None

add(status='', output_type='', properties=None, sdc=None, fair=None, command='', summary='', outcome=None, output=None, comments=None)

Add an output to the results.

Parameters:

statusstr

SDC status: {“pass”, “fail”, “review”}

output_typestr

Type of output, e.g., “regression”

propertiesdict

Dictionary containing structured output data.

sdcdict

Dictionary containing SDC results.

fairdict

Dictionary containing FAIR description of analysis

commandstr

String representation of the operation performed.

summarystr

String summarising the ACRO checks.

outcomeDataFrame

DataFrame describing the details of ACRO checks.

outputlist[str | list[DataFrame]

List of output DataFrames.

commentslist[str] | None, default None

List of strings entered by the user to add comments to the output.

Parameters:

• status (str)

• output_type (str)

• properties (dict | None)

• sdc (dict | None)

• fair (dict | None)

• command (str)

• summary (str)

• outcome (DataFrame | None)

• output (list[str] | list[DataFrame] | None)

• comments (list[str] | None)

Return type:

None

remove(key)

Remove an output from the results.

Parameters:

keystr

Key specifying which output to remove, e.g., ‘output_0’.

Parameters:

key (str)

Return type:

None

get(key)

Return a specified output from the results.

Parameters:

keystr

Key specifying which output to return, e.g., ‘output_0’.

Returns:

Record

The requested output.

Parameters:

key (str)

Return type:

Record

get_keys()

Return the list of available output keys.

Returns:

list[str]

List of output names.

Return type:

list[str]

get_index(index)

Return the output at the specified position.

Parameters:

indexint

Position of the output to return.

Returns:

Record

The requested output.

Parameters:

index (int)

Return type:

Record

add_custom(filename, comment=None)

Add an unsupported output to the results dictionary.

Parameters:

filenamestr

The name of the file that will be added to the list of the outputs.

commentstr | None, default None

An optional comment.

Returns:

bool

False if the file extension is blocked, True otherwise.

Parameters:

• filename (str)

• comment (str | None)

Return type:

bool

rename(old, new)

Rename an output.

Parameters:

oldstr

The old name of the output.

newstr

The new name of the output.

Parameters:

• old (str)

• new (str)

Return type:

None

add_comments(output, comment)

Add a comment to an output.

Parameters:

outputstr

The name of the output.

commentstr

The comment.

Parameters:

• output (str)

• comment (str)

Return type:

None

add_exception(output, reason)

Add an exception request to an output.

Parameters:

outputstr

The name of the output.

reasonstr

The reason the output should be released.

Parameters:

• output (str)

• reason (str)

Return type:

None

print()

Print the current results.

Returns:

str

String representation of all outputs.

Return type:

str

validate_outputs()

Prompt researcher to complete any required fields.

Return type:

None

finalise(path, ext, interactive=False)

Create a results file for checking.

Parameters:

pathstr

Name of a folder to save outputs.

extstr

Extension of the results file. Valid extensions: {json, xlsx}.

interactiveBool

Whether to prompt the user to request exceptions for failing outputs.

Parameters:

• path (str)

• ext (str)

• interactive (bool)

Return type:

None

finalise_json(path)

Write outputs to a JSON file.

Parameters:

pathstr

Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

finalise_excel(path)

Write outputs to an excel spreadsheet.

Parameters:

pathstr

Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

finalise_evidence(path, evidence_store=None)

Serialise federated evidence to CSV files and return the manifest dict.

Each interim table (DataFrame) is saved as a separate CSV file in path. The returned dictionary is suitable for writing to evidence.json.

Parameters:

pathstr

Directory where CSV files and evidence.json will be written.

evidence_storedict, optional

The evidence dictionary to serialise. When None an empty dict is used, producing an empty manifest. Callers should pass getattr(self_acro, "_federated_evidence", {}).

Returns:

dict

Manifest describing every output’s evidence and the CSV filenames.

Parameters:

• path (str)

• evidence_store (dict | None)

Return type:

dict

write_checksums(path)

Write checksums for each file to checksums folder.

Parameters:

pathstr

Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

acro.record.load_records(path)

Load outputs from a JSON file.

Parameters:

pathstr

Name of an output folder containing results.json.

Returns:

Records

The loaded records.

Parameters:

path (str)

Return type:

Records

Utilities

Helper Functions

ACRO: Utility Functions.

acro.utils.is_blocked_extension(filename, blocked_extensions)

Return True and log a warning if the file’s extension is blocked.

Parameters:

• filename (str)

• blocked_extensions (list[str])

Return type:

bool

acro.utils.get_command(default, stack_list)

Return the calling source line as a string.

Parameters:

defaultstr

Default string to return if unable to extract the stack.

stack_listlist[tuple]

A list of frame records for the caller’s stack. The first entry in the returned list represents the caller; the last entry represents the outermost call on the stack.

Returns:

str

The calling source line.

Parameters:

• default (str)

• stack_list (list[FrameInfo])

Return type:

str

acro.utils.prettify_table_string(table, separator=None)

Add delimiters to table.to_string() to improve readability for onscreen display.

Splits fields on whitespace unless an optional separator is provided e.g. ‘,’ for csv.

Parameters:

• table (DataFrame)

• separator (str | None)

Return type:

str

acro.utils.get_unique_artefact_filename(filename)

Return a unique filename from a proposed string.

Parameters:

filename (str)

Return type:

str

acro.utils.get_catdtype(series)

Get info for pandas datatype to convert series to CategoricalDtype.

Parameters:

series (Series)

Return type:

CategoricalDtype

Table Utilities

ACRO Table-Specific Utility Functions.

acro.table_utils.axis_to_list(axis, prefix='row')

Translate axis into standard format.

Convert variables describing an axis (row/column) into a list to simplify code. Wraps input inside a list if it is a single series or leaves it unchanged if it is already a list of series.

Parameters:

axisSeries or list of Series or ArrayLike

Pandas series or list of series describing an axis.

Returns:

list

List of Series objects.

Parameters:

• axis (Any)

• prefix (str)

Return type:

list[Series]

acro.table_utils.list_to_list_of_series(mylist)

Convert list of objects to list of pandas series.

Pandas crosstab supports ArrayLike objects for crosstabs etc but internally we assume lists of pd.Series.

Parameters:

mylistlist(Any)

list to be converted

Returns:

list of pandas Series

Parameters:

mylist (list)

Return type:

list[Series]

acro.table_utils.drop_duplicate_columns(outcome)

Remove duplicate columns arising from multiple aggregation functions.

Parameters:

outcome (DataFrame)

Return type:

DataFrame

acro.table_utils.collate_risk_assessments(table, allcheckresults)

Collate the Risk Assessment for a table.

Parameters:

tableDataFrame

Table to be risk assessed.

allcheckresultsdict[str, ChecksResults]

Dictionary of dataclasses specifying individual risk assessments results.

Returns:

DataFrame

Table with collated outcomes of suppression checks.

Parameters:

• table (DataFrame)

• allcheckresults (dict[str, ChecksResults])

Return type:

DataFrame

acro.table_utils.get_analysis_summary(sdc)

Return the status and summary of the suppression masks.

Parameters:

sdcdict

Properties of the SDC checks for an analysis.

Returns:

str

Status: {“review”, “fail”, “pass”}.

str

Summary of the suppression masks.

Parameters:

sdc (dict[str, Any])

Return type:

tuple[str, str]

acro.table_utils.get_redacted_table(model, collated_assessment)

Redact table as needed then rereun the table query.

Parameters:

• model (TableModelDetails)

• collated_assessment (DataFrame)

Return type:

DataFrame

acro.table_utils.get_redacted_pivottable(model, collated_assessment)

Redact table as needed then rereun the table query.

Parameters:

• model (TableModelDetails)

• collated_assessment (DataFrame)

Return type:

DataFrame

acro.table_utils.add_backticks(name)

Add backticks to a name if it contains spaces and doesn’t have them.

Parameters:

namestr

The name to add backticks to.

Returns:

str

The name with backticks if needed.

Parameters:

name (str)

Return type:

str

acro.table_utils.get_relevant_dataframe(model)

Extract copy of data relevant to crosstab into new DataFrame.

Assumes preprocessing has happened, so index and columns in model should both have been converted into lists of Series.

Parameters:

modelTableModelDetails

The table model details object containing index, columns, and values.

Returns:

DataFrame

DataFrame containing copies of pandas series needed to calculate the crosstab.

Parameters:

model (TableModelDetails)

Return type:

DataFrame

acro.table_utils.translate_args_to_newdf(arguments, redacted_data)

Translate arguments or keys from one data frame to another.

Parameters:

argumentslist

list of positional arguments to be translated to a different dataframe

redacted_dataDataframe

the name of the ‘host’ dataframe

Returns:

list

arguments translate on to columns with the same name in the host DataFrame

Parameters:

• arguments (tuple)

• redacted_data (DataFrame)

Return type:

list

acro.table_utils.get_queries_from_collated_risk(collated_risk, aggfunc)

Return a list of the boolean conditions for each true (disclosive) cell in the suppression masks.

Parameters:

collated_riskDataFrame

DataFrame with collated risk assessment outcomes per cell.

masksdict[str, DataFrame]

Dictionary of tables specifying suppression masks for application.

aggfuncstr | None

The aggregation function

Returns:

str

The boolean conditions for each true (disclosive) cell in the suppression masks.

Parameters:

• collated_risk (DataFrame)

• aggfunc (str | None)

Return type:

list[str]

acro.table_utils.get_redacted_data(data, queries, dimensions)

Apply set of queries to remove sensitive data from DataFrame.

Parameters:

datapandas DataFrame

the raw data

querieslist[str]

a set of queries that define the data in cells marked as being disclosive

dimensionslist[str]

the names of the dimensional variablss - these are the categorical entities in the queries

Returns:

DataFrame

the data after the sensitive data has been removed

Parameters:

• data (DataFrame)

• queries (list[str])

• dimensions (list[str])

Return type:

DataFrame

acro.table_utils.get_debugging_table_analysis(allchecksresults)

Get string of status/summary debugging info.

Parameters:

allchecksresults (dict[str, ChecksResults])

Return type:

str

acro.table_utils.aggfunc_to_strings(aggfunc)

Turn aggfunc into list of strings.

Parameters:

aggfunc (Any)

Return type:

list[str]

acro.table_utils.round_table(table, base)

Round numeric cells to the nearest multiple of base (NaNs preserved).

Parameters:

• table (DataFrame)

• base (int | None)

Return type:

DataFrame

acro.table_utils.append_rounded_margins(rounded_table, aggfunc, margins_name, base)

Append row/column/grand-total margins to a pre-rounded table.

Once cells have been rounded, margins are computed by aggregating the rounded cells (so rounded inner cells add up to the displayed totals) and then rounded again to base so the whole output respects the rounding base.

Conceptually this is the same as the “synthetic-data” approach Jim described - exploding the rounded table into one record per cell and re-running pd.crosstab(margins=True) - but implemented directly on the rounded DataFrame to keep it simple. We currently support single- level row and column indices; multi-level or list-of-aggfunc tables fall back to returning the table without margins.

Parameters:

• rounded_table (DataFrame)

• aggfunc (Any)

• margins_name (str)

• base (int)

Return type:

DataFrame

Function Reference by Category

Output Management

• finalise() Prepare outputs for review

• remove_output() Remove specific output

• print_outputs() Display current outputs

• custom_output() Add custom output

• rename_output() Rename an output

• add_comments() Add comments to output

• add_exception() Add exception request

Mitigation Control

• enable_suppression() Switch to suppression mode

• disable_suppression() Disable suppression

• enable_rounding(base) Switch to rounding mode

• disable_rounding() Disable rounding

Common Parameters

Many ACRO methods share common parameters:

Parameter	Type	Description
suppress	bool	Whether to suppress potentially disclosive outputs automatically.
federated	bool	Whether to run in federated mode (evidence sent to a trusted aggregator).
show_suppressed	bool	Deprecated: retained for backward compatibility; it has no effect.
		The following parameters should never be manipulated in code. They should only be set via the configuration file provided by the TRE as discussed below.
safe_threshold	int	Minimum cell count threshold (TRE-controlled; set in YAML config).
safe_dof_threshold	int	Minimum degrees of freedom for statistical models.
safe_nk_n	int	n in the NK dominance rule.
safe_nk_k	float	k (proportion) in the NK dominance rule.
safe_pratio_p	float	P-ratio threshold for dominance checking.

Configuration

ACRO uses YAML configuration files to set safety parameters.

Safety parameters are read from the YAML config at initialisation; pass a different file with the config argument to override defaults for a TRE or dataset (for example acro = acro.ACRO(config="myriskappetite.yml")).

# Initialise with default confi
acro = acro.ACRO()

# Initialise with suppress mode on
acro = acro.ACRO(suppress=True)

# Initialise with a custom config file
acro = acro.ACRO(config="custom.yaml")

Custom Configuration

Create a custom YAML file for your TRE:

# custom.yaml
safe_threshold: 10
safe_dof_threshold: 10
safe_nk_n: 2
safe_nk_k: 0.9
safe_pratio_p: 0.1
check_missing_values: false
zeros_are_disclosive: true
safe_round_base: 5
federated: false
blocked_extensions:
  - .svg
  - .gph

Version Information

import acro
from acro.version import __version__
print(__version__)

See Also

• Architecture Reference Detailed technical architecture reference

• Examples Usage examples and tutorials

• Installation Installation instructions

• Welcome to ACRO Getting started guide