Records Class#

The record module manages the session’s output store. It contains two classes (Record and Records) and a set of module-level helper functions.

Records Class#

Records is the session-level container. Every ACRO instance holds one Records object at acro_session.results.

class acro.record.Records(blocked_extensions=None)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Return the list of available output keys.

Returns:

list[str]: List of output names.

Return type:

list[str]

get_index(index)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Print the current results.

Returns:

str: String representation of all outputs.

Return type:

str

validate_outputs()[source]

Prompt researcher to complete any required fields.

Return type:: None

finalise(path, ext, interactive=False)[source]

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)[source]

Write outputs to a JSON file.

Parameters:

pathstr: Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

finalise_excel(path)[source]

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)[source]

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)[source]

Write checksums for each file to checksums folder.

Parameters:

pathstr: Name of a folder to save outputs.

Parameters:

path (str)

Return type:

None

Note

New in v1.0.0+: Federated evidence serialisation: Records.finalise_evidence() is called by acro.ACRO.finalise() when running in federated mode (ACRO(federated=True)). It serialises each output’s SDCEvidence interim tables to CSV files and writes an evidence.json manifest so a trusted aggregator can run the SDC checks centrally.

Record Class#

Record represents a single output item stored in the session.

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

Bases: object

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)[source]

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')[source]

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]

Module-Level Functions#

acro.record.load_records(path)[source]#

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

acro.record.load_output(path, output)[source]#

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]

acro.record.load_outcome(outcome)[source]#

Return a DataFrame from an outcome dictionary.

Parameters:

outcomedict: The outcome to load as a DataFrame.

Parameters:

outcome (dict[str, Any])

Return type:

DataFrame