Study reporting

Record the selected pipeline, the search that produced it and the context needed to interpret the results. This guide exports those records and prepares method references for a study report.

The snippets below continue Classification: a complete example with search and its selected model. In the example script, place them inside main(), after fit and evaluation.

Save the pipeline summary and search history

To retain cross-validation records, set keep_training_history=True when constructing IAML, before fitting, as shown in When you need a search record. After fit, search.training_history contains the collected pipeline configurations, fold-level results and evaluation statuses. These records stay in memory and are reset by the next fit.

Export the selected pipeline’s configuration and the collected history before starting another search:

import json
from pathlib import Path

audit = {
    "study": search.describe().to_dict(),
    "pipeline": model.pipeline_audit_summary(),
    "training_history": search.training_history,
}
Path("iaml_audit.json").write_text(
    json.dumps(audit, ensure_ascii=False, indent=2, default=str, allow_nan=False),
    encoding="utf-8",
)

The export stores simple values directly and represents other configuration objects as strings. The strict JSON export rejects non-finite numbers such as NaN or infinity if they occur in a metric, so inspect those results before exporting them.

This file records configurations and cross-validation results. It does not contain the fitted model, the observations or the row indices of each fold. Final fitting is not part of the history, and evaluations interrupted before returning a result may be absent. Preserve the study’s data-selection and split records separately.

Report results with their context

Save held-out scores from Distinguish search scores from test scores alongside the audit, identified separately from the search’s cross-validation scores. Retain the performance figures from Inspect performance plots and the SHAP outputs from 03 / Explain when they form part of the analysis.

Record the following alongside the outputs:

  • The cohort definition, inclusion criteria, features, outcome definition and, for classification, the label representing the event of interest.

  • The training and evaluation populations, split method, any patient or site grouping, and the retained row selections for each split.

  • The objective metric and its parameters, search budget, optimizer, sampling settings and final fitting population. Record train_on_n_samples and refit_on_sample when used. The search and final fit can use different rows.

  • Random seeds, IAML version or commit, and dependency versions. For SHAP, record the explained output, rows, background and sampling effort as well.

The audit is one part of this record. It does not capture all these settings automatically or guarantee identical results on another run.

Retain the recipe and the resolved study

When you customize pipelines, keep the editable recipe alongside the resolved study already included in the audit. describe() displays the recipe, diff(base) compares it with a baseline and to_code() exports its configuration as Python:

from pathlib import Path
from iaml.flow import PipelineSpec

print(search.pipeline.describe())
print(search.pipeline.diff(PipelineSpec.default()))
Path("pipeline_recipe.py").write_text(
    search.pipeline.to_code(), encoding="utf-8",
)

After fit, search.describe() reports that run’s resolved catalogue, objective, analytical definitions and available evaluation reports. Later recipe edits do not rewrite its frozen configuration or the selected candidate. search.pipeline.describe() and to_code() describe the current editable recipe, so save them before changing it for another run.

Exported recipe code retains active domains, inactive domains behind Const, aliases, exclusions and initial choices. An open family is resolved against the installed components when rerun; retain the resolved study report and dependency versions as well. Recipe reconstruction does not reproduce fitted state or guarantee identical scores. See Pipeline and study API reference for inspection and run snapshots.

Review method references

Components declare references that can help prepare the methods section:

print(model.bibliography())

Review this list against the actual pipeline before citing it. The current bibliography omits training-only resampling steps, so methods such as SMOTE may need additional references. It also includes a SHAP reference whether or not SHAP explanations were computed. The pipeline summary helps identify the methods actually used.

Citing IAML

If you use IAML in a study, cite the software release used for the analysis. For version 1.0.0, use:

Merieux, R., Ruellet, H., Bourachot, R., Dahlouk, Y., Blanchard, F., & Vuiblet, V. (2026). IAML: Integrated AutoML for Medical Labs (Version 1.0.0) [Computer software]. https://github.com/IIAS-Research/iaml/releases/tag/v1.0.0

The same reference in BibTeX:

@misc{iaml_1_0_0,
  author       = {Merieux, Rudy and Ruellet, Hugo and Bourachot, Robin
                  and Dahlouk, Youssouf and Blanchard, Fr{\'e}d{\'e}ric
                  and Vuiblet, Vincent},
  title        = {{IAML}: Integrated {AutoML} for Medical Labs},
  year         = {2026},
  howpublished = {Computer software},
  note         = {Version 1.0.0},
  url          = {https://github.com/IIAS-Research/iaml/releases/tag/v1.0.0}
}

Use python -m pip show PyIAML to check the installed version. For another release, update the version, year and release URL in the reference. For a development checkout, cite the full commit identifier and its GitHub URL.

Cite the methods used in your pipeline as well, using the bibliography described above to identify the relevant references.