Skip to content

Figures

The figure families, the runs they read, and the drawing kernel that writes SVG and TikZ.

dispatchatlas.analysis.figures

Figures of campaign results, as SVG and as TikZ, without a plotting library.

Write every figure of a campaign at once:

from dispatchatlas.analysis import load_dataset
from dispatchatlas.analysis.figures import render_figures

paths = render_figures(load_dataset("results/my-campaign"), "figures")

or compute one figure's data and draw it:

from dispatchatlas.analysis.figures import performance_profile, plot_performance_profile

figure = plot_performance_profile(performance_profile(records))
svg, tex = figure.svg(), figure.tex()

The families, in CATALOG order: performance profiles (Dolan and Moré 2002), data profiles (Moré and Wild 2009), runtime distributions over quality targets (Hansen et al. 2022), convergence over evaluations and over time, the critical-difference diagram (Demšar 2006), box plots of relative deviations, Pareto fronts as attainment surfaces (Fonseca and Fleming 1996), and the Gantt chart of one schedule.

The modules:

dispatchatlas.analysis.figures.catalog

The figure catalog, and the function that writes every figure of a campaign.

CATALOG is the one list of figure families: each FigureSpec names a family, describes it, cites its method, and draws it from a FigureContext: the runs of one protocol, the analysis settings, and the theme. render_figures() writes every figure whose inputs are present, in both formats, under stable file names: <name>.svg and <name>.tex, where the name is the family id, or, for the Pareto fronts, pareto-front-<problem>; family_of() maps a name back to its family. A family whose inputs are absent, such as fronts in a campaign of single-objective problems, writes nothing.

The settings make the figures read what the tables of the same analysis read: the protocol, solvers, and problems it selects, and the objective and sense it analyses. The critical-difference diagram also follows its statistic, omnibus test, and significance level.

FORMATS module-attribute

FORMATS: tuple[str, ...] = ('svg', 'tex')

The formats figures are written in.

CATALOG module-attribute

CATALOG: tuple[FigureSpec, ...] = (FigureSpec('performance-profile', 'Performance profile', "For each solver, the share of problems on which its median run comes within a factor tau of the best solver's value; failed runs never do. With more than two solvers the profile compares each solver with the best one only.", _performance, ('dolan2002benchmarking', 'gould2016note')), FigureSpec('data-profile', 'Data profile', 'For each solver, the share of problems its median run solves to accuracy 0.001 within a budget of evaluations per task plus one.', _data, ('more2009benchmarking',)), FigureSpec('runtime-ecdf', 'Runtime to reach quality targets', 'For each solver, the share of (problem, quality target) pairs its runs reach within a given time, with targets between the best value found and the worst first value.', _runtime, ('hansen2022anytime',)), FigureSpec('convergence-evaluations', 'Convergence over evaluations', 'Median gap to the best value found, with its interquartile range, against the evaluations spent.', _convergence('evaluations')), FigureSpec('convergence-time', 'Convergence over time', 'Median gap to the best value found, with its interquartile range, against the elapsed time.', _convergence('time')), FigureSpec('critical-difference', 'Critical-difference diagram', 'Average ranks over the problems every solver is planned on; solvers the Nemenyi test does not separate are joined by a bar.', _critical_difference, ('demsar2006statistical',)), FigureSpec('distribution', 'Relative deviation from the best value found', "Box plots of each solver's relative percentage deviation from the best value found, over its succeeded runs, with the number of succeeded runs.", _distribution, ('hyndman1996sample',)), FigureSpec('pareto-fronts', 'Pareto fronts', "For each problem with two objectives, the median attainment surface of each solver's runs.", _pareto, ('fonseca1996performance',), prefix='pareto-front-'), FigureSpec('gantt', 'Gantt chart', 'The best recorded schedule on the first problem, one row per task, coloured by mode.', _gantt))

Every figure family, in the order figures are written.

FigureContext dataclass

FigureContext(observations: Observations, config: AnalysisConfig = AnalysisConfig(), theme: Theme = DEFAULT_THEME)

What a figure family draws from.

Attributes:

Name Type Description
observations Observations

The runs of one protocol, read for the analysed objective.

config AnalysisConfig

The analysis settings.

theme Theme

The appearance.

FigureSpec dataclass

FigureSpec(id: str, title: str, caption: str, builder: Builder, references: tuple[str, ...] = (), prefix: str = '')

One family of figures.

Attributes:

Name Type Description
id str

Stable identifier, also the file stem of the family's figure.

title str

Title of the family.

caption str

What the figures show and how to read them.

builder Builder

Draws the family's figures, and returns none when their inputs are absent.

references tuple[str, ...]

Bibliography keys of the methods the figures implement.

prefix str

For a family with one figure per problem, the start of their file stems; empty when the stem is the id.

owns

owns(name: str) -> bool

Return whether a figure's file stem belongs to this family.

figure_spec

figure_spec(identifier: str) -> FigureSpec

Return the catalog entry with the given id.

Raises:

Type Description
ConfigError

If no entry has that id.

family_of

family_of(name: str) -> FigureSpec | None

Return the family a figure's file stem belongs to, or None for a foreign name.

render_figures

render_figures(dataset: object, directory: str | Path, *, formats: Sequence[str] = FORMATS, config: AnalysisConfig | None = None) -> list[Path]

Write every applicable figure of a campaign's runs.

Parameters:

Name Type Description Default
dataset object

An analysis Dataset, a sequence of RunRecord, or an object with a runs attribute holding run records and optionally a failures attribute holding failure records.

required
directory str | Path

Where to write. When the runs span several protocols, each protocol's figures go to a subdirectory named after it.

required
formats Sequence[str]

Formats to write, from "svg" and "tex".

FORMATS
config AnalysisConfig | None

The analysis settings, the defaults when None: its protocol, solvers, and problems select the runs, its objective and sense are the ones figures read, and the critical-difference diagram follows its statistic, omnibus test, and alpha.

None

Returns:

Type Description
list[Path]

The paths written, in catalog order, then figure order, then format

list[Path]

order; empty when no figure applies.

Raises:

Type Description
ConfigError

If a format is unknown or given twice, or the settings name something the runs lack.

TypeError

If dataset is not one of the accepted inputs.

dispatchatlas.analysis.figures.frames

What the figures read: every planned run, judged by one outcome policy.

observe() turns the results of a campaign into Observations, one Observation per planned run. It accepts:

  • an analysis Dataset, whose runs already carry their status and which also knows the runs that never completed or never started;
  • a sequence of RunRecord;
  • any object with a runs attribute holding run records and, optionally, a failures attribute holding FailureRecord objects.

Outcome policy. It is the analysis package's: a run succeeds when it completed with a feasible schedule and a value. An infeasible run (its schedule breaks a constraint), a failed run (every attempt raised), and a missing run (no record yet) are failures. Failures are never dropped: they count in every denominator, as the worst value in every aggregate, and as never reaching any target. A solver that the plan excludes from a problem counts as failing it in the figures that compare solvers over a common problem set, the performance and data profiles.

Analysed objective. Figures read each problem's primary objective, or the objective and sense an AnalysisConfig names (Observations.configured()), as the tables do. Traces record the primary objective only, so the anytime figures, which read traces, have no data when another objective is analysed.

Aggregation over replicates is explicit (Aggregation): "median" takes the median run, the lower of the two middle runs for an even count, so that the value is one a run achieved and a cell where more than half the runs fail is a failure, while an even split keeps the finite middle run; "best" takes the best run.

