Reference

A specification

One object says what to train, on what data, with what. Built from a dict or from YAML - the same specification either way, and task decides its shape.

from_dict	Validate a dict into a spec, raising ConfigError with every problem at once.
from_yaml	Read a YAML file into a spec: the same object from_dict builds, by the same rules.
save_spec	Write a specification back out as YAML - what was set, not what it holds.
SegmentationSpec
InstanceSpec	Objects rather than classes: which object every pixel belongs to, scored as instances.
DetectionSpec
PlatypusSpec	The shared base of SegmentationSpec and DetectionSpec.
Task	What the models in a spec are being asked to do.
Separation	The signal that makes one mask into many objects.
spec_schema	The JSON Schema for a specification, generated from the models themselves.
write_schema	Write the schema to a file, creating the directory if it is not there.

What a model is made of

Losses, metrics, optimisers, callbacks and augmentation are named in the specification rather than constructed, so their fields are documented in the schema. These ask the package what those names are, read from the same models the schema is generated from - so a loss added to the engine appears in the listing with no second list to update.

available_tasks	What this package can be asked to do at all.
available_models	The architectures this package can build for a task.
available_losses	The losses you can name under loss, which is not the same list at every task.
available_metrics	The metrics you can name under metrics.
available_optimizers	The optimisers you can name under optimizer. The same set for either task.
available_callbacks	The callbacks you can name under callbacks. The same set for either task.
available_decodings	The decodings you can name in decode, and which separation signal each one reads.
available_separations	The separation signals you can name under separation, and what each one costs.
available_transforms	Transform names the installed albumentations actually offers.

The data on disk

Splitting by patient rather than by slice, and looking at what will actually be read before spending an afternoon training on it.

read_image	Read one image or volume as a channels-last array.
split_dataset	Split one folder of data into three CSVs a specification can point at.
split_samples	Divide samples between the splits, keeping every group whole.
Engine.dataset	only_images defaults to what the split actually has rather than to False.
Engine.loader	A torch DataLoader over one split, wrapping dataset.
InstanceEngine.dataset	One split as (image, instance target) pairs.
InstanceEngine.loader	A torch DataLoader over one split, wrapping dataset.
DetectionEngine.dataset	The dataset for one split: images letterboxed to input_shape, boxes encoded.
DetectionEngine.loader	A torch DataLoader over one split, wrapping dataset.

Training

The engine the task asks for, and the run itself.

build_engine	The engine this spec’s task asks for.
Engine
Engine.fit	Train every model the spec asks for, in order.
InstanceEngine	Many instance models, one spec. What platypus_fit(spec) will call for this task.
InstanceEngine.fit	Train every model the spec asks for, in order.
DetectionEngine
DetectionEngine.fit	Train every model in the specification, in turn, against the same data.
DetectionEngine.fit_anchors	k-means with an IoU distance over the training boxes, or nothing to do.

Predicting and scoring

Per model, per case, per class, per image - and the distribution rather than a single number, because the minimum is what nobody publishes and everybody should.

Engine.predict	Class probabilities, channels-last, one array per source image.
Engine.predict_stream	(case, prediction) one source image at a time, instead of all of them at once.
Engine.evaluate	One row per model: the comparison table the whole multi-model idea is for.
Engine.evaluate_cases	One row per case instead of one row per model.
summarise_cases	Turn per-case rows into the distribution, one row per metric.
Engine.best_model	Rank the models on one column.
InstanceEngine.predict	The model’s own channels, channels-last, one array per source image, stacked.
InstanceEngine.predict_instances	One label map per source image: objects numbered from 1.
InstanceEngine.evaluate	One row per model and decoding: the comparison this task is for.
InstanceEngine.evaluate_cases	One row per case instead of one row per model, for one decoding.
InstanceEngine.best_model	Which model scored best, by one column of evaluate.
DetectionEngine.predict	Boxes, scores and labels for every image in a split, in its own pixels.
DetectionEngine.evaluate	One row per model: the comparison table, with detection’s columns.
DetectionEngine.evaluate_classes	One row per class instead of one row per model.
DetectionEngine.evaluate_images	One row per image instead of one row per model or per class.
DetectionEngine.best_model	Which model scored highest on one column.
DetectionEngine.crops	Every detection cut out of the image it was found in.
DetectionReport	One model on one split, under the three sets of conventions a table needs.
DetectionEngine.report	Everything a detection table is read off, from one pass over the split.
DetectionEngine.anchor_coverage	How well the anchors in use cover this split’s boxes.
DetectionEngine.box_shapes	The cloud of box shapes in a split, with the anchors in use beside it.
DetectionEngine.split_sizes	How many images each split holds, and in which order they were found.
DetectionEngine.model_names	The models that have been fitted or loaded, in the order they were.

Weights

Named rather than downloaded by hand, and a name is pinned to one commit - so a name means one set of numbers today and the same set next year.

available_weights	Registry names and what they are, for listing to a user.
resolve_weights	Turn any of the three forms into a local file, downloading if it has to.
export_weights	Write a model’s weights as safetensors, with the sidecar that describes them.
Engine.export_weights	Write one trained model’s weights, ready to publish or to load again later.
InstanceEngine.export_weights	Write one trained model’s weights, with the sidecar that says what they are for.
DetectionEngine.export_weights	Write one detector’s weights, with the anchors in the sidecar.

Records

What a run wrote down about itself, including the engine version that made it.

write_record	Write <output_dir>/<name>/run.json and return its path.
read_record	A record back off disk. Plain data; from_dict(record["specification"]) runs it.

Looking at the results

The decisions a drawing makes, held here so the R package and this one cannot disagree about what red means. Until 0.8.0a1 this group existed only in the R package, because the engine carried no plotting at all.

plot_masks	Images, their masks and where the two disagree, one row per image.
plot_boxes	Detections drawn on the images they were found in, one row per image.
plot_anchors	Fitted anchors against the box shapes they were fitted to.
overlay_mask	An image with a mask tinted onto it.
overlay_agreement	An image showing what was found, what was missed and what was invented.
overlay_instances	An instance label map over its image, coloured so no two touching objects match.
overlay_instance_agreement	Found, missed and invented objects, matched the way the metric matches them.
flow_to_colours	A two-channel vector field as a picture: hue is the direction, value is the length.
drawing_style	Every decision above, in one mapping.

Masks and volumes

Overlapping classes cannot be one picture, so they are one picture each. The rest of this group is R’s: reading and uniting masks is where an R user meets them.

save_class_masks

One binary picture per class, which is how an overlapping prediction reaches disk.

When something is wrong

Three kinds, because they are three different problems: a configuration that cannot be read, an engine that cannot run it, and weights that do not belong to the model.

PlatypusError	Base class, so R can catch one thing.
ConfigError	A spec that does not describe a runnable experiment.
WeightsError