CAREamist

The CAREamist is the central class in CAREamics, it provides the API to train, predict and save models. There are three ways to create a CAREamist object: with a configuration, with a path to a configuration, or with a path to a trained model.

Instantiating with a configuration

When passing a configuration to the CAREamist constructor, the model is initialized with random weights and prediction will not be possible until the model is trained.

from careamics import CAREamist
from careamics.config import create_n2v_configuration

config = create_n2v_configuration(
    experiment_name="n2v_2D",
    data_type="array",
    axes="YX",
    patch_size=[64, 64],
    batch_size=8,
    num_epochs=20,
)  # (1)!

careamist = CAREamist(config)

1. Any valid configuration will do!

Instantiating with a path to a configuration

This is similar to the previous section, except that the configuration is loaded from a file on disk.

from careamics import CAREamist
from careamics.config import create_n2v_configuration
from careamics.config.utils.configuration_io import save_configuration

config = create_n2v_configuration(
    experiment_name="n2v_2D",
    data_type="array",
    axes="YX",
    patch_size=[64, 64],
    batch_size=8,
    num_epochs=20,
)

save_configuration(config, "configuration_example.yml")

careamist = CAREamist("configuration_example.yml")

Instantiating with a path to a model

There are two types of models exported from CAREamics. During training, the model is saved as checkpoints (.ckpt). After training, users can export the model to the bioimage model zoo format (saved as a.zip). Both can be loaded into CAREamics to either retrain or predict. Alternatively, a checkpoint can be loaded in order to export it as a bioimage model zoo model.

In any case, both types of pre-trained models can be loaded into CAREamics by passing the path to the model file. The instantiated CAREamist is then ready to predict on new images!

from careamics import CAREamist

path_to_model = "model.zip"  # (1)!

careamist = CAREamist(path_to_model)

1. Any valid path to a model, as a string or a Path.path object, will work.

Setting the working directory

By default, CAREamics will save the checkpoints in the current working directory. When creating a new CAREamist, you can indicate a different working directory in which to save the logs and checkpoints during training.

careamist = CAREamist(config, work_dir="work_dir")

Custom callbacks

CAREamics uses two different callbacks from PyTorch Lightning:

• ModelCheckpoint: to save the model at different points during the training.
• EarlyStopping: to stop the training based on a few parameters.

The parameters for the callbacks are the same as the ones from PyTorch Lightning, and can be set in the configuration.

Custom callbacks can be passed to the CAREamist constructor. The callbacks must inherit from the PyTorch Lightning Callback class.

from pytorch_lightning.callbacks import Callback


# define a custom callback
class MyCallback(Callback):  # (1)!
    def __init__(self):
        super().__init__()

        self.has_started = False
        self.has_ended = False

    def on_train_start(self, trainer, pl_module):
        self.has_started = True  # (2)!

    def on_train_end(self, trainer, pl_module):
        self.has_ended = True


my_callback = MyCallback()  # (3)!

careamist = CAREamist(config, callbacks=[my_callback])  # (4)!

1. The callbacks must inherit from the PyTorch Lightning Callback class.

2. This is just an example to test that the callback was called!

3. Create your callback.

4. Pass the callback to the CAREamist constructor as a list.