Progress. The anytime figures read how the best value found improved during a run (Observation.progress()): the feasible points of the recorded trace, and the final value at the final budget. The budget is the number of evaluations or the elapsed seconds (Budget).

Aggregation

Aggregation = Literal['median', 'best']

How the replicates of a solver on a problem become one value.

Budget

Budget = Literal['evaluations', 'time']

What measures the effort of a run: schedules evaluated, or elapsed seconds.

Observation dataclass

Observation(run_id: str, solver: str, problem: str, protocol: str, replicate: int, status: RunStatus, record: RunRecord | None = None)

One planned run.

Attributes:

Name Type Description
run_id str

Run id.

solver str

Solver name: the campaign label, or the solver id.

problem str

Problem id.

protocol str

Protocol name.

replicate int

Replicate number, from 0.

status RunStatus

"succeeded", "infeasible", "failed", or "missing".

record RunRecord | None

The run record of a completed run.

succeeded property

succeeded: bool

Whether the run completed with a feasible schedule and a value.

progress

progress(sense: Sense, budget: Budget) -> tuple[tuple[float, float], ...]

Return how the best feasible value of the primary objective improved during the run.

Parameters:

Name Type Description Default
sense Sense

Whether the primary objective is minimised or maximised.

required
budget Budget

The effort measure of the first coordinate.

required

Returns:

Type Description
tuple[float, float]

(budget, best value so far) pairs, the value in minimisation

...

form and strictly improving: one per feasible trace point that

tuple[tuple[float, float], ...]

improved on the previous ones, then the final value at the final

tuple[tuple[float, float], ...]

budget if the trace ends above it. Empty unless the run succeeded.

spent

spent(budget: Budget) -> float

Return the effort the run recorded, zero for a run without a record.

Observations dataclass

Observations(runs: tuple[Observation, ...], solvers: tuple[str, ...], problems: tuple[str, ...], protocols: tuple[str, ...], objectives: Mapping[str, tuple[str, ...]] = dict(), sizes: Mapping[str, int] = dict(), target: str | None = None, target_sense: Sense | None = None)

The planned runs of a campaign, as the figures read them.

Build one with observe(), and focus it with configured(), select(), restrict(), and analysing().

Attributes:

Name Type Description
runs tuple[Observation, ...]

One entry per planned run, ordered by problem, replicate, solver, and protocol.

solvers tuple[str, ...]

Solver names, in campaign order.

problems tuple[str, ...]

Problem ids, in plan order.

protocols tuple[str, ...]

Protocol names, in campaign order.

objectives Mapping[str, tuple[str, ...]]

Each problem's objectives, primary first, where known.

sizes Mapping[str, int]

Each problem's number of tasks, where known.

target str | None

The analysed objective, or None for each problem's primary objective.

target_sense Sense | None

The analysed objective's sense, or None for the sense the objective registry declares.

cell

cell(solver: str, problem: str) -> tuple[Observation, ...]

Return the runs of a solver on a problem; empty when the plan excludes the pair.

primary

primary(problem: str) -> str | None

Return the primary objective a problem declares, or None when unknown.

objective

objective(problem: str) -> str | None

Return the analysed objective of a problem, or None when unknown.

sense

sense(problem: str) -> Sense

Return the sense of a problem's analysed objective, minimisation when unknown.

objective_label

objective_label() -> str

Return the name of the analysed objective, or a phrase when problems differ.

value

value(run: Observation) -> float | None

Return the analysed objective's value of a succeeded run, else None.

score

score(run: Observation) -> float

Return a run's value in minimisation form, infinite for a run that did not succeed.

cell_score

cell_score(solver: str, problem: str, aggregation: Aggregation) -> float

Return the aggregated score of a solver's runs on a problem, see aggregate().

traced

traced(problem: str) -> bool

Return whether traces record the analysed objective of a problem, its primary one.

progress

progress(run: Observation, budget: Budget) -> tuple[tuple[float, float], ...]

Return a run's progress, see Observation.progress(), computed once.

Empty when the analysed objective is not the primary one, which is the only objective traces record.

select

select(protocol: str) -> Observations

Return the runs of one protocol.

Raises:

Type Description
ConfigError

If no run has that protocol.

restrict

restrict(solvers: Iterable[str] | None = None, problems: Iterable[str] | None = None) -> Observations

Return the runs of some solvers on some problems, in their original order.

Parameters:

Name Type Description Default
solvers Iterable[str] | None

Solver names to keep, or None for all.

None
problems Iterable[str] | None

Problem ids to keep, or None for all.

None

Raises:

Type Description
ConfigError

If a name is not among the runs'.

analysing

analysing(objective: str | None, sense: Sense | None = None) -> Observations

Return these runs read for another objective, or for each problem's primary one.

Parameters:

Name Type Description Default
objective str | None

The objective to read, or None for each problem's primary objective.

required
sense Sense | None

Its sense, or None for the sense the registry declares.

None

Raises:

Type Description
ConfigError

If a problem whose objectives are known does not declare objective.

configured

configured(config: AnalysisConfig) -> Observations

Return the runs an analysis with these settings reads.

That is its protocol, when it names one, its solvers and problems, and its objective and sense.

Raises:

Type Description
ConfigError

If the settings name a protocol, solver, problem, or objective the runs lack.

comparable

comparable() -> Observations

Return these runs, checking that they come from one protocol.

Runs under different stop criteria cannot be compared, so every figure reads one protocol at a time.

Raises:

Type Description
ConfigError

If the runs span several protocols.

QualityRange dataclass

QualityRange(best: float, start: float)

The span of values found on one problem, in minimisation form.

Attributes:

Name Type Description
best float

The best value any succeeded run reached, the f_L of Moré and Wild (2009).

start float

The worst first feasible value of a succeeded run.

gap

gap(value: float) -> float

Return how far value is from the best, as a share of the span, from 0 to 1.

Infinite values, which stand for no feasible solution, give 1. A problem where every run started at the best value gives 0.

observe

observe(source: object) -> Observations

Return the planned runs of a campaign's results, with their status.

Parameters:

Name Type Description Default
source object

An analysis dataset, a sequence of run records, an object with runs (run records) and optionally failures (failure records), or observations, which are returned as they are.

required

Returns:

Type Description
Observations

The observations. Records and failures give no missing runs, since

Observations

only a dataset knows the plan; a run whose attempts failed and that

Observations

never completed is a failed run.

Raises:

Type Description
TypeError

If source is none of these, or holds other objects.

lower_median

lower_median(values: Sequence[float]) -> float

Return the lower median: the middle value, or the lower of the two middle values.

Raises:

Type Description
ValueError

If values is empty.

aggregate

aggregate(scores: Sequence[float], aggregation: Aggregation) -> float

Return one value for the scores of a cell's runs, in minimisation form.

Parameters:

Name Type Description Default
scores Sequence[float]

The runs' scores, infinite for a failed run.

required
aggregation Aggregation

"median" for the median run, "best" for the best run.

required

Returns:

Type Description
float

The aggregated score, infinite for a cell without runs.

check_aggregation

check_aggregation(value: object) -> Aggregation

Return value if it names an aggregation.

Raises:

Type Description
ConfigError

Otherwise.

check_budget

check_budget(value: object) -> Budget

Return value if it names a budget measure.

Raises:

Type Description
ConfigError

Otherwise.

quality_ranges

