Reporting

Structured reporting helpers build on the Python data surfaces already exposed by cimba.Dataset and cimba.TimeSeries. They return plain Python objects that can be formatted, inspected, or plotted.

The C API exposes this area as printer-oriented functions such as cmb_dataset_fivenum_print(), cmb_dataset_histogram_print(), cmb_dataset_correlogram_print(), and resource-specific report printers. Python keeps the same reporting coverage but returns structured values first. Use format_report() for debug text, or the plotting helpers for figures. The C functions are not exposed under their cmb_* names.

The reporting backend intentionally stays native and dependency-free for the calculations. For analysis libraries, reporting objects expose plain Python records and column dictionaries, so pandas, Polars, NumPy, CSV writers, and similar tools can consume the results without Cimba importing those libraries.

Install plotting support with the optional extra:

pip install "cimba[plot]"

class cimba.reporting.SummaryStats

Availability-aware summary statistics. Fields that do not make sense for the available sample count are None.

as_dict(): Return a plain dictionary, suitable for pandas.DataFrame([stats.as_dict()]).

class cimba.reporting.FiveNumberSummary

Five-number summary with min, q1, median, q3, max, and a weighted flag. This is the Python equivalent of the C five-number printers.

as_dict(): Return a plain dictionary.

class cimba.reporting.HistogramBin

One histogram bucket with lower, upper, mass, underflow, and overflow fields.

as_dict(): Return a plain dictionary.

class cimba.reporting.Histogram

Histogram data with explicit underflow and overflow buckets.

as_dict()

to_records()

to_columns(): Return nested dictionaries, row records, or column tuples for analysis libraries.

class cimba.reporting.Correlogram

Autocorrelation or partial-autocorrelation coefficients.

as_dict()

to_records()

to_columns(): Return dictionaries, row records, or column tuples with kind, lag, and coefficient fields.

class cimba.reporting.HistoryReport

Structured report containing a title, summary, histogram, and optional correlogram.

as_dict()

to_tables(): Return nested report data or table-shaped records keyed by report section.

cimba.reporting.summarize(source): Return SummaryStats for a cimba.DataSummary, cimba.WeightedSummary, cimba.Dataset, or cimba.TimeSeries.

cimba.reporting.histogram(source, bins=20, range=None, weighted='auto'): Return a Histogram for a cimba.Dataset or cimba.TimeSeries. Time series histograms are duration-weighted by default.

cimba.reporting.five_number(source): Return a FiveNumberSummary for a cimba.Dataset or cimba.TimeSeries. Time series summaries are duration-weighted.

cimba.reporting.correlogram(source, lags, kind='acf'): Return a Correlogram using source.acf(lags) or source.pacf(lags).

cimba.reporting.history_report(source, *, title=None, bins=20, lags=None, correlation=None): Return a HistoryReport for a dataset or time series.

cimba.reporting.resource_report(resource, *, bins=None, lags=None, correlation=None): Return a HistoryReport for a recorded buffer, queue, resource, or resource pool.

cimba.reporting.sample_records(source)

cimba.reporting.sample_columns(source): Return raw cimba.Dataset or cimba.TimeSeries samples with stable column names. Datasets use index and value; time series use time, value, and weight.

cimba.reporting.format_report(report): Return text for a HistoryReport matching the native Cimba report: the cmb_buffer_print_report() summary and character histogram followed by the cmb_dataset_correlogram_print() correlogram.

cimba.reporting.format_summary(summary_or_source): Return compact debug text for a SummaryStats, cimba.DataSummary, cimba.WeightedSummary, cimba.Dataset, or cimba.TimeSeries.

cimba.reporting.plot_history(history, ax=None, **kwargs)

cimba.reporting.plot_histogram(histogram_or_source, ax=None, **kwargs)

cimba.reporting.plot_correlogram(correlogram_or_source, ax=None, **kwargs)

cimba.reporting.plot_report(report, axes=None, **kwargs): Plot with Matplotlib. The dependency is imported only when one of these helpers is called.

Analysis Interop

The record adapters are ordinary Python data:

from cimba import reporting

report = reporting.history_report(samples, bins=30, lags=12)

summary_row = report.summary.as_dict()
histogram_rows = report.histogram.to_records()
correlogram_rows = report.correlogram.to_records()

# pandas or Polars can build frames directly from the records.
# pd.DataFrame(histogram_rows)
# pl.DataFrame(report.to_tables()["summary"])

For raw sample data, use sample_records() or sample_columns():

rows = reporting.sample_records(history)
columns = reporting.sample_columns(history)

C API Equivalents

C reporting helper	Python reporting helper
`cmb_datasummary_print()`, `cmb_wtdsummary_print()`	`summarize()`, `format_summary()`
`cmb_dataset_fivenum_print()`, `cmb_timeseries_fivenum_print()`	`five_number()`
`cmb_dataset_histogram_print()`, `cmb_timeseries_histogram_print()`	`histogram()`, `plot_histogram()`
`cmb_dataset_ACF()`, `cmb_dataset_PACF()`, correlogram printers	`correlogram()`, `plot_correlogram()`
`cmb_buffer_print_report()` and the queue/resource report printers	`resource_report()`, `format_report()`, `plot_report()`
`cmb_dataset_print()`, `cmb_timeseries_print()`	`cimba.Dataset.values()`, `cimba.TimeSeries.values()`