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:
frames: the runs, one outcome policy, and explicit aggregation over replicates;profiles,traces,ranking,distribution,pareto, andgantt: each family's data and figure;catalog: the list of families andrender_figures();chart,axes,drawing,theme,svg, andtex: the drawing kernel.
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
¶
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. |
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
|
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 |
FORMATS
|
config
|
AnalysisConfig | None
|
The analysis settings, the defaults when |
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 |
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
runsattribute holding run records and, optionally, afailuresattribute holdingFailureRecordobjects.
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
¶
How the replicates of a solver on a problem become one value.
Budget
¶
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
|
|
record |
RunRecord | None
|
The run record of a completed run. |
succeeded
property
¶
Whether the run completed with a feasible schedule and a value.
progress
¶
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]
|
|
...
|
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. |
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 |
target_sense |
Sense | None
|
The analysed objective's sense, or |
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
¶
Return the primary objective a problem declares, or None when unknown.
objective
¶
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
¶
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
¶
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
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
|
problems
|
Iterable[str] | None
|
Problem ids to keep, or |
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 |
required |
sense
|
Sense | None
|
Its sense, or |
None
|
Raises:
| Type | Description |
|---|---|
ConfigError
|
If a problem whose objectives are known does not
declare |
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
¶
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 |
start |
float
|
The worst first feasible value of a succeeded run. |
gap
¶
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 |
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 |
lower_median
¶
Return the lower median: the middle value, or the lower of the two middle values.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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
|
|
required |
Returns:
| Type | Description |
|---|---|
float
|
The aggregated score, infinite for a cell without runs. |
check_aggregation
¶
check_aggregation(value: object) -> Aggregation
quality_ranges
¶
quality_ranges(observations: Observations, budget: Budget) -> dict[str, QualityRange]
Return the span of values found on each problem where some run succeeded.
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
tauof the best solver's; - the data profile of Moré and Wild (2009): the share of problems a
solver solves to accuracy
tauwithin 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
¶
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 of the runtime distribution, as shares of a problem's span of values.
ProfileCurve
dataclass
¶
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. |
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
¶
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. |
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 |
unit |
str
|
What a unit of budget is: |
knots |
tuple[float, ...]
|
The finite budgets where some curve steps, ascending. |
aggregation |
Aggregation
|
How the runs of a cell were aggregated. |
points
¶
Return a solver's (budget, share) pairs at every knot.
Raises:
| Type | Description |
|---|---|
ConfigError
|
If the profile has no such solver. |
RuntimeCurve
dataclass
¶
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], ...]
|
|
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 |
required |
aggregation
|
str
|
|
'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 |
required |
accuracy
|
float
|
The accuracy |
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'
|
Returns:
| Type | Description |
|---|---|
DataProfile
|
The profiles. |
Raises:
| Type | Description |
|---|---|
ConfigError
|
If |
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 |
required |
targets
|
Sequence[float]
|
Target levels between 0 (the best value found) and 1. |
QUALITY_TARGETS
|
budget
|
str
|
|
'time'
|
Returns:
| Type | Description |
|---|---|
RuntimeDistribution
|
The distributions. |
Raises:
| Type | Description |
|---|---|
ConfigError
|
If a target is outside |
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 |
required |
budget
|
str
|
|
'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, |
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 |
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 |
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
|
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
|
required |
config
|
AnalysisConfig | None
|
The analysis settings, the defaults when |
None
|
Returns:
| Type | Description |
|---|---|
RankDiagram
|
The diagram, with |
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 |
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
|
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
|
|
attainment_surface
¶
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 |
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
|
required |
aggregation
|
str
|
|
'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 |
Figure
|
cannot name a file replaced by |
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
¶
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']
|
|
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
|
required |
Returns:
| Type | Description |
|---|---|
Observation | None
|
The run, or |
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 |
style |
SeriesStyle
|
Colour, marker, and dash. |
kind |
Literal['line', 'step', 'points']
|
|
markers |
bool
|
Draw |
band |
tuple[tuple[float, float, float], ...]
|
|
until |
float | None
|
For a step function, the |
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']
|
|
Guide
dataclass
¶
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
¶
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
¶
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
|
|
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 |
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
¶
Return a figure that states why there is nothing to draw.
label_for
¶
Return the display label of an id: its entry in labels, else the id itself.
draw_title
¶
Add the title, wrapped to the canvas, and return the height it takes.
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 |
log |
bool
|
Whether the scale is logarithmic; then |
ticks |
tuple[float, ...]
|
Tick positions within |
labels |
tuple[str, ...]
|
The label of each tick. |
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
¶
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
¶
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 |
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.
Anchor
¶
Which point of a text its position names: its start, middle, or end.
Stroke
dataclass
¶
How a line is drawn.
Attributes:
| Name | Type | Description |
|---|---|---|
color |
str
|
|
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
¶
Polyline
dataclass
¶
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
|
|
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
|
|
opacity |
float
|
Fill opacity from 0 to 1. |
stroke |
Stroke | None
|
Outline, or |
tooltip |
str
|
Text a viewer shows on hovering, SVG only. |
Marker
dataclass
¶
A data marker centred on a point.
Attributes:
| Name | Type | Description |
|---|---|---|
x |
float
|
Centre. |
y |
float
|
Centre. |
shape |
str
|
One of |
size |
float
|
Radius of the circle that holds the shape, in pixels. |
color |
str
|
|
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
|
|
anchor |
Anchor
|
Which point of the text |
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 |
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. |
number
¶
Format a coordinate: at most two decimals, no trailing zeros, no negative zero.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
text_width
¶
Return a generous estimate of the width of text set at size pixels.
truncate
¶
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
¶
Break text into lines that fit in width pixels, at spaces where possible.
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.
MARKERS
module-attribute
¶
MARKERS: tuple[str, ...] = ('circle', 'square', 'triangle', 'diamond', 'triangle-down', 'cross', 'plus')
Marker shapes, assigned to series in turn.
DASHES
module-attribute
¶
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
¶
How one series is drawn.
Attributes:
| Name | Type | Description |
|---|---|---|
color |
str
|
Hexadecimal |
marker |
str
|
One of |
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 |
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 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.
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
¶
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
¶
Return text folded to plain ASCII, for comments: accents dropped, symbols spelled.