quality_ranges(observations: Observations, budget: Budget) -> dict[str, QualityRange]

Return the span of values found on each problem where some run succeeded.

objective_sense

objective_sense(objective: str) -> Sense

Return the sense the objective registry declares, minimisation for an unknown name.

An unknown objective is logged once, since the figures of a run of a plugin's objective can still be drawn when the plugin is not loaded.

dispatchatlas.analysis.figures.profiles

Performance profiles, data profiles, and runtime distributions.

Three views of how often each solver reaches good results over a common problem set, each a step function from 0 to 1:

  • the performance profile of Dolan and Moré (2002): the share of problems on which a solver's value is within a factor tau of the best solver's;
  • the data profile of Moré and Wild (2009): the share of problems a solver solves to accuracy tau within a budget of evaluations;
  • the runtime distribution of Hansen et al. (2022): the share of (problem, quality target) pairs a solver's runs reach within a budget.

Every profile keeps failures in its denominator (see frames): a failed run never reaches a ratio, an accuracy, or a target.

PROFILE_THRESHOLDS module-attribute

PROFILE_THRESHOLDS: tuple[float, ...] = (1.0, 1.05, 1.1, 1.25, 1.5, 2.0)

Ratio thresholds at which PerformanceProfile.at() reads the profiles by default.

GOULD_SCOTT_CAVEAT module-attribute

GOULD_SCOTT_CAVEAT = 'Caveat: profiles rank each solver only against the per-problem best; the relative order of non-best solvers is not implied (Gould & Scott 2016).'

The caution of Gould and Scott (2016), shown on profiles of more than two solvers.

QUALITY_TARGETS module-attribute

QUALITY_TARGETS: tuple[float, ...] = (0.5, 0.2, 0.1, 0.05, 0.02, 0.01, 0.0)

Quality targets of the runtime distribution, as shares of a problem's span of values.

ProfileCurve dataclass

ProfileCurve(solver: str, ratios: tuple[float, ...])

The performance ratios of one solver.

Attributes:

Name Type Description
solver str

Solver name.

ratios tuple[float, ...]

One ratio per problem of the profile, ascending; infinite where the solver failed.

solved property

solved: int

Problems with a finite ratio.

share

share(tau: float) -> float

Return the profile at tau: the share of problems with a ratio of at most tau.

PerformanceProfile dataclass

PerformanceProfile(curves: tuple[ProfileCurve, ...], problems: tuple[str, ...], excluded: tuple[str, ...], aggregation: Aggregation, objective: str = '')

Dolan-Moré performance profiles of every solver over a common problem set.

Attributes:

Name Type Description
curves tuple[ProfileCurve, ...]

One curve per solver, in campaign order.

problems tuple[str, ...]

The problems of the profile.

excluded tuple[str, ...]

Problems left out because their best value is not positive, where ratios are undefined.

aggregation Aggregation

How the runs of a cell were aggregated.

objective str

Name of the objective compared, empty when unknown.

at

at(thresholds: Sequence[float] = PROFILE_THRESHOLDS) -> dict[str, tuple[float, ...]]

Return each solver's profile read at the given ratio thresholds.

DataCurve dataclass

DataCurve(solver: str, budgets: tuple[float, ...])

The budgets one solver needs to solve each problem.

Attributes:

Name Type Description
solver str

Solver name.

budgets tuple[float, ...]

One budget per problem of the profile, ascending, in the profile's unit; infinite where the solver never solves it.

solved property

solved: int

Problems solved within the budget limit.

cells property

cells: int

Problems of the profile, solved or not.

share

share(kappa: float) -> float

Return the share of problems solved within budget kappa; failures never count.

DataProfile dataclass

DataProfile(curves: tuple[DataCurve, ...], problems: tuple[str, ...], accuracy: float, unit: str, knots: tuple[float, ...], aggregation: Aggregation = 'median')

Moré-Wild data profiles of every solver.

Attributes:

Name Type Description
curves tuple[DataCurve, ...]

One curve per solver, in campaign order.

problems tuple[str, ...]

The problems of the profile.

accuracy float

The accuracy tau of the convergence test.

unit str

What a unit of budget is: "evaluations", or evaluations divided by the number of tasks plus one.

knots tuple[float, ...]

The finite budgets where some curve steps, ascending.

aggregation Aggregation

How the runs of a cell were aggregated.

points

points(solver: str) -> tuple[tuple[float, float], ...]

Return a solver's (budget, share) pairs at every knot.

Raises:

Type Description
ConfigError

If the profile has no such solver.

RuntimeCurve dataclass

RuntimeCurve(solver: str, knots: tuple[tuple[float, float], ...])

The share of (problem, target) pairs one solver's runs reach, by budget.

Attributes:

Name Type Description
solver str

Solver name.

knots tuple[tuple[float, float], ...]

(budget, share reached within it) pairs, ascending in both.

final property

final: float

The share of pairs reached by the end of the runs.

share

share(budget: float) -> float

Return the share of pairs reached within budget.

RuntimeDistribution dataclass

RuntimeDistribution(curves: tuple[RuntimeCurve, ...], problems: tuple[str, ...], targets: tuple[float, ...], budget: Budget, horizon: float)

Runtime distributions of every solver over quality targets.

Attributes:

Name Type Description
curves tuple[RuntimeCurve, ...]

One curve per solver, in campaign order.

problems tuple[str, ...]

The problems of the distribution.

targets tuple[float, ...]

The quality targets, as shares of each problem's span.

budget Budget

What measures the runtime.

horizon float

The largest budget any run spent.

performance_profile

performance_profile(source: object, *, aggregation: str = 'median') -> PerformanceProfile

Return the performance profiles of Dolan and Moré (2002).

