Skip to content

Plotting API

Back to API Reference

The figures are read from the results they draw, and return a matplotlib Figure. results.plot, replicates.plot and predictive.plot give the figures of a run, of replicates and of a predictive: plot.series(), plot.cumulative() and plot.observations(). The results of PRCC, Morris, Sobol and polynomial chaos, and the result of a profile likelihood, draw their figure with plot(). plot_compared draws several runs, replicates or predictives on the same panels. The figures need the optional extra commol[plot]. Guide: Plotting.

ResultsPlot

The figures of one run, read from results.plot.

Each figure has one panel per series, or per observed series for observations, and returns the matplotlib Figure. Given axes=, the Figure of an earlier figure of commol, it draws each series on the panel of that series instead.

Source code in commol/api/plotting/accessors.py 
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
class ResultsPlot:
    """
    The figures of one run, read from ``results.plot``.

    Each figure has one panel per series, or per observed series for
    `observations`, and returns the matplotlib `Figure`. Given ``axes=``, the
    `Figure` of an earlier figure of commol, it draws each series on the
    panel of that series instead.
    """

    def __init__(self, results: "SimulationResults") -> None:
        """
        The figures of `results`.

        Parameters
        ----------
        results : SimulationResults
            The run.
        """
        self._results = results

    def series(
        self,
        output_file: str | None = None,
        observed_data: "list[ObservedDataPoint] | None" = None,
        calibration_result: "CalibrationResult | None" = None,
        config: "PlotConfig | None" = None,
        series: list[str] | None = None,
        show_legend: bool = True,
        position_label: Callable[[float], str] | None = None,
        tick_every: float | None = None,
        x_label: str = "Step",
        prediction_intervals: "PredictionIntervals | None" = None,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw each series along the axis, one panel per series.

        Parameters
        ----------
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        observed_data : list[ObservedDataPoint] | None
            Observations, each drawn as a point on the panel of its label.
            When the observations of a series share one sum of outputs and
            one factor and have no window, the line covers every position of
            the results. Otherwise the model of each observation is read
            through its own operator (outputs, window, factor) at its own
            position, as the loss reads it, and the line joins these values.
        calibration_result : CalibrationResult | None
            Its ``best_parameters`` give the values of the factors of the
            observations, which multiply the line; observed values stay in
            their own units.
        config : PlotConfig | None
            Layout and style. If None, the defaults.
        series : list[str] | None
            What to draw, one panel each: an output name (such as ``A_g1``),
            or a bin or accumulator id, which draws the sum of its outputs.
            An exact output name wins over an id. If None, every output.
        show_legend : bool
            Whether each panel shows its legend.
        position_label : Callable[[float], str] | None
            Turns a position on the axis into a tick label. If None, a model
            with an origin (``ModelBuilder(origin=...)``) labels each tick
            with its date: ``2020-01-02``, with the time when it is not
            midnight. Otherwise the ticks show the position.
        tick_every : float | None
            Labels the plotted positions `tick_every` apart, counted from the
            first plotted position. If None, every plotted position, or the
            ticks matplotlib places on a dated axis.
        x_label : str
            The label of the x axis.
        prediction_intervals : PredictionIntervals | None
            Prediction intervals of a conformal method
            (``ConformalResult.intervals``). The panel of each of their
            series, by label, shows the band between their lower and upper
            ends and their point prediction, dashed; an unbounded interval
            is left out of the band.
        axes : Figure | None
            A figure of commol to draw on: each series is drawn on its panel,
            the `Axes` whose label is the id of the series. If None, a new
            figure.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the line of the run, such as
            ``linewidth``, ``alpha`` or ``linestyle``.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            If an entry of ``series`` is a bin or accumulator id of results
            with no model; the results have no value at the position of an
            observation read on its own or at the start of its window; or
            ``axes`` has no panel of a series.
        KeyError
            If an entry of ``series`` is neither an output nor a bin or
            accumulator id of the model.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _run_series

        return _run_series(
            self._results,
            output_file=output_file,
            observed_data=observed_data,
            calibration_result=calibration_result,
            config=config,
            series=series,
            show_legend=show_legend,
            position_label=position_label,
            tick_every=tick_every,
            x_label=x_label,
            prediction_intervals=prediction_intervals,
            axes=axes,
            **kwargs,
        )

    def cumulative(
        self,
        output_file: str | None = None,
        observed_data: "list[ObservedDataPoint] | None" = None,
        calibration_result: "CalibrationResult | None" = None,
        config: "PlotConfig | None" = None,
        series: list[str] | None = None,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw the running total of each series, one panel per series.

        Parameters
        ----------
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        observed_data : list[ObservedDataPoint] | None
            Observations, drawn as their running total on the panel of their
            label. An observation with a factor is divided by the value of
            its factor in ``calibration_result``.
        calibration_result : CalibrationResult | None
            Its ``best_parameters`` give the values of the factors.
        config : PlotConfig | None
            Layout, size and style. If None, the defaults.
        series : list[str] | None
            What to draw, one panel each, as in `series`. If None, every
            output.
        axes : Figure | None
            A figure of commol to draw on, as in `series`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the line of the run.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            If ``axes`` has no panel of a series.
        KeyError
            If an entry of ``series`` is neither an output nor a bin or
            accumulator id of the model.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _run_cumulative

        return _run_cumulative(
            self._results,
            output_file=output_file,
            observed_data=observed_data,
            calibration_result=calibration_result,
            config=config,
            series=series,
            axes=axes,
            **kwargs,
        )

    def observations(
        self,
        observed_data: "list[ObservedDataPoint]",
        output_file: str | None = None,
        calibration_result: "CalibrationResult | None" = None,
        config: "PlotConfig | None" = None,
        show_legend: bool = True,
        position_label: Callable[[float], str] | None = None,
        tick_every: float | None = None,
        x_label: str = "Step",
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw each observed series with the model read through its
        observation operator, one panel per label.

        The model is read only at the observations: the value of each
        observation through its own operator (the sum of its outputs, its
        window and its factor), as the loss reads it. A value with a window is
        a total over ``(at - window, at]``, drawn as a step over its window
        with a marker at ``at``. A value with no window is a marker, joined
        to the next only as a guide. The run along the whole axis is
        `series`, on the same figure with ``axes=``.

        Parameters
        ----------
        observed_data : list[ObservedDataPoint]
            The observations. Each label is one panel, in the order of its
            first observation, with the `Axes` label of the label.
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        calibration_result : CalibrationResult | None
            Its ``best_parameters`` give the values of the factors of the
            observations, which multiply the model; observed values stay in
            their own units.
        config : PlotConfig | None
            Layout and style. If None, the defaults.
        show_legend : bool
            Whether each panel shows its legend.
        position_label : Callable[[float], str] | None
            Turns a position into a tick label, as in `series`.
        tick_every : float | None
            The distance between labelled observation positions, as in
            `series`.
        x_label : str
            The label of the x axis.
        axes : Figure | None
            A figure of commol to draw on: each observed series is drawn on
            the `Axes` whose label is its label. If None, a new figure.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the steps and the guide of the model,
            such as ``linewidth`` or ``alpha``.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            If there are no observations; the results have no value at the
            position of an observation or at the start of its window; or
            ``axes`` has no panel of a label.
        KeyError
            If an observation names an output the results do not have.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _run_observations

        return _run_observations(
            self._results,
            observed_data,
            output_file=output_file,
            calibration_result=calibration_result,
            config=config,
            show_legend=show_legend,
            position_label=position_label,
            tick_every=tick_every,
            x_label=x_label,
            axes=axes,
            **kwargs,
        )

Methods:

__init__ 

__init__(results: SimulationResults) -> None

The figures of results.

Parameters:

Name Type Description Default
results SimulationResults

The run.

 required
Source code in commol/api/plotting/accessors.py 
33
34
35
36
37
38
39
40
41
42
def __init__(self, results: "SimulationResults") -> None:
    """
    The figures of `results`.

    Parameters
    ----------
    results : SimulationResults
        The run.
    """
    self._results = results

series 

series(output_file: str | None = None, observed_data: list[ObservedDataPoint] | None = None, calibration_result: CalibrationResult | None = None, config: PlotConfig | None = None, series: list[str] | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', prediction_intervals: PredictionIntervals | None = None, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw each series along the axis, one panel per series.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
observed_data list[ObservedDataPoint] | None

Observations, each drawn as a point on the panel of its label. When the observations of a series share one sum of outputs and one factor and have no window, the line covers every position of the results. Otherwise the model of each observation is read through its own operator (outputs, window, factor) at its own position, as the loss reads it, and the line joins these values.

 None
calibration_result CalibrationResult | None

Its best_parameters give the values of the factors of the observations, which multiply the line; observed values stay in their own units.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
series list[str] | None

What to draw, one panel each: an output name (such as A_g1), or a bin or accumulator id, which draws the sum of its outputs. An exact output name wins over an id. If None, every output.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position on the axis into a tick label. If None, a model with an origin (ModelBuilder(origin=...)) labels each tick with its date: 2020-01-02, with the time when it is not midnight. Otherwise the ticks show the position.

 None
tick_every float | None

Labels the plotted positions tick_every apart, counted from the first plotted position. If None, every plotted position, or the ticks matplotlib places on a dated axis.

 None
x_label str

The label of the x axis.

 'Step'
prediction_intervals PredictionIntervals | None

Prediction intervals of a conformal method (ConformalResult.intervals). The panel of each of their series, by label, shows the band between their lower and upper ends and their point prediction, dashed; an unbounded interval is left out of the band.

 None
axes Figure | None

A figure of commol to draw on: each series is drawn on its panel, the Axes whose label is the id of the series. If None, a new figure.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of the run, such as linewidth, alpha or linestyle.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If an entry of series is a bin or accumulator id of results with no model; the results have no value at the position of an observation read on its own or at the start of its window; or axes has no panel of a series.
KeyError

If an entry of series is neither an output nor a bin or accumulator id of the model.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def series(
    self,
    output_file: str | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    calibration_result: "CalibrationResult | None" = None,
    config: "PlotConfig | None" = None,
    series: list[str] | None = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    prediction_intervals: "PredictionIntervals | None" = None,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw each series along the axis, one panel per series.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    observed_data : list[ObservedDataPoint] | None
        Observations, each drawn as a point on the panel of its label.
        When the observations of a series share one sum of outputs and
        one factor and have no window, the line covers every position of
        the results. Otherwise the model of each observation is read
        through its own operator (outputs, window, factor) at its own
        position, as the loss reads it, and the line joins these values.
    calibration_result : CalibrationResult | None
        Its ``best_parameters`` give the values of the factors of the
        observations, which multiply the line; observed values stay in
        their own units.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    series : list[str] | None
        What to draw, one panel each: an output name (such as ``A_g1``),
        or a bin or accumulator id, which draws the sum of its outputs.
        An exact output name wins over an id. If None, every output.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position on the axis into a tick label. If None, a model
        with an origin (``ModelBuilder(origin=...)``) labels each tick
        with its date: ``2020-01-02``, with the time when it is not
        midnight. Otherwise the ticks show the position.
    tick_every : float | None
        Labels the plotted positions `tick_every` apart, counted from the
        first plotted position. If None, every plotted position, or the
        ticks matplotlib places on a dated axis.
    x_label : str
        The label of the x axis.
    prediction_intervals : PredictionIntervals | None
        Prediction intervals of a conformal method
        (``ConformalResult.intervals``). The panel of each of their
        series, by label, shows the band between their lower and upper
        ends and their point prediction, dashed; an unbounded interval
        is left out of the band.
    axes : Figure | None
        A figure of commol to draw on: each series is drawn on its panel,
        the `Axes` whose label is the id of the series. If None, a new
        figure.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of the run, such as
        ``linewidth``, ``alpha`` or ``linestyle``.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If an entry of ``series`` is a bin or accumulator id of results
        with no model; the results have no value at the position of an
        observation read on its own or at the start of its window; or
        ``axes`` has no panel of a series.
    KeyError
        If an entry of ``series`` is neither an output nor a bin or
        accumulator id of the model.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _run_series

    return _run_series(
        self._results,
        output_file=output_file,
        observed_data=observed_data,
        calibration_result=calibration_result,
        config=config,
        series=series,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        prediction_intervals=prediction_intervals,
        axes=axes,
        **kwargs,
    )

cumulative 

cumulative(output_file: str | None = None, observed_data: list[ObservedDataPoint] | None = None, calibration_result: CalibrationResult | None = None, config: PlotConfig | None = None, series: list[str] | None = None, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw the running total of each series, one panel per series.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
observed_data list[ObservedDataPoint] | None

Observations, drawn as their running total on the panel of their label. An observation with a factor is divided by the value of its factor in calibration_result.

 None
calibration_result CalibrationResult | None

Its best_parameters give the values of the factors.

 None
config PlotConfig | None

Layout, size and style. If None, the defaults.

 None
series list[str] | None

What to draw, one panel each, as in series. If None, every output.

 None
axes Figure | None

A figure of commol to draw on, as in series.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of the run.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If axes has no panel of a series.
KeyError

If an entry of series is neither an output nor a bin or accumulator id of the model.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def cumulative(
    self,
    output_file: str | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    calibration_result: "CalibrationResult | None" = None,
    config: "PlotConfig | None" = None,
    series: list[str] | None = None,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw the running total of each series, one panel per series.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    observed_data : list[ObservedDataPoint] | None
        Observations, drawn as their running total on the panel of their
        label. An observation with a factor is divided by the value of
        its factor in ``calibration_result``.
    calibration_result : CalibrationResult | None
        Its ``best_parameters`` give the values of the factors.
    config : PlotConfig | None
        Layout, size and style. If None, the defaults.
    series : list[str] | None
        What to draw, one panel each, as in `series`. If None, every
        output.
    axes : Figure | None
        A figure of commol to draw on, as in `series`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of the run.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If ``axes`` has no panel of a series.
    KeyError
        If an entry of ``series`` is neither an output nor a bin or
        accumulator id of the model.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _run_cumulative

    return _run_cumulative(
        self._results,
        output_file=output_file,
        observed_data=observed_data,
        calibration_result=calibration_result,
        config=config,
        series=series,
        axes=axes,
        **kwargs,
    )

observations 

observations(observed_data: list[ObservedDataPoint], output_file: str | None = None, calibration_result: CalibrationResult | None = None, config: PlotConfig | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw each observed series with the model read through its observation operator, one panel per label.

The model is read only at the observations: the value of each observation through its own operator (the sum of its outputs, its window and its factor), as the loss reads it. A value with a window is a total over (at - window, at], drawn as a step over its window with a marker at at. A value with no window is a marker, joined to the next only as a guide. The run along the whole axis is series, on the same figure with axes=.

Parameters:

Name Type Description Default
observed_data list[ObservedDataPoint]

The observations. Each label is one panel, in the order of its first observation, with the Axes label of the label.

 required
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
calibration_result CalibrationResult | None

Its best_parameters give the values of the factors of the observations, which multiply the model; observed values stay in their own units.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position into a tick label, as in series.

 None
tick_every float | None

The distance between labelled observation positions, as in series.

 None
x_label str

The label of the x axis.

 'Step'
axes Figure | None

A figure of commol to draw on: each observed series is drawn on the Axes whose label is its label. If None, a new figure.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the steps and the guide of the model, such as linewidth or alpha.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If there are no observations; the results have no value at the position of an observation or at the start of its window; or axes has no panel of a label.
KeyError

If an observation names an output the results do not have.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
def observations(
    self,
    observed_data: "list[ObservedDataPoint]",
    output_file: str | None = None,
    calibration_result: "CalibrationResult | None" = None,
    config: "PlotConfig | None" = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw each observed series with the model read through its
    observation operator, one panel per label.

    The model is read only at the observations: the value of each
    observation through its own operator (the sum of its outputs, its
    window and its factor), as the loss reads it. A value with a window is
    a total over ``(at - window, at]``, drawn as a step over its window
    with a marker at ``at``. A value with no window is a marker, joined
    to the next only as a guide. The run along the whole axis is
    `series`, on the same figure with ``axes=``.

    Parameters
    ----------
    observed_data : list[ObservedDataPoint]
        The observations. Each label is one panel, in the order of its
        first observation, with the `Axes` label of the label.
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    calibration_result : CalibrationResult | None
        Its ``best_parameters`` give the values of the factors of the
        observations, which multiply the model; observed values stay in
        their own units.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position into a tick label, as in `series`.
    tick_every : float | None
        The distance between labelled observation positions, as in
        `series`.
    x_label : str
        The label of the x axis.
    axes : Figure | None
        A figure of commol to draw on: each observed series is drawn on
        the `Axes` whose label is its label. If None, a new figure.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the steps and the guide of the model,
        such as ``linewidth`` or ``alpha``.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If there are no observations; the results have no value at the
        position of an observation or at the start of its window; or
        ``axes`` has no panel of a label.
    KeyError
        If an observation names an output the results do not have.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _run_observations

    return _run_observations(
        self._results,
        observed_data,
        output_file=output_file,
        calibration_result=calibration_result,
        config=config,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        axes=axes,
        **kwargs,
    )

ReplicatesPlot

The figures of the replicates of a stochastic engine, read from replicates.plot.

The figures are those of ResultsPlot for the mean of the replicates; series adds the band of the replicates.

Source code in commol/api/plotting/accessors.py 
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
class ReplicatesPlot:
    """
    The figures of the replicates of a stochastic engine, read from
    ``replicates.plot``.

    The figures are those of `ResultsPlot` for the mean of the replicates;
    `series` adds the band of the replicates.
    """

    def __init__(self, replicates: "SimulationReplicates") -> None:
        """
        The figures of `replicates`.

        Parameters
        ----------
        replicates : SimulationReplicates
            The replicates.
        """
        self._replicates = replicates

    def series(
        self,
        output_file: str | None = None,
        observed_data: "list[ObservedDataPoint] | None" = None,
        calibration_result: "CalibrationResult | None" = None,
        config: "PlotConfig | None" = None,
        series: list[str] | None = None,
        show_legend: bool = True,
        position_label: Callable[[float], str] | None = None,
        tick_every: float | None = None,
        x_label: str = "Step",
        prediction_intervals: "PredictionIntervals | None" = None,
        confidence_level: float = 0.95,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw the mean of each series and the band of the replicates, one
        panel per series.

        Each replicate is reduced to the series first, through the operator
        of its observations, then the band takes the interval of
        `confidence_level` across them (`member_statistics`).

        Parameters
        ----------
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        observed_data : list[ObservedDataPoint] | None
            Observations, as in `ResultsPlot.series`.
        calibration_result : CalibrationResult | None
            The values of the factors, as in `ResultsPlot.series`.
        config : PlotConfig | None
            Layout and style. If None, the defaults.
        series : list[str] | None
            What to draw, as in `ResultsPlot.series`.
        show_legend : bool
            Whether each panel shows its legend.
        position_label : Callable[[float], str] | None
            Turns a position into a tick label, as in `ResultsPlot.series`.
        tick_every : float | None
            The distance between labelled positions, as in
            `ResultsPlot.series`.
        x_label : str
            The label of the x axis.
        prediction_intervals : PredictionIntervals | None
            Prediction intervals of a conformal method, as in
            `ResultsPlot.series`.
        confidence_level : float
            The level of the band, strictly between 0 and 1.
        axes : Figure | None
            A figure of commol to draw on, as in `ResultsPlot.series`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the line of the mean.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            As `ResultsPlot.series`; or if there are no replicates or the
            confidence level is out of range.
        KeyError
            As `ResultsPlot.series`.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _replicates_series

        return _replicates_series(
            self._replicates,
            output_file=output_file,
            observed_data=observed_data,
            calibration_result=calibration_result,
            config=config,
            series=series,
            show_legend=show_legend,
            position_label=position_label,
            tick_every=tick_every,
            x_label=x_label,
            prediction_intervals=prediction_intervals,
            confidence_level=confidence_level,
            axes=axes,
            **kwargs,
        )

    def cumulative(
        self,
        output_file: str | None = None,
        observed_data: "list[ObservedDataPoint] | None" = None,
        calibration_result: "CalibrationResult | None" = None,
        config: "PlotConfig | None" = None,
        series: list[str] | None = None,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw the running total of the mean of the replicates, as
        `ResultsPlot.cumulative` draws one run.

        Parameters
        ----------
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        observed_data : list[ObservedDataPoint] | None
            Observations, as in `ResultsPlot.cumulative`.
        calibration_result : CalibrationResult | None
            The values of the factors, as in `ResultsPlot.cumulative`.
        config : PlotConfig | None
            Layout, size and style. If None, the defaults.
        series : list[str] | None
            What to draw, as in `ResultsPlot.series`.
        axes : Figure | None
            A figure of commol to draw on, as in `ResultsPlot.series`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the line of the mean.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            As `ResultsPlot.cumulative`; or if there are no replicates.
        KeyError
            As `ResultsPlot.cumulative`.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _replicates_cumulative

        return _replicates_cumulative(
            self._replicates,
            output_file=output_file,
            observed_data=observed_data,
            calibration_result=calibration_result,
            config=config,
            series=series,
            axes=axes,
            **kwargs,
        )

    def observations(
        self,
        observed_data: "list[ObservedDataPoint]",
        output_file: str | None = None,
        calibration_result: "CalibrationResult | None" = None,
        config: "PlotConfig | None" = None,
        show_legend: bool = True,
        position_label: Callable[[float], str] | None = None,
        tick_every: float | None = None,
        x_label: str = "Step",
        confidence_level: float = 0.95,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw each observed series with the mean of the replicates and their
        band, read through its observation operator, one panel per label.

        Each replicate is read through the operator of each observation
        first, as `ResultsPlot.observations` reads a run, then the band takes
        the interval of `confidence_level` across them
        (`member_statistics`). A band over a window is a rectangle over that
        window. The band is a band of the model, with no observation noise,
        not a prediction interval, and its legend says so.

        Parameters
        ----------
        observed_data : list[ObservedDataPoint]
            The observations, as in `ResultsPlot.observations`.
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        calibration_result : CalibrationResult | None
            The values of the factors, as in `ResultsPlot.observations`.
        config : PlotConfig | None
            Layout and style. If None, the defaults.
        show_legend : bool
            Whether each panel shows its legend.
        position_label : Callable[[float], str] | None
            Turns a position into a tick label, as in `ResultsPlot.series`.
        tick_every : float | None
            The distance between labelled positions, as in
            `ResultsPlot.series`.
        x_label : str
            The label of the x axis.
        confidence_level : float
            The level of the band, strictly between 0 and 1.
        axes : Figure | None
            A figure of commol to draw on, as in `ResultsPlot.observations`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the steps and the guide of the mean.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            As `ResultsPlot.observations`; or if there are no replicates or
            the confidence level is out of range.
        KeyError
            If an observation names an output the replicates do not have.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _replicates_observations

        return _replicates_observations(
            self._replicates,
            observed_data,
            output_file=output_file,
            calibration_result=calibration_result,
            config=config,
            show_legend=show_legend,
            position_label=position_label,
            tick_every=tick_every,
            x_label=x_label,
            confidence_level=confidence_level,
            axes=axes,
            **kwargs,
        )

Methods:

__init__ 

__init__(replicates: SimulationReplicates) -> None

The figures of replicates.

Parameters:

Name Type Description Default
replicates SimulationReplicates

The replicates.

 required
Source code in commol/api/plotting/accessors.py 
303
304
305
306
307
308
309
310
311
312
def __init__(self, replicates: "SimulationReplicates") -> None:
    """
    The figures of `replicates`.

    Parameters
    ----------
    replicates : SimulationReplicates
        The replicates.
    """
    self._replicates = replicates

series 

series(output_file: str | None = None, observed_data: list[ObservedDataPoint] | None = None, calibration_result: CalibrationResult | None = None, config: PlotConfig | None = None, series: list[str] | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', prediction_intervals: PredictionIntervals | None = None, confidence_level: float = 0.95, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw the mean of each series and the band of the replicates, one panel per series.

Each replicate is reduced to the series first, through the operator of its observations, then the band takes the interval of confidence_level across them (member_statistics).

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
observed_data list[ObservedDataPoint] | None

Observations, as in ResultsPlot.series.

 None
calibration_result CalibrationResult | None

The values of the factors, as in ResultsPlot.series.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
series list[str] | None

What to draw, as in ResultsPlot.series.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position into a tick label, as in ResultsPlot.series.

 None
tick_every float | None

The distance between labelled positions, as in ResultsPlot.series.

 None
x_label str

The label of the x axis.

 'Step'
prediction_intervals PredictionIntervals | None

Prediction intervals of a conformal method, as in ResultsPlot.series.

 None
confidence_level float

The level of the band, strictly between 0 and 1.

 0.95
axes Figure | None

A figure of commol to draw on, as in ResultsPlot.series.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of the mean.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

As ResultsPlot.series; or if there are no replicates or the confidence level is out of range.
KeyError

As ResultsPlot.series.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
def series(
    self,
    output_file: str | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    calibration_result: "CalibrationResult | None" = None,
    config: "PlotConfig | None" = None,
    series: list[str] | None = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    prediction_intervals: "PredictionIntervals | None" = None,
    confidence_level: float = 0.95,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw the mean of each series and the band of the replicates, one
    panel per series.

    Each replicate is reduced to the series first, through the operator
    of its observations, then the band takes the interval of
    `confidence_level` across them (`member_statistics`).

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    observed_data : list[ObservedDataPoint] | None
        Observations, as in `ResultsPlot.series`.
    calibration_result : CalibrationResult | None
        The values of the factors, as in `ResultsPlot.series`.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    series : list[str] | None
        What to draw, as in `ResultsPlot.series`.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position into a tick label, as in `ResultsPlot.series`.
    tick_every : float | None
        The distance between labelled positions, as in
        `ResultsPlot.series`.
    x_label : str
        The label of the x axis.
    prediction_intervals : PredictionIntervals | None
        Prediction intervals of a conformal method, as in
        `ResultsPlot.series`.
    confidence_level : float
        The level of the band, strictly between 0 and 1.
    axes : Figure | None
        A figure of commol to draw on, as in `ResultsPlot.series`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of the mean.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        As `ResultsPlot.series`; or if there are no replicates or the
        confidence level is out of range.
    KeyError
        As `ResultsPlot.series`.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _replicates_series

    return _replicates_series(
        self._replicates,
        output_file=output_file,
        observed_data=observed_data,
        calibration_result=calibration_result,
        config=config,
        series=series,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        prediction_intervals=prediction_intervals,
        confidence_level=confidence_level,
        axes=axes,
        **kwargs,
    )

cumulative 

cumulative(output_file: str | None = None, observed_data: list[ObservedDataPoint] | None = None, calibration_result: CalibrationResult | None = None, config: PlotConfig | None = None, series: list[str] | None = None, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw the running total of the mean of the replicates, as ResultsPlot.cumulative draws one run.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
observed_data list[ObservedDataPoint] | None

Observations, as in ResultsPlot.cumulative.

 None
calibration_result CalibrationResult | None

The values of the factors, as in ResultsPlot.cumulative.

 None
config PlotConfig | None

Layout, size and style. If None, the defaults.

 None
series list[str] | None

What to draw, as in ResultsPlot.series.

 None
axes Figure | None

A figure of commol to draw on, as in ResultsPlot.series.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of the mean.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

As ResultsPlot.cumulative; or if there are no replicates.
KeyError

As ResultsPlot.cumulative.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
def cumulative(
    self,
    output_file: str | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    calibration_result: "CalibrationResult | None" = None,
    config: "PlotConfig | None" = None,
    series: list[str] | None = None,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw the running total of the mean of the replicates, as
    `ResultsPlot.cumulative` draws one run.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    observed_data : list[ObservedDataPoint] | None
        Observations, as in `ResultsPlot.cumulative`.
    calibration_result : CalibrationResult | None
        The values of the factors, as in `ResultsPlot.cumulative`.
    config : PlotConfig | None
        Layout, size and style. If None, the defaults.
    series : list[str] | None
        What to draw, as in `ResultsPlot.series`.
    axes : Figure | None
        A figure of commol to draw on, as in `ResultsPlot.series`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of the mean.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        As `ResultsPlot.cumulative`; or if there are no replicates.
    KeyError
        As `ResultsPlot.cumulative`.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _replicates_cumulative

    return _replicates_cumulative(
        self._replicates,
        output_file=output_file,
        observed_data=observed_data,
        calibration_result=calibration_result,
        config=config,
        series=series,
        axes=axes,
        **kwargs,
    )

observations 

observations(observed_data: list[ObservedDataPoint], output_file: str | None = None, calibration_result: CalibrationResult | None = None, config: PlotConfig | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', confidence_level: float = 0.95, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw each observed series with the mean of the replicates and their band, read through its observation operator, one panel per label.

Each replicate is read through the operator of each observation first, as ResultsPlot.observations reads a run, then the band takes the interval of confidence_level across them (member_statistics). A band over a window is a rectangle over that window. The band is a band of the model, with no observation noise, not a prediction interval, and its legend says so.

Parameters:

Name Type Description Default
observed_data list[ObservedDataPoint]

The observations, as in ResultsPlot.observations.

 required
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
calibration_result CalibrationResult | None

The values of the factors, as in ResultsPlot.observations.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position into a tick label, as in ResultsPlot.series.

 None
tick_every float | None

The distance between labelled positions, as in ResultsPlot.series.

 None
x_label str

The label of the x axis.

 'Step'
confidence_level float

The level of the band, strictly between 0 and 1.

 0.95
axes Figure | None

A figure of commol to draw on, as in ResultsPlot.observations.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the steps and the guide of the mean.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

As ResultsPlot.observations; or if there are no replicates or the confidence level is out of range.
KeyError

If an observation names an output the replicates do not have.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def observations(
    self,
    observed_data: "list[ObservedDataPoint]",
    output_file: str | None = None,
    calibration_result: "CalibrationResult | None" = None,
    config: "PlotConfig | None" = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    confidence_level: float = 0.95,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw each observed series with the mean of the replicates and their
    band, read through its observation operator, one panel per label.

    Each replicate is read through the operator of each observation
    first, as `ResultsPlot.observations` reads a run, then the band takes
    the interval of `confidence_level` across them
    (`member_statistics`). A band over a window is a rectangle over that
    window. The band is a band of the model, with no observation noise,
    not a prediction interval, and its legend says so.

    Parameters
    ----------
    observed_data : list[ObservedDataPoint]
        The observations, as in `ResultsPlot.observations`.
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    calibration_result : CalibrationResult | None
        The values of the factors, as in `ResultsPlot.observations`.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position into a tick label, as in `ResultsPlot.series`.
    tick_every : float | None
        The distance between labelled positions, as in
        `ResultsPlot.series`.
    x_label : str
        The label of the x axis.
    confidence_level : float
        The level of the band, strictly between 0 and 1.
    axes : Figure | None
        A figure of commol to draw on, as in `ResultsPlot.observations`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the steps and the guide of the mean.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        As `ResultsPlot.observations`; or if there are no replicates or
        the confidence level is out of range.
    KeyError
        If an observation names an output the replicates do not have.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _replicates_observations

    return _replicates_observations(
        self._replicates,
        observed_data,
        output_file=output_file,
        calibration_result=calibration_result,
        config=config,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        confidence_level=confidence_level,
        axes=axes,
        **kwargs,
    )

PredictivePlot

The figures of a predictive, read from predictive.plot.

Each panel shows the weighted median of the draws and their band, with no other run; the model of the source names the series.

Source code in commol/api/plotting/accessors.py 
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
class PredictivePlot:
    """
    The figures of a predictive, read from ``predictive.plot``.

    Each panel shows the weighted median of the draws and their band, with no
    other run; the model of the source names the series.
    """

    def __init__(self, predictive: "Predictive") -> None:
        """
        The figures of `predictive`.

        Parameters
        ----------
        predictive : Predictive
            The predictive.
        """
        self._predictive = predictive

    def series(
        self,
        output_file: str | None = None,
        observed_data: "list[ObservedDataPoint] | None" = None,
        config: "PlotConfig | None" = None,
        series: list[str] | None = None,
        show_legend: bool = True,
        position_label: Callable[[float], str] | None = None,
        tick_every: float | None = None,
        x_label: str = "Step",
        prediction_intervals: "PredictionIntervals | None" = None,
        confidence_level: float = 0.95,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw the weighted median of the draws of each series and their band,
        one panel per series.

        Each draw is read through the observation operator of the problem
        (the sums, windows and factors of the observations of the series,
        each at its own position when they do not share one operator with no
        window), then the draws are reduced with their weights.

        Parameters
        ----------
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        observed_data : list[ObservedDataPoint] | None
            Observations, each drawn as a point on the panel of its label;
            they set the operator each draw is read through.
        config : PlotConfig | None
            Layout and style. If None, the defaults.
        series : list[str] | None
            What to draw, as in `ResultsPlot.series`.
        show_legend : bool
            Whether each panel shows its legend.
        position_label : Callable[[float], str] | None
            Turns a position into a tick label, as in `ResultsPlot.series`.
        tick_every : float | None
            The distance between labelled positions, as in
            `ResultsPlot.series`.
        x_label : str
            The label of the x axis.
        prediction_intervals : PredictionIntervals | None
            Prediction intervals of a conformal method, as in
            `ResultsPlot.series`.
        confidence_level : float
            The level of the band, strictly between 0 and 1.
        axes : Figure | None
            A figure of commol to draw on, as in `ResultsPlot.series`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the line of the median.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            If an observation names an unknown output or factor, the
            confidence level is out of range, or ``axes`` has no panel of a
            series.
        KeyError
            If an entry of ``series`` is neither an output nor a bin or
            accumulator id of the model.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _predictive_series

        return _predictive_series(
            self._predictive,
            output_file=output_file,
            observed_data=observed_data,
            config=config,
            series=series,
            show_legend=show_legend,
            position_label=position_label,
            tick_every=tick_every,
            x_label=x_label,
            prediction_intervals=prediction_intervals,
            confidence_level=confidence_level,
            axes=axes,
            **kwargs,
        )

    def cumulative(
        self,
        output_file: str | None = None,
        observed_data: "list[ObservedDataPoint] | None" = None,
        config: "PlotConfig | None" = None,
        series: list[str] | None = None,
        confidence_level: float = 0.95,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw the weighted median and the band of the running total of each
        series across the draws, one panel per series.

        Parameters
        ----------
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        observed_data : list[ObservedDataPoint] | None
            Observations, drawn as their running total on the panel of their
            label. An observation with a factor is divided by the weighted
            median of that factor in the sample.
        config : PlotConfig | None
            Layout, size and style. If None, the defaults.
        series : list[str] | None
            What to draw, as in `ResultsPlot.series`.
        confidence_level : float
            The level of the band, strictly between 0 and 1.
        axes : Figure | None
            A figure of commol to draw on, as in `ResultsPlot.series`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the line of the median.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            If the confidence level is out of range, or ``axes`` has no panel
            of a series.
        KeyError
            If an entry of ``series`` is neither an output nor a bin or
            accumulator id of the model.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _predictive_cumulative

        return _predictive_cumulative(
            self._predictive,
            output_file=output_file,
            observed_data=observed_data,
            config=config,
            series=series,
            confidence_level=confidence_level,
            axes=axes,
            **kwargs,
        )

    def observations(
        self,
        observed_data: "list[ObservedDataPoint]",
        output_file: str | None = None,
        config: "PlotConfig | None" = None,
        show_legend: bool = True,
        position_label: Callable[[float], str] | None = None,
        tick_every: float | None = None,
        x_label: str = "Step",
        confidence_level: float = 0.95,
        axes: "Figure | None" = None,
        **kwargs: str | int | float | bool | None,
    ) -> "Figure":
        """
        Draw each observed series with the weighted median of the draws and
        their band, read through its observation operator, one panel per
        label.

        The values are those of ``at_observations(observed_data, NoNoise())``:
        each draw's value of each observation through its own operator (the
        sum of its outputs, its window and the draw's value of its factor),
        the values the loss compares. A value with a window is drawn as a
        step over its window with a marker at ``at``, and its band as a
        rectangle over the same window; a value with no window is a marker,
        joined only as a guide. The band is a band of the model, with no
        observation noise, not a prediction interval, and its legend says so.

        Parameters
        ----------
        observed_data : list[ObservedDataPoint]
            The observations, as in `ResultsPlot.observations`.
        output_file : str | None
            Path to save the figure to. If None, the figure is only returned.
        config : PlotConfig | None
            Layout and style. If None, the defaults.
        show_legend : bool
            Whether each panel shows its legend.
        position_label : Callable[[float], str] | None
            Turns a position into a tick label, as in `ResultsPlot.series`.
        tick_every : float | None
            The distance between labelled positions, as in
            `ResultsPlot.series`.
        x_label : str
            The label of the x axis.
        confidence_level : float
            The level of the band, strictly between 0 and 1.
        axes : Figure | None
            A figure of commol to draw on, as in `ResultsPlot.observations`.
        **kwargs : str | int | float | bool | None
            Passed to ``Axes.plot`` for the steps and the guide of the median.

        Returns
        -------
        Figure
            The matplotlib figure.

        Raises
        ------
        ValueError
            If there are no observations, an observation names an unknown
            output or factor, the confidence level is out of range, or
            ``axes`` has no panel of a label.
        ImportError
            If matplotlib is not installed (``pip install 'commol[plot]'``).
        """
        from commol.api.plotting.figures import _predictive_observations

        return _predictive_observations(
            self._predictive,
            observed_data,
            output_file=output_file,
            config=config,
            show_legend=show_legend,
            position_label=position_label,
            tick_every=tick_every,
            x_label=x_label,
            confidence_level=confidence_level,
            axes=axes,
            **kwargs,
        )

Methods:

__init__ 

__init__(predictive: Predictive) -> None

The figures of predictive.

Parameters:

Name Type Description Default
predictive Predictive

The predictive.

 required
Source code in commol/api/plotting/accessors.py 
553
554
555
556
557
558
559
560
561
562
def __init__(self, predictive: "Predictive") -> None:
    """
    The figures of `predictive`.

    Parameters
    ----------
    predictive : Predictive
        The predictive.
    """
    self._predictive = predictive

series 

series(output_file: str | None = None, observed_data: list[ObservedDataPoint] | None = None, config: PlotConfig | None = None, series: list[str] | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', prediction_intervals: PredictionIntervals | None = None, confidence_level: float = 0.95, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw the weighted median of the draws of each series and their band, one panel per series.

Each draw is read through the observation operator of the problem (the sums, windows and factors of the observations of the series, each at its own position when they do not share one operator with no window), then the draws are reduced with their weights.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
observed_data list[ObservedDataPoint] | None

Observations, each drawn as a point on the panel of its label; they set the operator each draw is read through.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
series list[str] | None

What to draw, as in ResultsPlot.series.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position into a tick label, as in ResultsPlot.series.

 None
tick_every float | None

The distance between labelled positions, as in ResultsPlot.series.

 None
x_label str

The label of the x axis.

 'Step'
prediction_intervals PredictionIntervals | None

Prediction intervals of a conformal method, as in ResultsPlot.series.

 None
confidence_level float

The level of the band, strictly between 0 and 1.

 0.95
axes Figure | None

A figure of commol to draw on, as in ResultsPlot.series.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of the median.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If an observation names an unknown output or factor, the confidence level is out of range, or axes has no panel of a series.
KeyError

If an entry of series is neither an output nor a bin or accumulator id of the model.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
def series(
    self,
    output_file: str | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    config: "PlotConfig | None" = None,
    series: list[str] | None = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    prediction_intervals: "PredictionIntervals | None" = None,
    confidence_level: float = 0.95,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw the weighted median of the draws of each series and their band,
    one panel per series.

    Each draw is read through the observation operator of the problem
    (the sums, windows and factors of the observations of the series,
    each at its own position when they do not share one operator with no
    window), then the draws are reduced with their weights.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    observed_data : list[ObservedDataPoint] | None
        Observations, each drawn as a point on the panel of its label;
        they set the operator each draw is read through.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    series : list[str] | None
        What to draw, as in `ResultsPlot.series`.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position into a tick label, as in `ResultsPlot.series`.
    tick_every : float | None
        The distance between labelled positions, as in
        `ResultsPlot.series`.
    x_label : str
        The label of the x axis.
    prediction_intervals : PredictionIntervals | None
        Prediction intervals of a conformal method, as in
        `ResultsPlot.series`.
    confidence_level : float
        The level of the band, strictly between 0 and 1.
    axes : Figure | None
        A figure of commol to draw on, as in `ResultsPlot.series`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of the median.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If an observation names an unknown output or factor, the
        confidence level is out of range, or ``axes`` has no panel of a
        series.
    KeyError
        If an entry of ``series`` is neither an output nor a bin or
        accumulator id of the model.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _predictive_series

    return _predictive_series(
        self._predictive,
        output_file=output_file,
        observed_data=observed_data,
        config=config,
        series=series,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        prediction_intervals=prediction_intervals,
        confidence_level=confidence_level,
        axes=axes,
        **kwargs,
    )

cumulative 

cumulative(output_file: str | None = None, observed_data: list[ObservedDataPoint] | None = None, config: PlotConfig | None = None, series: list[str] | None = None, confidence_level: float = 0.95, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw the weighted median and the band of the running total of each series across the draws, one panel per series.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
observed_data list[ObservedDataPoint] | None

Observations, drawn as their running total on the panel of their label. An observation with a factor is divided by the weighted median of that factor in the sample.

 None
config PlotConfig | None

Layout, size and style. If None, the defaults.

 None
series list[str] | None

What to draw, as in ResultsPlot.series.

 None
confidence_level float

The level of the band, strictly between 0 and 1.

 0.95
axes Figure | None

A figure of commol to draw on, as in ResultsPlot.series.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of the median.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If the confidence level is out of range, or axes has no panel of a series.
KeyError

If an entry of series is neither an output nor a bin or accumulator id of the model.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
def cumulative(
    self,
    output_file: str | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    config: "PlotConfig | None" = None,
    series: list[str] | None = None,
    confidence_level: float = 0.95,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw the weighted median and the band of the running total of each
    series across the draws, one panel per series.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    observed_data : list[ObservedDataPoint] | None
        Observations, drawn as their running total on the panel of their
        label. An observation with a factor is divided by the weighted
        median of that factor in the sample.
    config : PlotConfig | None
        Layout, size and style. If None, the defaults.
    series : list[str] | None
        What to draw, as in `ResultsPlot.series`.
    confidence_level : float
        The level of the band, strictly between 0 and 1.
    axes : Figure | None
        A figure of commol to draw on, as in `ResultsPlot.series`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of the median.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If the confidence level is out of range, or ``axes`` has no panel
        of a series.
    KeyError
        If an entry of ``series`` is neither an output nor a bin or
        accumulator id of the model.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _predictive_cumulative

    return _predictive_cumulative(
        self._predictive,
        output_file=output_file,
        observed_data=observed_data,
        config=config,
        series=series,
        confidence_level=confidence_level,
        axes=axes,
        **kwargs,
    )

observations 

observations(observed_data: list[ObservedDataPoint], output_file: str | None = None, config: PlotConfig | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', confidence_level: float = 0.95, axes: Figure | None = None, **kwargs: str | int | float | bool | None) -> Figure

Draw each observed series with the weighted median of the draws and their band, read through its observation operator, one panel per label.

The values are those of at_observations(observed_data, NoNoise()): each draw's value of each observation through its own operator (the sum of its outputs, its window and the draw's value of its factor), the values the loss compares. A value with a window is drawn as a step over its window with a marker at at, and its band as a rectangle over the same window; a value with no window is a marker, joined only as a guide. The band is a band of the model, with no observation noise, not a prediction interval, and its legend says so.

Parameters:

Name Type Description Default
observed_data list[ObservedDataPoint]

The observations, as in ResultsPlot.observations.

 required
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position into a tick label, as in ResultsPlot.series.

 None
tick_every float | None

The distance between labelled positions, as in ResultsPlot.series.

 None
x_label str

The label of the x axis.

 'Step'
confidence_level float

The level of the band, strictly between 0 and 1.

 0.95
axes Figure | None

A figure of commol to draw on, as in ResultsPlot.observations.

 None
**kwargs str | int | float | bool | None

Passed to Axes.plot for the steps and the guide of the median.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If there are no observations, an observation names an unknown output or factor, the confidence level is out of range, or axes has no panel of a label.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/api/plotting/accessors.py 
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
def observations(
    self,
    observed_data: "list[ObservedDataPoint]",
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    confidence_level: float = 0.95,
    axes: "Figure | None" = None,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw each observed series with the weighted median of the draws and
    their band, read through its observation operator, one panel per
    label.

    The values are those of ``at_observations(observed_data, NoNoise())``:
    each draw's value of each observation through its own operator (the
    sum of its outputs, its window and the draw's value of its factor),
    the values the loss compares. A value with a window is drawn as a
    step over its window with a marker at ``at``, and its band as a
    rectangle over the same window; a value with no window is a marker,
    joined only as a guide. The band is a band of the model, with no
    observation noise, not a prediction interval, and its legend says so.

    Parameters
    ----------
    observed_data : list[ObservedDataPoint]
        The observations, as in `ResultsPlot.observations`.
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position into a tick label, as in `ResultsPlot.series`.
    tick_every : float | None
        The distance between labelled positions, as in
        `ResultsPlot.series`.
    x_label : str
        The label of the x axis.
    confidence_level : float
        The level of the band, strictly between 0 and 1.
    axes : Figure | None
        A figure of commol to draw on, as in `ResultsPlot.observations`.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the steps and the guide of the median.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If there are no observations, an observation names an unknown
        output or factor, the confidence level is out of range, or
        ``axes`` has no panel of a label.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _predictive_observations

    return _predictive_observations(
        self._predictive,
        observed_data,
        output_file=output_file,
        config=config,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        confidence_level=confidence_level,
        axes=axes,
        **kwargs,
    )

plot_compared 

plot_compared(results: Mapping[str, SimulationResults | SimulationReplicates | Predictive], series: list[str] | None = None, window: float | None = None, observed_data: list[ObservedDataPoint] | None = None, panels: Literal['series', 'observations'] = 'series', axes: Figure | None = None, output_file: str | None = None, config: PlotConfig | None = None, show_legend: bool = True, position_label: Callable[[float], str] | None = None, tick_every: float | None = None, x_label: str = 'Step', confidence_level: float = 0.95, **kwargs: str | int | float | bool | None) -> Figure

Draw several results of the same model on the same panels, one panel per series or one per observed series.

Each panel has one line per result, labelled with its key and in the same color in every panel (C0 for the first key, C1 for the second, …). Replicates show their mean and the band of the replicates, and a predictive the weighted median of its draws and their band, in the color of their key. The observations are drawn once.

Parameters:

Name Type Description Default
results Mapping[str, SimulationResults | SimulationReplicates | Predictive]

The results, by the label of their lines. Each has the outputs of the first; the model of the first names the series.

 required
series list[str] | None

What to draw, one panel each, as in ResultsPlot.series. If None, every output. Only with panels="series".

 None
window float | None

The length of a window on the axis. Each line is then the gain of the series over each complete window, as Simulation.windowed_totals reads it, at the end of the window; a band is the band of these gains. If None, each line is the line of the plot.series of its result with observed_data. Only with panels="series".

 None
observed_data list[ObservedDataPoint] | None

Observations, each drawn once as a point on the panel of its label. Without window, they also set how each line is read, as in ResultsPlot.series.

 None
panels Literal['series', 'observations']

"series": one panel per entry of series. "observations": one panel per label of observed_data, with each result read only at the observations, through the observation operator of each one, as ResultsPlot.observations reads one result.

 'series'
axes Figure | None

A figure of commol to draw on: each series is drawn on its panel, the Axes whose label is the id of the series (or the label of the observed series). If None, a new figure.

 None
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
show_legend bool

Whether each panel shows its legend.

 True
position_label Callable[[float], str] | None

Turns a position into a tick label, as in ResultsPlot.series.

 None
tick_every float | None

The distance between labelled positions, as in ResultsPlot.series.

 None
x_label str

The label of the x axis.

 'Step'
confidence_level float

The level of the bands of replicates and predictives, strictly between 0 and 1.

 0.95
**kwargs str | int | float | bool | None

Passed to Axes.plot for the line of each result, such as linewidth.

 {}

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If there are no results; a result does not have the outputs of the first (the message names its key and the outputs that differ); window is not positive; the confidence level is out of range; axes has no panel of a series; panels is neither "series" nor "observations"; or, with panels="observations", series or window is given, there are no observations, or a result has no value at the position of an observation or at the start of its window.
KeyError

If an entry of series is neither an output nor a bin or accumulator id of the model.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').

Examples:

>>> figure = plot_compared({"k1 = 0.3": results, "k1 = 0.5": faster})
>>> checked = plot_compared(
...     {"k1 = 0.3": results, "k1 = 0.5": faster},
...     observed_data=observed,
...     panels="observations",
... )
Source code in commol/api/plotting/compared.py 
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def plot_compared(
    results: "Mapping[str, SimulationResults | SimulationReplicates | Predictive]",
    series: list[str] | None = None,
    window: float | None = None,
    observed_data: "list[ObservedDataPoint] | None" = None,
    panels: Literal["series", "observations"] = "series",
    axes: "Figure | None" = None,
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    show_legend: bool = True,
    position_label: Callable[[float], str] | None = None,
    tick_every: float | None = None,
    x_label: str = "Step",
    confidence_level: float = 0.95,
    **kwargs: str | int | float | bool | None,
) -> "Figure":
    """
    Draw several results of the same model on the same panels, one panel per
    series or one per observed series.

    Each panel has one line per result, labelled with its key and in the
    same color in every panel (``C0`` for the first key, ``C1`` for the
    second, …). Replicates show their mean and the band of the replicates,
    and a predictive the weighted median of its draws and their band, in the
    color of their key. The observations are drawn once.

    Parameters
    ----------
    results : Mapping[str, SimulationResults | SimulationReplicates | Predictive]
        The results, by the label of their lines. Each has the outputs of
        the first; the model of the first names the series.
    series : list[str] | None
        What to draw, one panel each, as in ``ResultsPlot.series``. If None,
        every output. Only with ``panels="series"``.
    window : float | None
        The length of a window on the axis. Each line is then the gain of
        the series over each complete window, as `Simulation.windowed_totals`
        reads it, at the end of the window; a band is the band of these
        gains. If None, each line is the line of the ``plot.series`` of its
        result with `observed_data`. Only with ``panels="series"``.
    observed_data : list[ObservedDataPoint] | None
        Observations, each drawn once as a point on the panel of its label.
        Without `window`, they also set how each line is read, as in
        ``ResultsPlot.series``.
    panels : Literal["series", "observations"]
        ``"series"``: one panel per entry of `series`. ``"observations"``:
        one panel per label of `observed_data`, with each result read only
        at the observations, through the observation operator of each one,
        as ``ResultsPlot.observations`` reads one result.
    axes : Figure | None
        A figure of commol to draw on: each series is drawn on its panel,
        the `Axes` whose label is the id of the series (or the label of the
        observed series). If None, a new figure.
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    show_legend : bool
        Whether each panel shows its legend.
    position_label : Callable[[float], str] | None
        Turns a position into a tick label, as in ``ResultsPlot.series``.
    tick_every : float | None
        The distance between labelled positions, as in
        ``ResultsPlot.series``.
    x_label : str
        The label of the x axis.
    confidence_level : float
        The level of the bands of replicates and predictives, strictly
        between 0 and 1.
    **kwargs : str | int | float | bool | None
        Passed to ``Axes.plot`` for the line of each result, such as
        ``linewidth``.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If there are no results; a result does not have the outputs of the
        first (the message names its key and the outputs that differ);
        `window` is not positive; the confidence level is out of range;
        ``axes`` has no panel of a series; `panels` is neither ``"series"``
        nor ``"observations"``; or, with ``panels="observations"``, `series`
        or `window` is given, there are no observations, or a result has no
        value at the position of an observation or at the start of its
        window.
    KeyError
        If an entry of ``series`` is neither an output nor a bin or
        accumulator id of the model.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).

    Examples
    --------
    >>> figure = plot_compared({"k1 = 0.3": results, "k1 = 0.5": faster})
    >>> checked = plot_compared(
    ...     {"k1 = 0.3": results, "k1 = 0.5": faster},
    ...     observed_data=observed,
    ...     panels="observations",
    ... )
    """
    from commol.api.plotting.figures import _compared_series

    return _compared_series(
        results,
        series=series,
        window=window,
        observed_data=observed_data,
        panels=panels,
        axes=axes,
        output_file=output_file,
        config=config,
        show_legend=show_legend,
        position_label=position_label,
        tick_every=tick_every,
        x_label=x_label,
        confidence_level=confidence_level,
        **kwargs,
    )

plot 

plot(output_file: str | None = None, config: PlotConfig | None = None, x_label: str = 'Step', axes: Figure | None = None) -> Figure

Draw the PRCC of each input: one panel per series.

A series of a Trajectory draws one line per input over its positions; any other quantity draws one bar per input.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
x_label str

The label of the x axis of a series over positions.

 'Step'
axes Figure | None

A figure of commol to draw on: each panel is the Axes whose label is the name of its series. If None, a new figure.

 None

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If axes has no panel of a series.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/context/inference/global_sensitivity.py 
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
def plot(
    self,
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    x_label: str = "Step",
    axes: "Figure | None" = None,
) -> "Figure":
    """
    Draw the PRCC of each input: one panel per series.

    A series of a `Trajectory` draws one line per input over its
    positions; any other quantity draws one bar per input.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    x_label : str
        The label of the x axis of a series over positions.
    axes : Figure | None
        A figure of commol to draw on: each panel is the `Axes` whose
        label is the name of its series. If None, a new figure.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If ``axes`` has no panel of a series.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _prcc

    return _prcc(
        self, output_file=output_file, config=config, x_label=x_label, axes=axes
    )

plot 

plot(output_file: str | None = None, config: PlotConfig | None = None, axes: Figure | None = None) -> Figure

Draw σ against μ* of each input: one panel per quantity, one labelled point per input.

An input far to the right matters; one high up acts through interactions or a non-linear effect.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
axes Figure | None

A figure of commol to draw on: each panel is the Axes whose label is the label of its quantity. If None, a new figure.

 None

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If axes has no panel of a quantity.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/context/inference/global_sensitivity.py 
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
def plot(
    self,
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    axes: "Figure | None" = None,
) -> "Figure":
    """
    Draw ``σ`` against ``μ*`` of each input: one panel per quantity,
    one labelled point per input.

    An input far to the right matters; one high up acts through
    interactions or a non-linear effect.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    axes : Figure | None
        A figure of commol to draw on: each panel is the `Axes` whose
        label is the label of its quantity. If None, a new figure.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If ``axes`` has no panel of a quantity.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _morris

    return _morris(self, output_file=output_file, config=config, axes=axes)

plot 

plot(output_file: str | None = None, config: PlotConfig | None = None, axes: Figure | None = None) -> Figure

Draw the first-order and total Sobol indices: one panel per quantity, one pair of bars per input, with their intervals.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
axes Figure | None

A figure of commol to draw on: each panel is the Axes whose label is the label of its quantity. If None, a new figure.

 None

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If axes has no panel of a quantity.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/context/inference/global_sensitivity.py 
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
def plot(
    self,
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    axes: "Figure | None" = None,
) -> "Figure":
    """
    Draw the first-order and total Sobol indices: one panel per
    quantity, one pair of bars per input, with their intervals.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    axes : Figure | None
        A figure of commol to draw on: each panel is the `Axes` whose
        label is the label of its quantity. If None, a new figure.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If ``axes`` has no panel of a quantity.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _sobol

    return _sobol(self, output_file=output_file, config=config, axes=axes)

plot 

plot(output_file: str | None = None, config: PlotConfig | None = None, axes: Figure | None = None) -> Figure

Draw the first-order and total Sobol indices of the expansion: one panel per quantity, one pair of bars per input.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
axes Figure | None

A figure of commol to draw on: each panel is the Axes whose label is the label of its quantity. If None, a new figure.

 None

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If axes has no panel of a quantity.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/context/inference/global_sensitivity.py 
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
def plot(
    self,
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    axes: "Figure | None" = None,
) -> "Figure":
    """
    Draw the first-order and total Sobol indices of the expansion: one
    panel per quantity, one pair of bars per input.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    axes : Figure | None
        A figure of commol to draw on: each panel is the `Axes` whose
        label is the label of its quantity. If None, a new figure.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If ``axes`` has no panel of a quantity.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _sobol

    return _sobol(self, output_file=output_file, config=config, axes=axes)

plot 

plot(output_file: str | None = None, config: PlotConfig | None = None, axes: Figure | None = None) -> Figure

Draw each profile: one panel per parameter or prediction, with the statistic of each point, the threshold, and the ends of the interval.

A profile that stays under the threshold up to a bound is open on that side; a flat one stays near 0 over its whole range.

Parameters:

Name Type Description Default
output_file str | None

Path to save the figure to. If None, the figure is only returned.

 None
config PlotConfig | None

Layout and style. If None, the defaults.

 None
axes Figure | None

A figure of commol to draw on: each panel is the Axes whose label is the name of its profile. If None, a new figure.

 None

Returns:

Type Description
Figure

The matplotlib figure.

Raises:

Type Description
ValueError

If axes has no panel of a profile.
ImportError

If matplotlib is not installed (pip install 'commol[plot]').
Source code in commol/context/inference/profiles.py 
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
def plot(
    self,
    output_file: str | None = None,
    config: "PlotConfig | None" = None,
    axes: "Figure | None" = None,
) -> "Figure":
    """
    Draw each profile: one panel per parameter or prediction, with the
    statistic of each point, the threshold, and the ends of the interval.

    A profile that stays under the threshold up to a bound is open on that
    side; a flat one stays near 0 over its whole range.

    Parameters
    ----------
    output_file : str | None
        Path to save the figure to. If None, the figure is only returned.
    config : PlotConfig | None
        Layout and style. If None, the defaults.
    axes : Figure | None
        A figure of commol to draw on: each panel is the `Axes` whose
        label is the name of its profile. If None, a new figure.

    Returns
    -------
    Figure
        The matplotlib figure.

    Raises
    ------
    ValueError
        If ``axes`` has no panel of a profile.
    ImportError
        If matplotlib is not installed (``pip install 'commol[plot]'``).
    """
    from commol.api.plotting.figures import _profiles

    return _profiles(self, output_file=output_file, config=config, axes=axes)

PlotConfig

Bases: BaseModel

Configuration for plot layout and styling.

Attributes:

Name Type Description
figsize tuple[float, float]

Figure size in inches (width, height), of a figure of running totals; the other figures take their size from their panels.
dpi int

Dots per inch for figure resolution.
layout tuple[int, int] | None

Panel layout as (rows, cols). If None, computed from the number of panels.
style str | list[str] | None

A matplotlib style, or a list of styles applied in order: a name of matplotlib.style.available (such as "ggplot" or "seaborn-v0_8-whitegrid") or the path of a style file. See: https://matplotlib.org/stable/users/explain/customizing.html
Notes

The style applies to the figure of one call only: after the call, matplotlib.rcParams is as it was before it, so the figures that you draw with matplotlib keep your style. Given axes=, a figure draws on the panels of an earlier figure, and figsize, dpi and layout are those of that figure.

Examples:

>>> # Direct configuration
>>> config = PlotConfig(style=["seaborn-v0_8-whitegrid", "seaborn-v0_8-talk"])

>>> # Using presets
>>> config = PlotConfig.presentation()
>>> config = PlotConfig.publication()
Source code in commol/context/visualization.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
class PlotConfig(BaseModel):
    """
    Configuration for plot layout and styling.

    Attributes
    ----------
    figsize : tuple[float, float]
        Figure size in inches (width, height), of a figure of running totals;
        the other figures take their size from their panels.
    dpi : int
        Dots per inch for figure resolution.
    layout : tuple[int, int] | None
        Panel layout as (rows, cols). If None, computed from the number of
        panels.
    style : str | list[str] | None
        A matplotlib style, or a list of styles applied in order: a name of
        ``matplotlib.style.available`` (such as ``"ggplot"`` or
        ``"seaborn-v0_8-whitegrid"``) or the path of a style file.
        See: https://matplotlib.org/stable/users/explain/customizing.html

    Notes
    -----
    The style applies to the figure of one call only: after the call,
    ``matplotlib.rcParams`` is as it was before it, so the figures that you
    draw with matplotlib keep your style. Given ``axes=``, a figure draws on
    the panels of an earlier figure, and `figsize`, `dpi` and `layout` are
    those of that figure.

    Examples
    --------
    >>> # Direct configuration
    >>> config = PlotConfig(style=["seaborn-v0_8-whitegrid", "seaborn-v0_8-talk"])

    >>> # Using presets
    >>> config = PlotConfig.presentation()
    >>> config = PlotConfig.publication()
    """

    model_config = ConfigDict(extra="forbid")

    figsize: tuple[float, float] = Field(
        default=(12, 8),
        description="Figure size in inches (width, height)",
    )
    dpi: int = Field(
        default=100,
        description="Dots per inch for figure resolution",
    )
    layout: tuple[int, int] | None = Field(
        default=None,
        description="Panel layout as (rows, cols). If None, computed.",
    )
    style: str | list[str] | None = Field(
        default=None,
        description="A matplotlib style, or styles applied in order",
    )

    @classmethod
    def presentation(cls) -> Self:
        """
        Create a configuration optimized for presentations.

        Large figure size, high DPI, a white grid, the large text of the
        "talk" style and a palette for colour-blind readers.

        Returns
        -------
        PlotConfig
            Configuration with presentation-friendly settings.
        """
        return cls(
            figsize=(16, 10),
            dpi=150,
            style=[
                "seaborn-v0_8-whitegrid",
                "seaborn-v0_8-talk",
                "seaborn-v0_8-colorblind",
            ],
        )

    @classmethod
    def publication(cls) -> Self:
        """
        Create a configuration optimized for academic publications.

        Smaller figure size suitable for journal columns, high DPI for print
        quality, ticks and the small text of the "paper" style.

        Returns
        -------
        PlotConfig
            Configuration with publication-friendly settings.
        """
        return cls(
            figsize=(8, 6),
            dpi=300,
            style=["seaborn-v0_8-ticks", "seaborn-v0_8-paper"],
        )

    @classmethod
    def notebook(cls) -> Self:
        """
        Create a configuration optimized for Jupyter notebooks.

        Balanced defaults for interactive exploration.

        Returns
        -------
        PlotConfig
            Configuration with notebook-friendly settings.
        """
        return cls(
            figsize=(12, 8),
            dpi=100,
            style=["seaborn-v0_8-whitegrid", "seaborn-v0_8-notebook"],
        )

Methods:

presentation classmethod 

presentation() -> Self

Create a configuration optimized for presentations.

Large figure size, high DPI, a white grid, the large text of the "talk" style and a palette for colour-blind readers.

Returns:

Type Description
PlotConfig

Configuration with presentation-friendly settings.
Source code in commol/context/visualization.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@classmethod
def presentation(cls) -> Self:
    """
    Create a configuration optimized for presentations.

    Large figure size, high DPI, a white grid, the large text of the
    "talk" style and a palette for colour-blind readers.

    Returns
    -------
    PlotConfig
        Configuration with presentation-friendly settings.
    """
    return cls(
        figsize=(16, 10),
        dpi=150,
        style=[
            "seaborn-v0_8-whitegrid",
            "seaborn-v0_8-talk",
            "seaborn-v0_8-colorblind",
        ],
    )

publication classmethod 

publication() -> Self

Create a configuration optimized for academic publications.

Smaller figure size suitable for journal columns, high DPI for print quality, ticks and the small text of the "paper" style.

Returns:

Type Description
PlotConfig

Configuration with publication-friendly settings.
Source code in commol/context/visualization.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@classmethod
def publication(cls) -> Self:
    """
    Create a configuration optimized for academic publications.

    Smaller figure size suitable for journal columns, high DPI for print
    quality, ticks and the small text of the "paper" style.

    Returns
    -------
    PlotConfig
        Configuration with publication-friendly settings.
    """
    return cls(
        figsize=(8, 6),
        dpi=300,
        style=["seaborn-v0_8-ticks", "seaborn-v0_8-paper"],
    )

notebook classmethod 

notebook() -> Self

Create a configuration optimized for Jupyter notebooks.

Balanced defaults for interactive exploration.

Returns:

Type Description
PlotConfig

Configuration with notebook-friendly settings.
Source code in commol/context/visualization.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
@classmethod
def notebook(cls) -> Self:
    """
    Create a configuration optimized for Jupyter notebooks.

    Balanced defaults for interactive exploration.

    Returns
    -------
    PlotConfig
        Configuration with notebook-friendly settings.
    """
    return cls(
        figsize=(12, 8),
        dpi=100,
        style=["seaborn-v0_8-whitegrid", "seaborn-v0_8-notebook"],
    )