Results and Logs

run() gives a dictionary: one pandas.Series of features for each configuration. This page makes tables from the results, saves them, and describes the feature catalog and the processing log.

The Result of a Run

results = pipeline.run("ct.nii.gz", "lesion.nii.gz", config_names=["ct_fbs_25"])
features = results["ct_fbs_25"]           # a pandas Series
print(features["mean_intensity_Q4LE"])     # the feature name, then its IBSI code
print(len(features))                       # the number of features

A feature key is the feature name and its IBSI code, for example mean_intensity_Q4LE. The IBSI code identifies the feature in the IBSI reference manual. Each configuration gives all its feature names, also when a step fails (see Result Guarantees).

Tables: format_results

format_results() makes a table row (wide format) or a list of feature rows (long format) from the results of one run.

from pictologics import format_results

row = format_results(results, fmt="wide", meta={"subject_id": "p001"})
# {"subject_id": "p001", "ct_fbs_25__mean_intensity_Q4LE": 41.2, ...}

table = format_results(results, fmt="long", meta={"subject_id": "p001"}, output_type="pandas")
# columns: subject_id, config, feature_key, value

The long format suits many configurations and statistics programs such as R. The wide format gives one row for each case or ROI.

Files: save_results

save_results() writes results to a file. It takes a dict, a list of dicts, a DataFrame, a list of DataFrames, a JSON text or a list of JSON texts.

from pictologics import save_results

rows = []
for case in cases:
    results = pipeline.run(case["image"], case["mask"], config_names=["ct_fbs_25"])
    rows.append(format_results(results, meta={"subject_id": case["subject_id"]}))
    pipeline.clear_log()  # the log grows with each run
save_results(rows, "study/features.csv")

• File type: the extension sets it: .csv, .tsv or .json (no extension gives CSV). Another extension raises a ValueError. file_format="tsv" sets the type for any name.
• Folders: a missing folder is made.
• JSON: NaN and infinite values become null, so every JSON reader accepts the file.
• Columns: the rows merge by column name. When the rows have other columns (for example cases with other configurations), the table has all columns, and the cells without a value are empty.
• Many cases: run_batch gives the table of a whole study, and writes each case to its own file while it runs.

The Feature Catalog: describe_features

describe_features() gives one row for each feature of each configuration, before you run it. Save it with your results as a data dictionary.

catalog = pipeline.describe_features()
catalog.to_csv("study/feature_catalog.csv", index=False)
texture = catalog[(catalog["family_group"] == "Texture") & (catalog["discretisation_method"] == "FBN")]

• A step parameter column holds the parameters of the configuration only. A summary column such as interpolation or discretisation_method also gives the default when the step leaves out the parameter.
• A step that repeats gets a JSON list in its ..._params cell, with one entry for each time, with its step_index (from 1).

The Processing Log

The pipeline keeps a log entry for each configuration that run() or run_rois() runs. run_batch() writes the log of each case into its result file.

for entry in pipeline.get_log():           # a copy of the entries
    if entry["status"] != "completed":
        print(entry["config_name"], entry["status"], entry["error"], entry["failed_step"])

pipeline.save_log("study/log.json")        # the entries, with the versions
pipeline.clear_log()                       # empty the log

An entry holds these fields:

• save_log writes a JSON file with the entries, the log and schema versions, the Pictologics version and the export time. A name without .json gets it.
• The log grows with each run. In a long loop, save it and call clear_log().

What to Report

IBSI asks a study to report how it computed its features. Pictologics gives each part:

1. The configurations: save them with pipeline.save_configs("study/configs.yaml", config_names=[...]). The file loads again with RadiomicsPipeline.load_configs. See Configuration & Reproducibility.
2. The config_hash of each configuration: the same configuration gives the same hash on every computer. It is in each log entry.
3. The versions: the pictologics_version and the environment of the log entries.
4. The data dictionary: pipeline.describe_features(), with the IBSI code of each feature.
5. The image processing: the steps and their parameters (in the configurations), for example the spacing and the interpolation, the resegmentation range, and the discretisation method and its bins.
6. The IBSI compliance of the software: see IBSI 1 and IBSI 2. For the Gabor filter, also report the response value (see Image Filtering).