Each solver's runs on a problem become one value, the median or the best run, a failed run counting as infinitely bad. The ratio of a solver on a problem is its value over the best solver's value (the best value over the solver's value when the objective is maximised), 1 for the best solver and infinite for a failure. Values within the analysis tie tolerance of the best count as ratio 1. Ratios need positive values, so a problem whose best value is zero or negative is left out for every solver and reported.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required
aggregation str

"median" or "best", see Aggregation.

'median'

Returns:

Type Description
PerformanceProfile

The profiles.

Raises:

Type Description
ConfigError

If the runs span several protocols or the aggregation is unknown.

plot_performance_profile

plot_performance_profile(profile: PerformanceProfile, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw performance profiles as step functions of the ratio tau.

The ratio axis runs from 1 to the largest finite ratio, on a logarithmic scale when that exceeds 4. With more than two solvers the figure carries the caveat of Gould and Scott (2016) as a visible note.

Parameters:

Name Type Description Default
profile PerformanceProfile

The profiles.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, or a placeholder stating why there is nothing to draw.

data_profile

data_profile(source: object, *, accuracy: float = 0.001, sizes: Mapping[str, int] | None = None, budget_limit: float | None = None, aggregation: str = 'median') -> DataProfile

Return the data profiles of Moré and Wild (2009).

On each problem, f_L is the best value any succeeded run reached, over its trace and its final value. A run solves the problem at the first feasible trace point whose best value so far passes the inclusive convergence test f <= f_L + tau (f_0 - f_L), where f_0 is the run's first feasible value (mirrored for a maximised objective); its budget is the number of evaluations recorded at that point. A run that never passes the test, or did not succeed, never solves the problem. A solver's budget on a problem is that of its median run, the lower of the two middle runs for an even count, or of its best run. Budgets are divided by n_p + 1, where n_p is the problem's number of tasks, as Moré and Wild divide by the dimension plus one; a problem of unknown size keeps undivided budgets. A solver the plan excludes from a problem never solves it.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required
accuracy float

The accuracy tau, strictly between 0 and 1.

0.001
sizes Mapping[str, int] | None

Number of tasks of each problem. Defaults to the sizes the source knows, which an analysis dataset provides.

None
budget_limit float | None

Largest budget, in the profile's unit, within which a problem can count as solved.

None
aggregation str

"median" or "best", see Aggregation.

'median'

Returns:

Type Description
DataProfile

The profiles.

Raises:

Type Description
ConfigError

If accuracy is not strictly between 0 and 1, the budget limit is not positive, a size is negative, or the runs span several protocols.

plot_data_profile

plot_data_profile(profile: DataProfile, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw data profiles as step functions of the budget.

Parameters:

Name Type Description Default
profile DataProfile

The profiles.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, or a placeholder when no solver solved any problem.

runtime_distribution

runtime_distribution(source: object, *, targets: Sequence[float] = QUALITY_TARGETS, budget: str = 'time') -> RuntimeDistribution

Return the empirical distribution of the runtime to reach quality targets.

Following the anytime assessment of Hansen et al. (2022), each problem gets quality targets f_L + t (f_U - f_L) for every t in targets, where f_L is the best value any run reached and f_U the worst first feasible value of a run. The runtime of a run to a target is the budget at which its best value first reaches the target. A solver's curve at budget b is the share of (problem, target) pairs reached within b, averaged over its runs on each problem, with every problem weighing equally. Failed runs never reach a target, and a solver excluded from a problem reaches none of its targets.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required
targets Sequence[float]

Target levels between 0 (the best value found) and 1.

QUALITY_TARGETS
budget str

"time" for elapsed seconds or "evaluations".

'time'

Returns:

Type Description
RuntimeDistribution

The distributions.

Raises:

Type Description
ConfigError

If a target is outside [0, 1] or repeated, there is none, the budget is unknown, or the runs span several protocols.

plot_runtime_distribution

plot_runtime_distribution(distribution: RuntimeDistribution, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw runtime distributions as step functions on a logarithmic budget axis.

Parameters:

Name Type Description Default
distribution RuntimeDistribution

The distributions.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, or a placeholder when no run reached any target.

dispatchatlas.analysis.figures.traces

Convergence: how the best value found improves with the effort spent.

Values of different problems are made comparable by a gap in [0, 1]: 0 at the best value any run found on the problem, 1 at the worst first feasible value of a run (see QualityRange). A run's gap at a budget is that of the best feasible value it had found by then; before its first feasible schedule, and throughout a run that did not succeed, the gap is 1. A solver's curve is the median gap over all its planned runs, on every problem, with the interquartile range as a band, sampled on a grid of budgets spaced evenly on a logarithmic scale.

ConvergenceCurve dataclass

ConvergenceCurve(solver: str, budgets: tuple[float, ...], median: tuple[float, ...], lower: tuple[float, ...], upper: tuple[float, ...], runs: int)

The gap of one solver's runs, by budget.

Attributes:

Name Type Description
solver str

Solver name.

budgets tuple[float, ...]

The sampled budgets, ascending.

median tuple[float, ...]

Median gap at each budget.

lower tuple[float, ...]

First quartile of the gap.

upper tuple[float, ...]

Third quartile of the gap.

runs int

Planned runs summarised.

Convergence dataclass

Convergence(curves: tuple[ConvergenceCurve, ...], budget: Budget, problems: tuple[str, ...])

Convergence curves of every solver.

Attributes:

Name Type Description
curves tuple[ConvergenceCurve, ...]

One curve per solver with planned runs, in campaign order.

budget Budget

What measures the effort.

problems tuple[str, ...]

The problems the runs solved.

convergence

convergence(source: object, *, budget: str = 'evaluations', points: int = GRID_POINTS) -> Convergence

Return each solver's median convergence curve with its interquartile range.

Quartiles follow the inclusive method, as in the box plots.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required
budget str

"evaluations" or "time".

'evaluations'
points int

Budgets on the sampling grid, at least 2.

GRID_POINTS

Returns:

Type Description
Convergence

The curves. They are empty when no run recorded a positive budget.

Raises:

Type Description
ConfigError

If the budget is unknown, points is below 2, or the runs span several protocols.

plot_convergence

plot_convergence(curves: Convergence, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw median gaps as step functions of the budget, with interquartile bands.

Parameters:

Name Type Description Default
curves Convergence

The convergence curves.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, named convergence-evaluations or convergence-time,

Figure

or a placeholder when no run recorded any progress.

dispatchatlas.analysis.figures.ranking

The critical-difference diagram of Demšar (2006).

Solvers sit on an axis of average ranks, rank 1 best. When the omnibus test rejects, the Nemenyi critical difference CD is drawn as a bar of that length, and every maximal group of solvers, consecutive in rank order, whose average ranks lie within CD of each other is joined by a thick line: the members of a group are not significantly different. A pair of solvers two groups apart differs significantly. Groups of one are not drawn.

A diagram can be built from values computed elsewhere, such as the CriticalDifference of a summary (rank_diagram()), or from runs (average_ranks()), which follows the procedure of summarize() with the default AnalysisConfig: each cell scores the mean (or configured statistic) of its planned runs, a failure counting as the worst value; the complete blocks are ranked; the omnibus test gates the Nemenyi test, whose critical values come from the statistics package.

RankDiagram dataclass

RankDiagram(ranks: tuple[tuple[str, float], ...], critical_difference: float | None, alpha: float, blocks: int, cliques: tuple[tuple[str, ...], ...], note: str = '', objective: str = '')

What a critical-difference diagram shows.

Attributes:

Name Type Description
ranks tuple[tuple[str, float], ...]

Each solver's average rank, best first.

critical_difference float | None

The Nemenyi critical difference, or None when no post-hoc test applies.

alpha float

Significance level of the test.

blocks int

Problems the ranks average over.

cliques tuple[tuple[str, ...], ...]

Groups of at least two solvers, in rank order, whose ranks lie within the critical difference of each other.

note str

Why no critical difference is drawn, when none is.

objective str

Name of the objective ranked, empty when unknown.

cliques

cliques(ranks: Sequence[tuple[str, float]], critical_difference: float) -> tuple[tuple[str, ...], ...]

Return the maximal groups of rank-ordered solvers within the critical difference.

A group is a run of consecutive solvers in rank order whose first and last ranks differ by at most critical_difference; a group contained in another is not returned, and neither are groups of one.

rank_diagram

rank_diagram(ranks: Mapping[str, float] | Sequence[tuple[str, float]], critical_difference: float | None = None, *, alpha: float = 0.05, blocks: int = 0, note: str = '', objective: str = '') -> RankDiagram

Return a diagram of average ranks and a critical difference computed elsewhere.

Parameters:

Name Type Description Default
ranks Mapping[str, float] | Sequence[tuple[str, float]]

Each solver's average rank.

required
critical_difference float | None

The critical difference, or None to draw the ranks only.

None
alpha float

Significance level the critical difference belongs to.

0.05
blocks int

Problems the ranks average over, shown in the notes.

0
note str

Why no critical difference is given, shown in the notes.

''
objective str

Name of the objective ranked, shown in the notes.

''

Raises:

Type Description
ConfigError

If a rank or the critical difference is not a positive finite number, or a solver is ranked twice.

average_ranks

average_ranks(source: object, config: AnalysisConfig | None = None) -> RankDiagram

Return average ranks and the gated Nemenyi critical difference, from runs.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required
config AnalysisConfig | None

The analysis settings, the defaults when None: the runs of its protocol, solvers, and problems are ranked on its objective and sense, with its statistic, omnibus test, and alpha.

None

Returns:

Type Description
RankDiagram

The diagram, with critical_difference None and a note when

RankDiagram

there are fewer than three solvers or two complete blocks, when the

RankDiagram

omnibus test does not reject, or when no critical value is tabulated.

Raises:

Type Description
ConfigError

If the runs span several protocols, or the settings name something the runs lack.

plot_critical_difference

plot_critical_difference(diagram: RankDiagram, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw a critical-difference diagram.

The better half of the solvers is labelled on the left, the other half on the right, each label joined to the solver's rank by a line; groups that the Nemenyi test does not separate are joined by thick bars under the axis.

Parameters:

Name Type Description Default
diagram RankDiagram

Ranks, critical difference, and groups.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, or a placeholder with fewer than two ranked solvers.

dispatchatlas.analysis.figures.distribution

The distribution of each solver's results, as box plots.

Values of different problems are made comparable by their relative percentage deviation from the best value any run found on the problem, computed by relative_deviation(), so 0 is the best value found and larger is worse under either sense. Each solver's box pools the deviations of its succeeded runs on every problem; the row also states how many of its planned runs succeeded, since a failed run has no value to place. A problem whose best value is not positive has no relative deviation and is left out, and reported.

The box spans the inclusive quartiles (type 7 of Hyndman and Fan 1996), the inner line marks the median, and the whiskers reach the smallest and largest values.

Box dataclass

Box(solver: str, stats: BoxStats | None, succeeded: int, planned: int)

The deviations of one solver.

Attributes:

Name Type Description
solver str

Solver name.

stats BoxStats | None

Box-plot statistics of the deviations, in percent, or None when no run succeeded.

succeeded int

Succeeded runs on the problems of the distribution.

planned int

Planned runs on those problems.

Distribution dataclass

Distribution(boxes: tuple[Box, ...], problems: tuple[str, ...], excluded: tuple[str, ...], objective: str = '')

Box plots of every solver's relative deviations.

Attributes:

Name Type Description
boxes tuple[Box, ...]

One box per solver, in campaign order.

problems tuple[str, ...]

The problems whose runs the boxes pool.

excluded tuple[str, ...]

Problems left out because their best value is not positive.

objective str

Name of the objective measured, empty when unknown.

deviation_distribution

deviation_distribution(source: object) -> Distribution

Return each solver's relative percentage deviations from the best value found.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required

Returns:

Type Description
Distribution

The box of every solver.

Raises:

Type Description
ConfigError

If the runs span several protocols.

plot_distribution

plot_distribution(boxes: Distribution, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw one horizontal box plot per solver.

Parameters:

Name Type Description Default
boxes Distribution

The distribution.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, or a placeholder when no run succeeded.

dispatchatlas.analysis.figures.pareto

Pareto fronts of bi-objective problems, as attainment surfaces.

A run attains an objective vector when one of its solutions is at least as good in both objectives. With several replicates, a solver's front is a summary attainment surface (Fonseca and Fleming 1996): the boundary of the vectors attained in at least k of its planned runs. The median surface, k the smallest integer of at least half the runs, shows what a typical run achieves; the best surface, k = 1, is the non-dominated set of all the solver's solutions. A failed run attains nothing, so failures pull the median surface back without being dropped.

A multi-objective solver contributes its recorded front; any other solver contributes the objective vector of its best schedule. Problems with exactly two objectives get a figure each.

Surface dataclass

Surface(solver: str, points: tuple[Point, ...], level: int, runs: int)

One solver's attainment surface on a problem.

Attributes:

Name Type Description
solver str

Solver name.

points tuple[Point, ...]

The corners of the surface, in objective units, ordered by the first objective from best to worst.

level int

The surface bounds the vectors attained in at least this many runs.

runs int

Planned runs of the solver on the problem.

ParetoFronts dataclass

ParetoFronts(problem: str, objectives: tuple[str, str], senses: tuple[Sense, Sense], surfaces: tuple[Surface, ...], aggregation: Aggregation)

The attainment surfaces of every solver on one bi-objective problem.

Attributes:

Name Type Description
problem str

Problem id.

objectives tuple[str, str]

The two objectives, in the problem's order.

senses tuple[Sense, Sense]

Their senses.

surfaces tuple[Surface, ...]

One surface per solver with planned runs, in campaign order.

aggregation Aggregation

"median" or "best".

attainment_surface

attainment_surface(runs: Sequence[Sequence[Point]], level: int) -> tuple[Point, ...]

Return the corners of the level-th summary attainment surface of point sets.

Parameters:

Name Type Description Default
runs Sequence[Sequence[Point]]

The solutions of each run, as minimisation vectors; an empty set is a run that attained nothing.

required
level int

How many runs must attain a vector, from 1.

required

Returns:

Type Description
Point

The corners, ascending in the first coordinate and strictly

...

descending in the second; empty when fewer than level runs

tuple[Point, ...]

attain anything.

pareto_fronts

pareto_fronts(source: object, *, aggregation: str = 'median') -> tuple[ParetoFronts, ...]

Return the attainment surfaces of every solver on every bi-objective problem.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required
aggregation str

"median" for the surface attained in at least half of the planned runs, "best" for the one attained in any run.

'median'

Returns:

Type Description
tuple[ParetoFronts, ...]

One entry per problem with exactly two objectives, in plan order.

Raises:

Type Description
ConfigError

If the aggregation is unknown or the runs span several protocols.

plot_pareto_fronts

plot_pareto_fronts(fronts: ParetoFronts, *, labels: Mapping[str, str] | None = None, theme: Theme | None = None) -> Figure

Draw each solver's attainment surface on one problem as a staircase.

Parameters:

Name Type Description Default
fronts ParetoFronts

The surfaces of one problem.

required
labels Mapping[str, str] | None

Display names of solvers; a solver without one shows its name.

None
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, named pareto-front-<problem> with characters that

Figure

cannot name a file replaced by _, or a placeholder when no surface

Figure

has a point.

dispatchatlas.analysis.figures.gantt

The Gantt chart of one schedule.

Given the problem, the chart has one row per resource, and a task appears on the row of every resource its mode holds, coloured by its job (its group, or itself without one). A resource that runs several tasks at once, such as a pool of cores, gets as many rows as it needs, filled first-fit in order of start time, so bars never overlap. Without the problem, which the run records do not hold, the chart has one row per task, in order of start time, coloured by the index of the mode the task runs in. A dashed line marks the makespan.

representative_schedule() picks the schedule the figure catalog draws from a campaign: the best recorded schedule on the first problem.

GanttBar dataclass

GanttBar(row: int, task: str, start: float, end: float, key: int)

One task on one row.

Attributes:

Name Type Description
row int

Index of the row.

task str

Task id.

start float

Start time.

end float

Finish time.

key int

Index of the bar's colour key.

GanttChart dataclass

GanttChart(title: str, view: Literal['resources', 'tasks'], rows: tuple[str, ...], bars: tuple[GanttBar, ...], keys: tuple[str, ...], makespan: float)

What a Gantt chart shows.

Attributes:

Name Type Description
title str

Title of the figure.

view Literal['resources', 'tasks']

"resources" for one row per resource, "tasks" for one row per task.

rows tuple[str, ...]

Row labels; the extra rows of a resource are unlabelled.

bars tuple[GanttBar, ...]

The bars.

keys tuple[str, ...]

What each colour stands for: jobs, or modes.

makespan float

Latest finish time.

gantt_chart

gantt_chart(schedule: Schedule, problem: Problem | None = None, *, title: str = 'Schedule') -> GanttChart

Return the Gantt chart of a schedule.

Parameters:

Name Type Description Default
schedule Schedule

The schedule.

required
problem Problem | None

The problem it solves, for rows per resource. Without it, the chart has one row per task.

None
title str

Title of the figure.

'Schedule'

Returns:

Type Description
GanttChart

The chart.

Raises:

Type Description
ConfigError

If the schedule names a task or mode the problem lacks.

representative_schedule

representative_schedule(source: object) -> Observation | None

Return the run whose schedule the catalog draws.

It is the succeeded run with a recorded schedule on the first problem that has one, with the best value there; ties go to the solver listed first, then to the lowest replicate.

Parameters:

Name Type Description Default
source object

Runs of one protocol, anything observe() accepts.

required

Returns:

Type Description
Observation | None

The run, or None when no run recorded a schedule.

plot_gantt

plot_gantt(chart: GanttChart, *, theme: Theme | None = None) -> Figure

Draw a Gantt chart.

Parameters:

Name Type Description Default
chart GanttChart

The chart.

required
theme Theme | None

The appearance.

None

Returns:

Type Description
Figure

The figure, or a placeholder for an empty schedule.

dispatchatlas.analysis.figures.chart

Chart layouts shared by the figure families.

Two layouts cover every family except the critical-difference diagram:

  • xy_chart() draws series against two numeric axes, as lines, step functions, scatter points, and translucent bands;
  • row_chart() draws one row per category, such as a solver or a machine, against a numeric horizontal axis, with box plots or bars.

Both put the title on top, the plot with its ticks, grid, and axis titles in the middle, and the legend and notes below the plot. The legend wraps onto as many rows as it needs and the canvas grows to hold it, so no element is ever placed outside the canvas, however many series a chart has. Series lines are thinned in pixel space before drawing: points that fall within half a pixel of each other are merged, which leaves the drawing unchanged and bounds the size of the output.

Series dataclass

Series(label: str, points: tuple[Point, ...], style: SeriesStyle, kind: Literal['line', 'step', 'points'] = 'line', markers: bool = True, band: tuple[tuple[float, float, float], ...] = (), until: float | None = None, legend: bool = True)

One series of an x-y chart, in data coordinates.

Attributes:

Name Type Description
label str

Legend text.

points tuple[Point, ...]

The points, ascending in x for lines and steps.

style SeriesStyle

Colour, marker, and dash.

kind Literal['line', 'step', 'points']

"line" joins the points, "step" draws a right-continuous step function that holds each value until the next point, and "points" draws markers only.

markers bool

Draw MAX_MARKERS markers along a line or step function, at evenly spaced positions.

band tuple[tuple[float, float, float], ...]

(x, low, high) triples drawn as a translucent band, stepped like the line when kind is "step".

until float | None

For a step function, the x up to which the last value holds.

legend bool

Give the series a legend entry.

LegendEntry dataclass

LegendEntry(label: str, style: SeriesStyle, kind: Literal['line', 'box', 'bar'] = 'line')

One legend item.

Attributes:

Name Type Description
label str

Text.

style SeriesStyle

Colour, marker, and dash of the swatch.

kind Literal['line', 'box', 'bar']

"line" for a line with its marker, "box" for a translucent square like a box plot's, "bar" for an opaque square like a bar's.

Guide dataclass

Guide(x: float, label: str)

A labelled vertical line across the plot, such as a makespan.

Attributes:

Name Type Description
x float

Position in data coordinates.

label str

Text written above the plot at the line.

BoxStats dataclass

BoxStats(minimum: float, lower: float, median: float, upper: float, maximum: float, count: int)

The five numbers a box plot draws.

Attributes:

Name Type Description
minimum float

Smallest value, the end of the lower whisker.

lower float

First quartile, the lower edge of the box.

median float

Median, the line inside the box.

upper float

Third quartile, the upper edge of the box.

maximum float

Largest value, the end of the upper whisker.

count int

Number of values.

Bar dataclass

Bar(row: int, start: float, end: float, color: str, text: str = '', tooltip: str = '')

A horizontal bar in a row chart.

Attributes:

Name Type Description
row int

Index of the row.

start float

Left end in data coordinates.

end float

Right end.

color str

#RRGGBB fill.

text str

Text written inside the bar when it fits.

tooltip str

Text a viewer shows on hovering, SVG only.

Row dataclass

Row(label: str, box: BoxStats | None = None, style: SeriesStyle | None = None, note: str = '')

One category of a row chart.

Attributes:

Name Type Description
label str

Text left of the row.

box BoxStats | None

Box-plot statistics drawn in the row, if any.

style SeriesStyle | None

Colour of the box.

note str

Text right of the box, such as a count of failed runs.

box_stats

box_stats(values: Sequence[float]) -> BoxStats

Return the five-number summary of at least one value.

Quartiles follow the inclusive method of statistics.quantiles(), type 7 in the taxonomy of Hyndman and Fan (1996); a single value is its own quartiles.

Raises:

Type Description
ValueError

If values is empty.

xy_chart

xy_chart(name: str, title: str, description: str, *, x: Axis, y: Axis, series: Sequence[Series], notes: Sequence[str] = (), theme: Theme) -> Figure

Draw series against two numeric axes.

Parameters:

Name Type Description Default
name str

File stem of the figure.

required
title str

Title drawn at the top.

required
description str

Text alternative of the figure.

required
x Axis

Horizontal axis.

required
y Axis

Vertical axis.

required
series Sequence[Series]

The series, drawn in order, each with a legend entry unless it asks for none.

required
notes Sequence[str]

Lines of text under the legend, such as caveats.

()
theme Theme

The appearance.

required

Returns:

Type Description
Figure

The figure.

row_chart

row_chart(name: str, title: str, description: str, *, x: Axis, rows: Sequence[Row], bars: Sequence[Bar] = (), row_height: float = 26.0, legend: Sequence[LegendEntry] = (), guides: Sequence[Guide] = (), notes: Sequence[str] = (), theme: Theme) -> Figure

Draw one row per category against a numeric horizontal axis.

Parameters:

Name Type Description Default
name str

File stem of the figure.

required
title str

Title drawn at the top.

required
description str

Text alternative of the figure.

required
x Axis

Horizontal axis.

required
rows Sequence[Row]

The categories, drawn top to bottom, with optional box plots.

required
bars Sequence[Bar]

Horizontal bars placed in the rows.

()
row_height float

Height of a row, in pixels.

26.0
legend Sequence[LegendEntry]

Legend entries, drawn under the axis.

()
guides Sequence[Guide]

Labelled vertical lines.

()
notes Sequence[str]

Lines of text under the legend.

()
theme Theme

The appearance.

required

Returns:

Type Description
Figure

The figure.

placeholder

placeholder(name: str, title: str, reason: str, theme: Theme) -> Figure

Return a figure that states why there is nothing to draw.

label_for

label_for(identifier: str, labels: Mapping[str, str] | None) -> str

Return the display label of an id: its entry in labels, else the id itself.

draw_title

draw_title(shapes: list[Shape], title: str, theme: Theme) -> float

Add the title, wrapped to the canvas, and return the height it takes.

draw_notes

draw_notes(shapes: list[Shape], notes: Sequence[str], top: float, theme: Theme) -> float

Add notes, wrapped to the canvas, and return the bottom of the last line.

dispatchatlas.analysis.figures.axes

Numeric axes: ranges, tick marks, tick labels, and the mapping to pixels.

A linear axis extends its data range to the nearest multiples of a nice step, a number 1, 2, or 5 times a power of ten, chosen so that about six ticks cover the range. A logarithmic axis (base 10) extends its range to the nearest numbers of the 1, 2, 5, 10, 20, ... sequence and places ticks at the numbers of that sequence in its range, at powers of ten alone when the sequence would give more than nine ticks, and at nice linear steps when it gives fewer than three. The labels of one axis share one style: the fewest decimals that tell the ticks apart, or exponent form when some tick is very large or very small. A label depends on the tick values only.

Axis dataclass

Axis(label: str, low: float, high: float, log: bool = False, ticks: tuple[float, ...] = (), labels: tuple[str, ...] = ())

A numeric axis.

Attributes:

Name Type Description
label str

Axis title.

low float

Value at the start of the axis.

high float

Value at the end of the axis, above low.

log bool

Whether the scale is logarithmic; then low is positive.

ticks tuple[float, ...]

Tick positions within [low, high], ascending.

labels tuple[str, ...]

The label of each tick.

fraction

fraction(value: float) -> float

Return where value lies along the axis, from 0 to 1, clamping outside values.

position

position(value: float, start: float, end: float) -> float

Return the pixel of value on an axis drawn from start to end.

numeric_axis

numeric_axis(label: str, values: Iterable[float], *, low: float | None = None, high: float | None = None, log: bool = False, ticks: int = 6) -> Axis

Return an axis covering the finite values.

Parameters:

Name Type Description Default
label str

Axis title.

required
values Iterable[float]

Data values; infinite and NaN values are ignored.

required
low float | None

Fixed lower end. Without one, the range extends to a nice value.

None
high float | None

Fixed upper end.

None
log bool

Use a logarithmic scale; non-positive values are then ignored.

False
ticks int

About how many ticks a linear axis gets.

6

Returns:

Type Description
Axis

The axis. Without data, a linear axis spans 0 to 1 and a logarithmic

Axis

one 1 to 10.

log_axis

log_axis(label: str, values: Iterable[float], *, low: float | None = None, high: float | None = None) -> Axis

Return a logarithmic axis covering the positive finite values.

Without fixed ends, the range extends to the nearest numbers of the 1, 2, 5 sequence around the data.

tick_labels

tick_labels(ticks: Sequence[float], step: float | None = None) -> tuple[str, ...]

Return the labels of an axis's ticks, all in one style.

Ticks are written in exponent form, such as 2e-5 or 1.5e6, when any of them is at least 1e5 or, other than zero, below 1e-4; otherwise as plain decimals.

Parameters:

Name Type Description Default
ticks Sequence[float]

The tick values.

required
step float | None

Distance between neighbouring ticks of a linear axis, which fixes the number of decimals; without it each value is written with the digits it needs.

None

format_tick

format_tick(value: float, step: float | None = None, *, exponent: bool = False) -> str

Return the label of one tick.

Parameters:

Name Type Description Default
value float

The tick value.

required
step float | None

Distance between neighbouring ticks of a linear axis, which fixes the number of decimals; without it the value is written with the digits it needs, up to six decimals.

None
exponent bool

Write the value in exponent form, such as 1.5e6.

False

dispatchatlas.analysis.figures.drawing

The drawing model: a figure is a canvas, a title, a description, and shapes.

Chart builders compute a layout in pixels, with the origin at the top left and y growing downwards, and emit a flat list of shapes: lines, polylines, polygons, rectangles, markers, and text. to_svg and to_tex serialise the same list, so the SVG and TikZ versions of a figure share every coordinate.

Numbers are written with at most two decimals and no trailing zeros (number()), so a figure's bytes depend on its data only. Text widths are estimated from the character count (text_width()); the estimate is generous, so labels fit in either format.

Point

Point = tuple[float, float]

A position in pixels: (x, y) with y growing downwards.

Anchor

Anchor = Literal['start', 'middle', 'end']

Which point of a text its position names: its start, middle, or end.

Shape

Shape = Line | Polyline | Polygon | Rect | Marker | Text

Anything a figure is drawn from.

Stroke dataclass

Stroke(color: str, width: float = 1.0, dash: tuple[float, ...] = (), opacity: float = 1.0)

How a line is drawn.

Attributes:

Name Type Description
color str

#RRGGBB colour.

width float

Line width in pixels.

dash tuple[float, ...]

Dash pattern in pixels, empty for a solid line.

opacity float

Opacity from 0 to 1.

Line dataclass

Line(start: Point, end: Point, stroke: Stroke, role: str = '')

A straight segment.

Attributes:

Name Type Description
start Point

First end.

end Point

Second end.

stroke Stroke

How it is drawn.

role str

Style class for restyling the SVG, such as "axis".

Polyline dataclass

Polyline(points: tuple[Point, ...], stroke: Stroke)

An open path through points.

Attributes:

Name Type Description
points tuple[Point, ...]

The points, in drawing order.

stroke Stroke

How it is drawn.

Polygon dataclass

Polygon(points: tuple[Point, ...], fill: str, opacity: float = 1.0)

A closed, filled path.

Attributes:

Name Type Description
points tuple[Point, ...]

The corners, in drawing order.

fill str

#RRGGBB fill colour.

opacity float

Fill opacity from 0 to 1.

Rect dataclass

Rect(x: float, y: float, width: float, height: float, fill: str | None, opacity: float = 1.0, stroke: Stroke | None = None, tooltip: str = '')

An axis-aligned rectangle.

Attributes:

Name Type Description
x float

Left edge.

y float

Top edge.

width float

Width, at least 0.

height float

Height, at least 0.

fill str | None

#RRGGBB fill colour, or None for no fill.

opacity float

Fill opacity from 0 to 1.

stroke Stroke | None

Outline, or None for none.

tooltip str

Text a viewer shows on hovering, SVG only.

Marker dataclass

Marker(x: float, y: float, shape: str, size: float, color: str, filled: bool = True)

A data marker centred on a point.

Attributes:

Name Type Description
x float

Centre.

y float

Centre.

shape str

One of MARKERS.

size float

Radius of the circle that holds the shape, in pixels.

color str

#RRGGBB colour.

filled bool

Filled, or outlined only.

Text dataclass

Text(x: float, y: float, text: str, size: float, color: str, anchor: Anchor = 'start', bold: bool = False, italic: bool = False, vertical: bool = False)

A single line of text.

Attributes:

Name Type Description
x float

Horizontal position of the anchor.

y float

Baseline, or, for vertical text, the horizontal position of the baseline.

text str

The text, without line breaks.

size float

Type size in pixels.

color str

#RRGGBB colour.

anchor Anchor

Which point of the text x names.

bold bool

Set in bold.

italic bool

Set in italics.

vertical bool

Rotated a quarter turn counter-clockwise, reading upwards.

Figure dataclass

Figure(name: str, title: str, description: str, width: float, height: float, shapes: tuple[Shape, ...], theme: Theme = DEFAULT_THEME)

A figure, ready to be written as SVG or TikZ.

Attributes:

Name Type Description
name str

File stem, for example "performance-profile".

title str

Title, drawn at the top and stored as the SVG title.

description str

Text alternative: what the figure shows, stored as the SVG description and as comments in the TikZ document.

width float

Canvas width in pixels.

height float

Canvas height in pixels.

shapes tuple[Shape, ...]

What is drawn, in painting order.

theme Theme

The theme the layout was computed with.

svg

svg() -> str

Return the figure as a standalone SVG document.

tex

tex() -> str

Return the figure as a standalone LaTeX document holding one TikZ picture.

render

render(fmt: str) -> str

Return the figure in format "svg" or "tex".

Raises:

Type Description
ValueError

For another format.

number

number(value: float) -> str

Format a coordinate: at most two decimals, no trailing zeros, no negative zero.

Raises:

Type Description
ValueError

If value is not finite.

text_width

text_width(text: str, size: float) -> float

Return a generous estimate of the width of text set at size pixels.

truncate

truncate(text: str, size: float, width: float) -> str

Return text shortened so that it fits in width pixels.

The middle gives way to an ellipsis, so that names that differ only at their end, such as numbered variants, stay apart.

wrap

wrap(text: str, size: float, width: float) -> list[str]

Break text into lines that fit in width pixels, at spaces where possible.

bounds

bounds(shape: Shape) -> tuple[float, float, float, float]

Return a shape's extent as (left, top, right, bottom), estimating text size.

dispatchatlas.analysis.figures.theme

Colours, type sizes, and canvas dimensions shared by every figure.

A Theme fixes everything about a figure's appearance that is not data: the canvas width, the height of a plot area, the series palette, the colours of text and axes, and the type sizes. Figures are laid out in pixels; the TikZ output maps one pixel to Theme.tex_scale big points, so the two formats share one layout.

The series palette is the colour-universal-design palette of Okabe and Ito, as published by Wong (2011): eight colours that stay distinguishable under the common forms of colour-vision deficiency. Series beyond the eighth reuse a colour, so every series also gets a marker shape and, from the ninth on, a dash pattern; the triple (colour, marker, dash) is unique for the first 168 series.

PALETTE module-attribute

PALETTE: tuple[str, ...] = ('#0072B2', '#D55E00', '#009E73', '#CC79A7', '#E69F00', '#56B4E9', '#000000', '#F0E442')

The Okabe-Ito palette, ordered so that yellow, the colour with the least contrast on white, comes last.

PALETTE_REFERENCE module-attribute

PALETTE_REFERENCE = 'wong2011points'

Bibliography key of the source of PALETTE.

MARKERS module-attribute

MARKERS: tuple[str, ...] = ('circle', 'square', 'triangle', 'diamond', 'triangle-down', 'cross', 'plus')

Marker shapes, assigned to series in turn.

DASHES module-attribute

DASHES: tuple[tuple[float, ...], ...] = ((), (6.0, 3.0), (1.5, 2.5))

Dash patterns in pixels: solid for the first eight series, then dashed, then dotted.

DEFAULT_THEME module-attribute

DEFAULT_THEME = Theme()

The theme figures use unless given another.

SeriesStyle dataclass

SeriesStyle(color: str, marker: str, dash: tuple[float, ...])

How one series is drawn.

Attributes:

Name Type Description
color str

Hexadecimal #RRGGBB colour.

marker str

One of MARKERS.

dash tuple[float, ...]

Dash pattern in pixels, empty for a solid line.

Theme dataclass

Theme(width: float = 720.0, plot_height: float = 300.0, palette: tuple[str, ...] = PALETTE, foreground: str = '#1F2328', muted: str = '#57606A', axis: str = '#57606A', grid: str = '#D8DEE4', background: str = '#FFFFFF', font_family: str = 'Helvetica, Arial, sans-serif', title_size: float = 15.0, label_size: float = 13.0, tick_size: float = 11.0, legend_size: float = 12.0, note_size: float = 11.0, line_width: float = 1.8, tex_scale: float = 0.6)

The appearance of a figure.

Attributes:

Name Type Description
width float

Canvas width in pixels.

plot_height float

Height of the plot area of a chart with a numeric vertical axis, in pixels. Charts with one row per category grow with the number of rows instead.

palette tuple[str, ...]

Series colours, as #RRGGBB.

foreground str

Colour of text.

muted str

Colour of secondary text, such as notes.

axis str

Colour of axis lines and ticks.

grid str

Colour of grid lines.

background str

Canvas colour.

font_family str

CSS font family of the SVG output. The TikZ output uses the document's font.

title_size float

Title type size, in pixels.

label_size float

Axis-title type size.

tick_size float

Tick-label type size.

legend_size float

Legend type size.

note_size float

Note and caption type size.

line_width float

Width of series lines, in pixels.

tex_scale float

Big points per pixel in the TikZ output. The default maps the 720-pixel canvas to 432 bp, the width of a text block.

series

series(index: int) -> SeriesStyle

Return the style of the series at position index, from 0.

dispatchatlas.analysis.figures.svg

Writing figures as SVG documents.

The document is ASCII: characters outside it are written as numeric character references. Every colour is written as a presentation attribute, so any SVG renderer shows the figure as designed, and the elements that a page may want to restyle carry classes (da-axis, da-grid, da-text). The theme's colours and font are also published as CSS custom properties (--da-fg, --da-axis, --da-grid, --da-font) in the style attribute of the svg element itself, so they are scoped to the figure: an SVG inlined in a web page neither reads nor overrides the page's own variables. The embedded style sheet only refers to those variables, and only elements drawn in the theme's own text, note, axis, and grid colours carry the classes it styles, so series colours are never overridden.

escape

escape(text: str) -> str

Escape text for SVG content or attributes, as ASCII.

The five XML special characters become entities, other non-ASCII characters become numeric references, and control characters, which XML forbids, are dropped.

to_svg

to_svg(figure: Figure) -> str

Return figure as a standalone SVG document, ending with a newline.

marker_outline

marker_outline(marker: Marker) -> tuple[Point, ...]

Return the corners of a polygonal marker: square, diamond, or triangle.

dispatchatlas.analysis.figures.tex

Writing figures as standalone LaTeX documents holding one TikZ picture.

The document needs only the tikz package. Its single tikzpicture uses the pixel coordinates of the SVG version, scaled by tex_scale big points per pixel and with the y axis flipped, so both formats share one layout. The colour definitions sit inside the picture, which can therefore be copied into another document as it is. Plain TikZ rather than PGFPlots keeps the output independent of PGFPlots versions and lets the SVG and TikZ versions agree to the coordinate.

Text is escaped for LaTeX, and the few non-ASCII characters figures use, such as Greek letters in axis titles, are written as LaTeX commands, so the file is ASCII and compiles with the default font encoding. Type sizes map to the nearest standard size command. The title and description open the file as comments.

tex_escape

tex_escape(text: str) -> str

Return text as LaTeX source that typesets it literally, in ASCII.

Special characters become commands, the symbols figures use (Greek letters, comparison signs, dashes) become their LaTeX forms, accented Latin letters become accent commands, and any other non-ASCII character becomes a question mark.

ascii_text

ascii_text(text: str) -> str

Return text folded to plain ASCII, for comments: accents dropped, symbols spelled.

to_tex

to_tex(figure: Figure) -> str

Return figure as a standalone LaTeX document, ending with a newline.