pdstools.adm.Reports¶

Report-generation namespace for ADMDatamart.

Exposed via the dm.generate namespace facade. Wraps Quarto-driven HealthCheck and ModelReport rendering plus an Excel export.

Classes¶

`ReportOptions`	Shared rendering/output options for report-generating methods.
`Reports`	Report generation namespace attached to `ADMDatamart` as `dm.generate`.

Module Contents¶

class ReportOptions¶

Bases: TypedDict

Shared rendering/output options for report-generating methods.

Passed via **options to Reports.model_reports() and Reports.health_check(). These eight keys are shared between both methods; each method also takes its own method-specific kwargs as normal parameters. All ReportOptions keys are optional — per-method defaults apply when a key is omitted.

Keys¶

titlestr: Title shown in the report.
subtitlestr: Subtitle shown under the title.
disclaimerstr: Disclaimer text included in the report.
output_dirstr or path-like or None: Directory for the output file. If None, uses the current working directory.
output_type{“html”, “pdf”}: Output format. Defaults to "html".
qmd_filestr or path-like or None: Path to a custom Quarto template. If None, the built-in template is used.
full_embedbool: When True, fully embed all JavaScript libraries (Plotly, itables, etc.) into the HTML output (larger file, requires esbuild). When False (default), load JavaScript libraries from CDN. See issue #620.
keep_temp_filesbool: If True, the temporary working directory is preserved after the report is generated. Defaults to False.

title: str¶

subtitle: str¶

disclaimer: str¶

output_dir: str | os.PathLike[str] | None¶

output_type: OutputType¶

qmd_file: str | os.PathLike[str] | None¶

full_embed: bool¶

keep_temp_files: bool¶

class Reports(datamart: pdstools.adm.ADMDatamart.ADMDatamart)¶

Bases: pdstools.utils.namespaces.LazyNamespace

Report generation namespace attached to ADMDatamart as dm.generate.

Parameters:: datamart (pdstools.adm.ADMDatamart.ADMDatamart)

dependencies: ClassVar[list[str]] = ['yaml']¶

dependency_group = 'healthcheck'¶

datamart¶

model_reports(model_ids: str | list[str], *, name: str | None = None, only_active_predictors: bool = True, progress_callback: collections.abc.Callable[[int, int], None] | None = None, model_file_path: str | os.PathLike[str] | None = None, predictor_file_path: str | os.PathLike[str] | None = None, **options: Unpack[ReportOptions]) → pathlib.Path¶

Generate model reports for Naive Bayes ADM models.

Parameters:

model_ids (str or list of str) – The model ID (or list of model IDs) to generate reports for.
name (str, optional) – Base file name of the report.
only_active_predictors (bool, default=True) – Whether to only include active predictor details.
progress_callback (callable, optional) – Function called as progress_callback(current, total) after each model report is rendered. Used by the Streamlit app.
model_file_path (str or path-like, optional) – Path to an existing model-data file. If provided, skips re-exporting the datamart’s model data.
predictor_file_path (str or path-like, optional) – Path to an existing predictor-data file. If provided, skips re-exporting the datamart’s predictor data.
**options (Unpack[ReportOptions]) – Shared rendering/output options. See ReportOptions for the full list (title, subtitle, disclaimer, output_dir, output_type, qmd_file, full_embed, keep_temp_files).

Returns:

The path to the generated report file (or zip if multiple model IDs).

Return type:

Path

Raises:

ValueError – If model_ids is empty or report generation fails.
FileNotFoundError – If required input files are not found.
subprocess.SubprocessError – If the Quarto subprocess fails.

Generate the ADM Health Check report.

Optionally includes predictor and prediction sections when the corresponding data is available on the datamart or supplied via prediction.

Parameters:

name (str, optional) – Base file name of the report.
query (QUERY, optional) – Extra filter applied to the datamart data before rendering.
prediction (Prediction, optional) – Prediction object to include in the report. If provided without prediction_file_path, prediction data is cached to a temporary file.
model_file_path (str or path-like, optional) – Path to an existing model-data file. If provided, skips re-exporting the datamart’s model data.
predictor_file_path (str or path-like, optional) – Path to an existing predictor-data file. If provided, skips re-exporting the datamart’s predictor data.
prediction_file_path (str or path-like, optional) – Path to an existing prediction-data file. If neither this nor prediction is provided, the prediction section is omitted.
**options (Unpack[ReportOptions]) – Shared rendering/output options. See ReportOptions for the full list (title, subtitle, disclaimer, output_dir, output_type, qmd_file, full_embed, keep_temp_files).

Returns:

The path to the generated report file.

Return type:

Path

Raises:

ValueError – If report generation fails.
FileNotFoundError – If required input files are not found.
subprocess.SubprocessError – If the Quarto subprocess fails.

excel_report(name: str | os.PathLike[str] = Path('Tables.xlsx'), *, predictor_binning: bool = False) → tuple[pathlib.Path | None, list[str]]¶

Export raw datamart tables to an Excel workbook.

Writes the last snapshots of model data, predictor summaries, and optionally predictor binning data to separate sheets. Sheets that are unavailable or exceed Excel’s row / size limits are skipped with a warning rather than failing the whole export.

Parameters:

name (str or path-like, default=Path("Tables.xlsx")) – Path where the Excel file will be written.
predictor_binning (bool, default=False) – If True, include the (potentially large) predictor binning sheet.

Returns:

The path to the created Excel file (None if no data was available), and a list of warning messages (empty if nothing was skipped).

Return type:

tuple of (Path or None, list of str)