report

The study report: the tables and the figures of an analysis in one document.

An analysis of pkpdutils ends in data frames and figures; a study report is those pieces in the order ICH M13A (2024, 2.2.2) asks for, in a file which can be sent around. Report collects the pieces - a paragraph, a table, a figure - and writes them as a self-contained HTML page (the figures embedded as base64 PNG, so the file travels alone) or as markdown next to its figure files. study_report assembles the package of a bioequivalence or single dose study from a batch and its result: the sentence describing the methods, the summary statistics M13A names, the acceptability of the extrapolation, the parameters of every subject, the mean curves and the individual panels.

Nothing here decides anything: every number comes from the analysis which was run, and every table is the one the matching function of pkpdutils returns, so a report can be extended with any further frame or figure of the package before it is written.

Section `dataclass` ¶

Section(
    kind,
    heading="",
    text="",
    frame=None,
    caption="",
    image=b"",
    digits=3,
    level=2,
)

One section of a report.

Attributes:

Name	Type	Description
`kind`	`SectionKind`	`"text"`, `"table"` or `"figure"`
`heading`	`str`	the heading above the section, empty for none
`text`	`str`	the paragraph of a text section
`frame`	`DataFrame \| None`	the table of a table section
`caption`	`str`	the caption below a table or a figure
`image`	`bytes`	the rendered PNG of a figure section
`digits`	`int`	significant digits of the numbers of a table
`level`	`int`	the level of the heading

Report `dataclass` ¶

Report(
    title="Study report",
    subtitle="",
    digits=3,
    sections=list(),
)

The sections of a report, written as HTML or as markdown.

A report is built by adding sections in the order they are read; every add_* returns the report itself, so the calls chain. The figures are rendered to PNG when they are added, so the report does not keep the matplotlib figures alive and writing it twice gives the same bytes.

Attributes:

Name	Type	Description
`title`	`str`	the title of the document
`subtitle`	`str`	the line below the title, empty for none
`digits`	`int`	significant digits of the numbers of a table which does not ask for its own
`sections`	`list[Section]`	the sections, in order

add_text ¶

add_text(text, *, heading=None, level=2)

Add a paragraph, optionally under a heading.

Parameters:

Name	Type	Description	Default
`text`	`str`	the paragraph; several paragraphs are separated by an empty line, as in markdown.	required

Other Parameters:

Name	Type	Description
`heading`	`str \| None`	the heading above it, none by default.
`level`	`int`	the level of the heading, 2 for a section of the document.

Returns:

Type	Description
`Report`	The report, so that the calls chain.

Raises:

Type	Description
`ValueError`	if `level` is not between 1 and 6.

add_table ¶

add_table(frame, caption='', *, heading=None, digits=None)

Add a table with a caption.

Parameters:

Name	Type	Description	Default
`frame`	`DataFrame`	the table, as any function of the package returns it; its index is not written, so a frame whose index carries information is reset by the caller.	required
`caption`	`str`	the caption below the table.	`''`

Other Parameters:

Name	Type	Description
`heading`	`str \| None`	the heading above it, none by default.
`digits`	`int \| None`	significant digits of the numbers, the report's own by default; a frame of formatted strings is unaffected.

Returns:

Type	Description
`Report`	The report, so that the calls chain.

add_figure ¶

add_figure(fig, caption='', dpi=150, *, heading=None)

Add a figure with a caption, rendered to PNG right away.

Parameters:

Name	Type	Description	Default
`fig`	`Figure`	the figure, as every plotting function of the package returns it; it is not closed, the caller owns it.	required
`caption`	`str`	the caption below the figure.	`''`
`dpi`	`int`	resolution of the rendered image.	`150`

Other Parameters:

Name	Type	Description
`heading`	`str \| None`	the heading above it, none by default.

Returns:

Type	Description
`Report`	The report, so that the calls chain.

write_html ¶

write_html(path)

Write the report as one self-contained HTML file.

The figures are embedded as base64 PNG and the style sheet is part of the document, so the file carries everything it needs and can be mailed or archived on its own.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	the file to write; its directory is created.	required

Returns:

Type	Description
`Path`	The file which was written.

write_markdown ¶

write_markdown(path)

Write the report as markdown with its figures as files next to it.

A figure is written as <stem>_<number>.png in the directory of the markdown file and referenced by that name, so the document and its images move together.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	the markdown file to write; its directory is created.	required

Returns:

Type	Description
`Path`	The markdown file which was written.

format_cell ¶

format_cell(value, digits=3)

One cell of a report table, formatted as the publication tables are.

A float is rounded to digits significant digits with pkpdutils.result.format_number, which leaves a missing value empty; a boolean and an integer are written as they are and anything else as its string.

Parameters:

Name	Type	Description	Default
`value`	`Any`	the cell value.	required
`digits`	`int`	significant digits of a float.	`3`

Returns:

Type	Description
`str`	The cell as a string.

study_report ¶

study_report(
    batch,
    result,
    *,
    dim,
    by=None,
    options=None,
    title="Non-compartmental analysis report",
    subtitle="",
)

The report package of a study: the methods, the tables and the figures.

The sections are the ones ICH M13A (2024, 2.2.2) names, in its order: the sentence describing the non-compartmental methods (methods_line), the summary statistics of every parameter with the statistics M13A lists (M13A_STATISTICS), the acceptability of the extrapolation of every subject with its verdict (acceptability_table, left out when the result carries no auc_inf_obs), the parameters of every subject (NCAResult.to_dataframe), the mean curves per group (pkpdutils.plot.plot_mean_timecourse) and one panel per subject (pkpdutils.plot.plot_nca_grid). The report is returned, not written, so that further sections can be added before write_html or write_markdown.

Parameters:

Name	Type	Description	Default
`batch`	`Timecourses`	the timecourses the analysis ran on.	required
`result`	`NCAResult`	the analysis of that batch.	required

Other Parameters:

Name	Type	Description
`dim`	`str`	the sample dimension of the individuals.
`by`	`str \| None`	coordinate along `dim` grouping the subjects (the treatment, the dose group), one group by default.
`options`	`NCAOptions \| None`	the options the analysis was run with, for the methods sentence; the defaults are described when none are given.
`title`	`str`	the title of the document.
`subtitle`	`str`	the line below the title.

Returns:

Type	Description
`Report`	The report.

Raises:

Type	Description
`ValueError`	if `dim` is not a sample dimension of the result.

report

Section dataclass ¶

Report dataclass ¶

add_text ¶

add_table ¶

add_figure ¶

write_html ¶

write_markdown ¶

format_cell ¶

study_report ¶

Section `dataclass` ¶

Report `dataclass` ¶