Trains a StarDist model on a prepared instance dataset. All data checks
run in R before Python is touched: the dataset must be an instance
dataset without split leakage, every training mask must be integer with
background 0 and one connected part per positive id, and the training
split must not be empty. Only then is the optional Python runtime
(stardist, tensorflow, csbdeep through reticulate) checked; when it
is missing an sg_capability_error with code CAPABILITY_UNAVAILABLE
and an installation hint is signalled.
Arguments
- training_data
An
sg_training_setfromsg_prepare_training_data()(in memory or on disk), or the path of a prepared dataset directory.- base_model
Optional pretrained StarDist model name to fine-tune (e.g.
"2D_versatile_fluo");NULLtrains from a new configuration. Fine-tuning copies its configuration and weights into a new model undersave_path/name, preserving the pretrained architecture and cache.- n_epochs, steps_per_epoch
Training length.
- learning_rate
Adam learning rate.
- n_rays
Number of radial directions for a new model. Fine-tuning preserves the pretrained architecture.
- grid
Subsampling grid (length 2) for a new model.
- normalize
Percentiles (length 2) for per-tile normalisation, recorded in the model card.
- save_path
Directory for the trained model (default: a temporary directory).
- name
Model name (one directory component below
save_path). An existing model destination is rejected rather than overwritten.- model_card
Model card fields (purpose, data_domain, limitations, license, ...), see
new_sg_trained_model().- seed
Integer seed passed to the Python random number generators.
- verbose
Logical; print progress.
Value
An sg_trained_model with backend "stardist", the dataset
manifest, runtime description and evaluation metrics (validation split
thresholds when available). The model path contains saved configuration
and weights, and the requested learning rate applies to both new models
and fine-tuning.
Examples
# \donttest{
img <- sg_example_image("fluorescence_nuclei")
msk <- sg_cleanup_labels(sg_example_mask("fluorescence_nuclei"),
disconnected = "split")
ts <- sg_prepare_training_data(
list(list(image = img, mask = msk, subject_id = "A"),
list(image = img, mask = msk, subject_id = "B")),
tile_size = 32L, split = c(train = 0.5, validation = 0.5, test = 0)
)
# Requires Python stardist; otherwise a classified capability error:
try(sg_train_stardist(ts, n_epochs = 1L))
#> Error in .sg_abort_unavailable("StarDist training (Python stardist + tensorflow)", :
#> StarDist training (Python stardist + tensorflow) is not available.
#> ℹ Install the Python packages 'stardist' and 'tensorflow'
#> (sg_setup_python(backends = 'stardist')).
# }