PumasReports Docstrings

Tools for working with, and generating, static reports based on Pumas data

report(
    fitted_models;
    output,
    title,
    version,
    date,
    author,
    categorical,
    force,
    inspect,
    infer,
    clean,
    header,
    footer,
    plot_fontsize,
    plot_resolution
)

Create a PDF report based on the provided fitted_models.

fitted_models can be provided as one of several different inputs:

A single fitted model result from fit.

fit_result = fit(...)
report(fit_result)

Note that ... in these examples is not real syntax and is used in these examples to illustrate unimportant details.

A vector of fitted model results from fit.

fit_1 = fit(...)
fit_2 = fit(...)
report([fit_1, fit_2])

The above two calls will result in fitted models named 1 to N. If you wish to provide named fitted models in the resulting report then pass in a NamedTuple instead of a single fit result or vector:

my_named_fit = fit(...)
report((; my_named_fit))

fit_1 = fit(...)
fit_2 = fit(...)
report((; fit_1, fit_2))

Note the leading ;, which is standard Julia syntax and required for naming your fitted models.

Other computed results can also be included alongside your fit results, namely inspect, infer, and vpc results. Any number of vpc results can be included, while only one of each of inspect and infer may be included. To include associated results along with the fitted model use Julia's tuple syntax, i.e. (a, b, c):

fit_1 = fit(...)
ins_1 = inspect(fit_1, ...)
inf_1 = infer(fit_1, ...)
vpc_1 = vpc(fit_1, ...)
vpc_2 = vpc(fit_1, ...)

report((; my_model = (fit_1, ins_1, inf_1, vpc_1, vpc_2)))

Keywords

• output: directory into which the final report files will be saved.
• title: a title for the final report that will appear on the title page and be used for the name of the finished PDF.
• version: the version of the document, given as a v"..." string.
• date: the date of the report, given as a Date value.
• author: the name of the author of the document.
• categorical: a vector of Symbols for covariates that should be treated as categorical in all plots of the report.
• force: (default true) remove all contents of output (if it exists) before generating a new report.
• inspect: (default true) should inspect be called automatically on fitted models if no inspect result is already provided. The call to inspect does not pass any additional arguments and so if customized inspect calls are required, for example when using NPDE, a pre-computed inspect result should be passed in instead of relying of the automatic behaviour.
• infer: (default false) should infer be called automatically on fitted models if no infer result is already provided.
• clean: (default true) only include the final PDF document in the output folder rather than all intermediate files as well.
• header: custom text to be added to the header section of each page.
• footer: custom text to be added to the footer section of each page.
• plot_fontsize: set the font size for all plots in the report. Default is 16.
• plot_resolution: set the resolution for all plots in the report. Default is (960, 540).

Examples

The following will generate a report based on objects fpm1 and fpm2, which are FittedPumasModels. It will automatically call inspect and infer for each.

report((; fpm1, fpm2))

The names of the models in the reports will be the same as the variable names. To change the names pass a different key name in the NamedTuple syntax passed to report.

Report-level metadata that should be included in the generated report can be passed in via the keyword arguments title and version, others to be added later.

The name of the resulting PDF file can be given with output = "NAME.pdf.

Return a valid "username" as defined in either "USER", "USER_NAME", or "USERNAME" to cover the differences on unix, windows, and juliahub.

coefficients_table(fitted_model)
coefficients_table(
    fitted_model,
    inference;
    digits,
    sigdigits,
    latex
)

Presents the fitted_model coefficients in a formatted DataFrame for use in reporting. When the second argument inference is provided then that is used for calculation of table values.

Keywords

• digits = 3 the number of significant digits to format number to.
• latex = false whether to display parameter names using $ for use in LaTeX tables.

compare_estimates(; fitted_models...)

Compare estimates for the given fitted_models.

Examples

compare_estimates(; fit_1, fit_2, fit_3)

metrics_table(fitted_model; digits, sigdigits, latex)

Presents the fitted_model metrics in a formatted DataFrame for use in reporting.

Keywords

• digits = 3 the number of significant digits to format number to.
• latex = false whether to display parameter names using $ for use in LaTeX tables.