Package 'mlr3torch'

Description

Deep Learning library that extends the mlr3 framework by building upon the 'torch' package. It makes it convenient to build, train, and evaluate deep learning models without having to worry about low level details. Custom architectures can be created using the graph language defined in 'mlr3pipelines'.

Options

• mlr3torch.cache: Whether to cache the downloaded data (TRUE) or not (FALSE, default). This can also be set to a specific folder on the file system to be used as the cache directory. Without caching, every task that downloads its data fetches it again in each session.

Author(s)

Maintainer: Sebastian Fischer [email protected] (ORCID)

Authors:

• Sebastian Fischer [email protected] (ORCID)

• Martin Binder [email protected]

Other contributors:

• Bernd Bischl [email protected] (ORCID) [contributor]

• Lukas Burk [email protected] (ORCID) [contributor]

• Florian Pfisterer [email protected] (ORCID) [contributor]

• Carson Zhang [email protected] [contributor]

See Also

Useful links:

• https://mlr3torch.mlr-org.com/

• https://github.com/mlr-org/mlr3torch/

• Report bugs at https://github.com/mlr-org/mlr3torch/issues

Description

Converts the input to a DataDescriptor.

Usage

as_data_descriptor(x, dataset_shapes, ...)

Arguments

Examples

ds = dataset("example",
  initialize = function() self$iris = iris[, -5],
  .getitem = function(i) list(x = torch_tensor(as.numeric(self$iris[i, ]))),
  .length = function() nrow(self$iris)
)()
as_data_descriptor(ds, list(x = c(NA, 4L)))

# if the dataset has a .getbatch method, the shapes are inferred
ds2 = dataset("example",
  initialize = function() self$iris = iris[, -5],
  .getbatch = function(i) list(x = torch_tensor(as.matrix(self$iris[i, ]))),
  .length = function() nrow(self$iris)
)()
as_data_descriptor(ds2)

Description

Converts an object to a lazy_tensor. A dataset is wrapped as-is, a torch_tensor or a numeric() is first turned into a dataset whose first dimension indexes the observations.

Usage

as_lazy_tensor(x, ...)

## S3 method for class 'dataset'
as_lazy_tensor(x, dataset_shapes = NULL, ids = NULL, ...)

Arguments

Examples

iris_ds = dataset("iris",
  initialize = function() {
    self$iris = iris[, -5]
  },
  .getbatch = function(i) {
    list(x = torch_tensor(as.matrix(self$iris[i, ])))
  },
  .length = function() nrow(self$iris)
)()
# no need to specify the dataset shapes as they can be inferred from the .getbatch method
# only first 5 observations
as_lazy_tensor(iris_ds, ids = 1:5)
# all observations
head(as_lazy_tensor(iris_ds))

iris_ds2 = dataset("iris",
  initialize = function() self$iris = iris[, -5],
  .getitem = function(i) list(x = torch_tensor(as.numeric(self$iris[i, ]))),
  .length = function() nrow(self$iris)
)()
# if .getitem is implemented we cannot infer the shapes as they might vary,
# so we have to annotate them explicitly
as_lazy_tensor(iris_ds2, dataset_shapes = list(x = c(NA, 4L)))[1:5]

# Convert a matrix
lt = as_lazy_tensor(matrix(rnorm(100), nrow = 20))
materialize(lt[1:5], rbind = TRUE)

Description

Converts a Graph representing a deep learning pipeline into a GraphLearnerTorch. The graph either builds the network from PipeOpTorch operators and ends in a PipeOpTorchModel, or its base learner is a LearnerTorch, e.g. po("scale") %>>% lrn("classif.mlp"). The advantage over using as_learner() is that the resulting learner exposes methods like ⁠$dataset()⁠ and fields like ⁠$network⁠.

Usage

as_learner_torch(x, ...)

## S3 method for class 'Graph'
as_learner_torch(x, id = NULL, ...)

## S3 method for class 'PipeOp'
as_learner_torch(x, ...)

## S3 method for class 'GraphLearner'
as_learner_torch(x, id = x$id, ...)

Arguments

Value

GraphLearner

See Also

Other Graph Network: ModelDescriptor(), TorchIngressToken(), mlr_learners_torch_model, mlr_pipeops_module, mlr_pipeops_torch, mlr_pipeops_torch_ingress, mlr_pipeops_torch_ingress_categ, mlr_pipeops_torch_ingress_ltnsr, mlr_pipeops_torch_ingress_num, model_descriptor_to_learner(), model_descriptor_to_module(), model_descriptor_union(), nn_graph(), pipeop_torch()

Other Learner: GraphLearnerTorch, mlr_learners.ft_transformer, mlr_learners.mlp, mlr_learners.module, mlr_learners.realmlp, mlr_learners.tab_resnet, mlr_learners.tabm, mlr_learners.torch_featureless, mlr_learners_torch, mlr_learners_torch_image, mlr_learners_torch_model

Examples

graph = po("scale") %>>%
  po("torch_ingress_num") %>>%
  nn("linear", out_features = 10) %>>%
  nn("relu") %>>%
  nn("head") %>>%
  po("torch_loss", "cross_entropy") %>>%
  po("torch_optimizer", "adam", lr = 0.1) %>>%
  po("torch_model_classif", epochs = 1, batch_size = 32)

learner = as_learner_torch(graph)
learner$id
learner$param_set$set_values(linear.out_features = 20, torch_optimizer.lr = 0.01)

task = tsk("iris")
learner$train(task)
learner$network
learner$predict(task)

learner$dataset(task, "train")

Description

Convert a torch scheduler generator to a CallbackSetLRScheduler.

Usage

as_lr_scheduler(x, step_on_epoch)

Arguments

Description

Creates a TaskTorch, the general-purpose task type of mlr3torch, from a data.frame() or a DataBackend. See the Custom Learning Problems article for more information.

Usage

as_task_torch(x, target = NULL, id = deparse(substitute(x))[1L], ...)

Arguments

Value

TaskTorch

Examples

# multi-output regression
d = data.frame(x = rnorm(50))
d$y1 = d$x + rnorm(50)
d$y2 = 2 * d$x + rnorm(50)
as_task_torch(d, target = c("y1", "y2"))

# unsupervised: no target at all
as_task_torch(data.frame(a = rnorm(50), b = rnorm(50)))

Description

Converts an object to a TorchCallback.

Usage

as_torch_callback(x, clone = FALSE, ...)

Arguments

Value

TorchCallback.

See Also

Other Callback: TorchCallback, as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.tb, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Description

Converts an object to a list of TorchCallback.

Usage

as_torch_callbacks(x, clone, ...)

Arguments

Value

list() of TorchCallbacks

See Also

Other Callback: TorchCallback, as_torch_callback(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.tb, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Other Torch Descriptor: TorchCallback, TorchDescriptor, TorchLoss, TorchOptimizer, as_torch_loss(), as_torch_optimizer(), mlr3torch_losses, mlr3torch_optimizers, t_clbk(), t_loss(), t_opt()

Description

Converts an object to a TorchLoss.

Usage

as_torch_loss(x, clone = FALSE, ...)

Arguments

Value

TorchLoss.

See Also

Other Torch Descriptor: TorchCallback, TorchDescriptor, TorchLoss, TorchOptimizer, as_torch_callbacks(), as_torch_optimizer(), mlr3torch_losses, mlr3torch_optimizers, t_clbk(), t_loss(), t_opt()

Examples

# Define a custom loss, here the quantile (pinball) loss for quantile regression.
# The class must contain "nn_loss", as this is what as_torch_loss() dispatches on.
nn_quantile_loss = nn_module(c("nn_quantile_loss", "nn_loss"),
  initialize = function(q = 0.5) {
    self$q = q
  },
  forward = function(input, target) {
    d = target - input
    torch_mean(torch_max(self$q * d, other = (self$q - 1) * d))
  }
)

# additional arguments are passed to the TorchLoss constructor
quantile_loss = as_torch_loss(nn_quantile_loss, task_types = "regr")
quantile_loss
# the parameters are inferred from the loss' initialize method
quantile_loss$param_set
# and can be configured when using the loss in a learner
lrn("regr.mlp", loss = quantile_loss, loss.q = 0.9)

# predefined losses can be converted from their key,
# this is the same as t_loss("mse")
as_torch_loss("mse")

# TorchLosses are returned as-is, unless clone is TRUE
loss = t_loss("mse")
identical(as_torch_loss(loss), loss)
identical(as_torch_loss(loss, clone = TRUE), loss)

Description

Converts an object to a TorchOptimizer.

Usage

as_torch_optimizer(x, clone = FALSE, ...)

Arguments

Value

TorchOptimizer

See Also

Other Torch Descriptor: TorchCallback, TorchDescriptor, TorchLoss, TorchOptimizer, as_torch_callbacks(), as_torch_loss(), mlr3torch_losses, mlr3torch_optimizers, t_clbk(), t_loss(), t_opt()

Examples

# convert a `torch::torch_optimizer_generator`
as_torch_optimizer(optim_adamw)
# the id defaults to the name of the generator, but can be overwritten
as_torch_optimizer(optim_adamw, id = "my_adamw", label = "My AdamW")

# convert a key of mlr3torch_optimizers, this is the same as t_opt("adamw")
as_torch_optimizer("adamw")

# TorchOptimizers are returned as-is, unless clone is TRUE
opt = t_opt("adamw")
identical(as_torch_optimizer(opt), opt)
identical(as_torch_optimizer(opt, clone = TRUE), opt)

Description

Rejects a dim parameter that does not address a dimension of shape. Resolve negative indices with resolve_dim() first and pass both, so that the error message can report the value the user actually specified.

Usage

assert_dim_in_range(dim, true_dim, shape, id)

Arguments

Value

The resolved dimension, invisibly.

See Also

Other Shape Assertions: assert_known_dims(), assert_ndim(), assert_not_batch_dim(), assert_positive_extent(), assert_same_batch_size(), assert_same_ndim(), assert_shape(), assert_shapes()

Examples

shape = c(NA, 3, 8, 8)
assert_dim_in_range(-1L, resolve_dim(-1L, shape), shape, id = "nn_squeeze")
try(assert_dim_in_range(-5L, resolve_dim(-5L, shape), shape, id = "nn_squeeze"))

Description

Ensure that a specific dimension is known, i.e. not NA.

Usage

assert_known_dims(shape, dims, what, id = NULL)

Arguments

Value

The shape, invisibly.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_ndim(), assert_not_batch_dim(), assert_positive_extent(), assert_same_batch_size(), assert_same_ndim(), assert_shape(), assert_shapes()

Examples

# a convolution needs the number of input channels, but not the spatial extent
assert_known_dims(c(NA, 3, NA, NA), 2, "the number of channels", id = "nn_conv2d")
try(assert_known_dims(c(NA, NA, 10, 10), 2, "the number of channels", id = "nn_conv2d"))

Description

Asserts whether something is a lazy tensor.

Usage

assert_lazy_tensor(x)

Arguments

Description

Rejects a shape with the wrong number of dimensions. Give either ndim, the number(s) of dimensions the operator accepts, or the bounds min and max (either on its own), which is what an operator that accepts a range of them uses, as batch normalization does.

Usage

assert_ndim(shape, ndim = NULL, id, min = NULL, max = NULL)

Arguments

Value

The shape, invisibly.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_not_batch_dim(), assert_positive_extent(), assert_same_batch_size(), assert_same_ndim(), assert_shape(), assert_shapes()

Examples

assert_ndim(c(NA, 3, 32, 32), 4L, id = "nn_conv2d")
try(assert_ndim(c(NA, 3), 4L, id = "nn_conv2d"))
# batch normalization accepts a range
try(assert_ndim(c(NA, 3, 4, 5), id = "nn_batch_norm1d", min = 2L, max = 3L))

Description

Rejects an operation on the first dimension, which is the batch dimension. An operator that changes it would silently change the number of observations, which fails much later with a mismatch against the target.

Usage

assert_not_batch_dim(dim, shape, id)

Arguments

Value

The dimension, invisibly.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_ndim(), assert_positive_extent(), assert_same_batch_size(), assert_same_ndim(), assert_shape(), assert_shapes()

Examples

assert_not_batch_dim(2L, c(NA, 3, 8), id = "nn_squeeze")
try(assert_not_batch_dim(1L, c(NA, 3, 8), id = "nn_squeeze"))

Description

Rejects a computed output size that no tensor can have, i.e. one that is not a positive number. Operators such as convolutions and pooling compute their spatial output sizes from kernel_size, stride, padding and dilation, a combination of which can produce a size of zero or less. Unknown (NA) sizes are accepted, since nothing can be said about them.

Usage

assert_positive_extent(extent, shape_in, id)

Arguments

Value

The extent, invisibly.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_ndim(), assert_not_batch_dim(), assert_same_batch_size(), assert_same_ndim(), assert_shape(), assert_shapes()

Examples

assert_positive_extent(c(30, NA), c(NA, 3, 32, 32), id = "nn_conv2d")
try(assert_positive_extent(c(0, 4), c(NA, 3, 32, 32), id = "nn_conv2d"))

Description

Rejects inputs whose batch sizes, i.e. first dimensions, disagree. An unknown (NA) batch size is compatible with any other, so only the known ones have to agree.

Unlike the other assertions this returns the common batch size rather than its input, because that is what the caller needs next: an operator that drops the batch dimension while it works has to put it back afterwards.

Usage

assert_same_batch_size(shapes, id)

Arguments

Value

(integer(1)) The common batch size, invisibly, or NA_integer_ if no input has a known one.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_ndim(), assert_not_batch_dim(), assert_positive_extent(), assert_same_ndim(), assert_shape(), assert_shapes()

Examples

assert_same_batch_size(list(c(8, 3), c(8, 5)), id = "nn_block")
# an unknown batch size is compatible with a known one, which is the one that is returned
assert_same_batch_size(list(c(NA, 3), c(8, 5)), id = "nn_block")
try(assert_same_batch_size(list(c(8, 3), c(4, 5)), id = "nn_block"))

Description

Rejects inputs that do not all have the same number of dimensions, which the operators that combine several inputs require: shorter shapes are not left-padded with 1s, because the first dimension is the batch dimension.

Usage

assert_same_ndim(shapes, id)

Arguments

Value

The shapes, invisibly.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_ndim(), assert_not_batch_dim(), assert_positive_extent(), assert_same_batch_size(), assert_shape(), assert_shapes()

Examples

assert_same_ndim(list(c(NA, 3), c(NA, 5)), id = "nn_merge_cat")
try(assert_same_ndim(list(c(NA, 3), c(NA, 5, 2)), id = "nn_merge_cat"))

Description

Checks that shape is a valid shape, i.e. an integer() with at least one dimension, NA where a dimension is unknown. See the "Shape Inference" section of PipeOpTorch for the conventions.

Usage

assert_shape(
  shape,
  null_ok = FALSE,
  coerce = TRUE,
  unknown_batch = NULL,
  len = NULL
)

Arguments

Value

The shape, coerced to an integer() if coerce is TRUE.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_ndim(), assert_not_batch_dim(), assert_positive_extent(), assert_same_batch_size(), assert_same_ndim(), assert_shapes()

Examples

assert_shape(c(NA, 3, 32, 32))
try(assert_shape("not a shape"))

Description

Checks that shapes is a non-empty list() of valid shapes, see assert_shape().

Usage

assert_shapes(
  shapes,
  coerce = TRUE,
  named = FALSE,
  null_ok = FALSE,
  unknown_batch = NULL
)

Arguments

Value

The shapes, coerced to integer() if coerce is TRUE.

See Also

Other Shape Assertions: assert_dim_in_range(), assert_known_dims(), assert_ndim(), assert_not_batch_dim(), assert_positive_extent(), assert_same_batch_size(), assert_same_ndim(), assert_shape()

Examples

assert_shapes(list(c(NA, 3), c(NA, 5)))

Description

Resolves the device parameter of a learner. "auto" becomes "cuda" when a CUDA device is available and "cpu" otherwise; any other value is returned unchanged, except that an explicit "cuda" (or "cuda:<index>") without an available CUDA device with that index is an error rather than a failure deep inside libtorch later on.

Usage

auto_device(device = NULL)

Arguments

Description

Converts a data frame of categorical data into a long tensor by converting the data to integers. No input checks are performed.

All columns are encoded with 1-based codes, i.e. the values of a feature with cardinality k are ⁠1, ..., k⁠.

Usage

batchgetter_categ(data, ...)

Arguments

Description

Converts a data frame of numeric data into a float tensor by calling as.matrix(). No input checks are performed

Usage

batchgetter_num(data, ...)

Arguments

Description

Creates an R6ClassGenerator inheriting from CallbackSet. Additionally performs checks such as that the stages are not accidentally misspelled. To create a TorchCallback use torch_callback().

In order for the resulting class to be cloneable, the private method ⁠$deep_clone()⁠ must be provided.

Usage

callback_set(
  classname,
  on_begin = NULL,
  on_end = NULL,
  on_exit = NULL,
  on_epoch_begin = NULL,
  on_before_valid = NULL,
  on_epoch_end = NULL,
  on_batch_begin = NULL,
  on_batch_end = NULL,
  on_after_backward = NULL,
  on_batch_valid_begin = NULL,
  on_batch_valid_end = NULL,
  on_valid_end = NULL,
  state_dict = NULL,
  load_state_dict = NULL,
  initialize = NULL,
  weight = NULL,
  public = NULL,
  private = NULL,
  active = NULL,
  parent_env = parent.frame(),
  inherit = CallbackSet,
  lock_objects = FALSE
)

Arguments

Value

CallbackSet

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.tb, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Description

The cross_entropy loss function selects the multi-class (nn_cross_entropy_loss) or binary (nn_bce_with_logits_loss) cross entropy loss based on the number of classes. Because of this, there is a slight reparameterization of the loss arguments, see Parameters.

Parameters

• class_weight:: torch_tensor
  The class weights. For multi-class problems, this must be a torch_tensor of length num_classes (and is passed as argument weight to nn_cross_entropy_loss). For binary problems, this must be a scalar (and is passed as argument pos_weight to nn_bce_with_logits_loss).

• ignore_index:: integer(1)
  Index of the class which to ignore and which does not contribute to the gradient. This is only available for multi-class loss.

• reduction :: character(1)
  The reduction to apply. Is either "mean" or "sum" and passed as argument reduction to either loss function. The default is "mean".

Examples

loss = t_loss("cross_entropy")
# multi-class
multi_ce = loss$generate(tsk("iris"))
multi_ce

# binary
binary_ce = loss$generate(tsk("sonar"))
binary_ce

Description

A data descriptor is a rather internal data structure used in the lazy_tensor data type. In essence it is an annotated torch::dataset and a preprocessing graph (consisting mosty of PipeOpModule operators). The additional meta data (e.g. pointer, shapes) makes it possible to preprocess lazy_tensors in an mlr3pipelines::Graph just like any (non-lazy) data types. The preprocessing is applied when materialize() is called on the lazy_tensor.

To create a data descriptor, you can also use the as_data_descriptor() function.

Details

While it would be more natural to define this as an S3 class, we opted for an R6 class to avoid the usual trouble of serializing S3 objects. If each row contained a DataDescriptor as an S3 class, this would copy the object when serializing.

Public fields

Methods

Public methods

• DataDescriptor$new()

• DataDescriptor$print()

• DataDescriptor$clone()

DataDescriptor$new()

Creates a new instance of this R6 class.

Usage

DataDescriptor$new(
  dataset,
  dataset_shapes = NULL,
  graph = NULL,
  input_map = NULL,
  pointer = NULL,
  pointer_shape = NULL,
  pointer_shape_predict = NULL,
  clone_graph = TRUE
)

Arguments

DataDescriptor$print()

Prints the object

Usage

DataDescriptor$print(...)

Arguments

DataDescriptor$clone()

The objects of this class are cloneable with this method.

Usage

DataDescriptor$clone(deep = FALSE)

Arguments

See Also

ModelDescriptor, lazy_tensor

Examples

# Create a dataset
ds = dataset(
  initialize = function() self$x = torch_randn(10, 3, 3),
  .getitem = function(i) list(x = self$x[i, ]),
  .length = function() nrow(self$x)
)()
dd = DataDescriptor$new(ds, list(x = c(NA, 3, 3)))
dd
# is the same as using the converter:
as_data_descriptor(ds, list(x = c(NA, 3, 3)))

Description

Converts the raw output of a network into a list() that can be passed to mlr3::as_prediction_data(), which is what the private .encode_prediction() method of a LearnerTorch has to return.

This is the default implementation that is used by LearnerTorch and LearnerTorchModel, i.e. by all learners that don't overwrite .encode_prediction(). When adding support for a custom task type, implement a method for the corresponding Task class, which makes the generic torch learners work for that task type.

For the network output that is expected for the built-in task types, see section Network Head and Target Encoding of LearnerTorch.

Usage

encode_prediction(task, network_output, predict_type, ...)

Arguments

Value

named list()

Description

Returns the function that builds a whole batch of a task, i.e. both the features x and the target y. This is how task_dataset loads its batches.

The returned function takes the arguments

• data, a data.table with the feature and target columns of the batch, and

• cache, a rather internal hashtab that can be used as a cache when loading multiple lazy_tensor columns.

It returns a list() with elements x (a named list() of torch_tensors) and y (a torch_tensor or NULL).

The default method applies the ingress tokens to obtain x and the target batchgetter to obtain y.

Usage

get_batch_constructor(
  task,
  feature_ingress_tokens,
  target_batchgetter = NULL,
  ...
)

Arguments

Value

⁠function(data, cache) -> list(x = list<torch_tensor>, y = torch_tensor | NULL)⁠

Examples

task = tsk("iris")
token = TorchIngressToken(task$feature_names, batchgetter_num, c(NA, 4))
# the token's features are a `Selector`; `task_dataset()` resolves them for you
token$features = token$features(task)
batch_constructor = get_batch_constructor(
  task,
  feature_ingress_tokens = list(input = token),
  target_batchgetter = get_target_batchgetter(task)
)
batch = batch_constructor(data = task$data(rows = 1:2))
batch$x$input
batch$y

Description

A LearnerTorch uses the batch_size parameter for both training and prediction, unless batch_size_predict is set, which then takes precedence during prediction. This helper resolves the batch size for one phase and is useful when overwriting the private .dataloader() method of a LearnerTorch.

Usage

get_batch_size(param_vals, phase)

Arguments

Value

(integer(1) or NULL)
The batch size for the given phase or NULL if none is set.

Examples

get_batch_size(list(batch_size = 16), "train")
get_batch_size(list(batch_size = 16, batch_size_predict = 32), "predict")
get_batch_size(list(batch_size_predict = 32), "train")

Description

Returns the function that converts the target column(s) of a task into the target tensor y of a batch, i.e. the tensor that the loss is applied to. The returned function takes an argument data, a data.table containing only the target column(s), and returns a torch_tensor. It is NULL for a task with no target at all, whose batches have no y element and whose loss is called as loss(y_hat).

For the target encodings of the built-in task types, see section Network Head and Target Encoding of LearnerTorch.

When adding support for a custom task type, implement a method for the corresponding Task class.

Usage

get_target_batchgetter(task, ...)

Arguments

Value

⁠function(data)⁠, ⁠function(data, x)⁠, or NULL for a task with no target

Examples

batchgetter = get_target_batchgetter(tsk("iris"))
batchgetter(data.table::data.table(Species = factor(c("setosa", "virginica"))))

Description

The GraphLearner that as_learner_torch() returns. On top of a GraphLearner it has the ⁠$network⁠, ⁠$loss⁠, ⁠$optimizer⁠ and ⁠$callbacks⁠ fields and the ⁠$dataset()⁠ method of a LearnerTorch. If the graph contains a PipeOpTorchModel, the loss, optimizer and callbacks are those of its configuring operators, otherwise those of its base LearnerTorch. It is not in the mlr_learners dictionary, because it cannot be constructed without a graph.

Super classes

mlr3::Learner -> mlr3pipelines::GraphLearner -> GraphLearnerTorch

Active bindings

Methods

Public methods

• GraphLearnerTorch$dataset()

• GraphLearnerTorch$clone()

GraphLearnerTorch$dataset()

Create the dataset for a task, i.e. the tensors that are fed to the network.

Usage

GraphLearnerTorch$dataset(
  task,
  stage = if (is.null(self$model)) "train" else "predict"
)

Arguments

Returns

dataset

GraphLearnerTorch$clone()

The objects of this class are cloneable with this method.

Usage

GraphLearnerTorch$clone(deep = FALSE)

Arguments

See Also

Other Learner: as_learner_torch(), mlr_learners.ft_transformer, mlr_learners.mlp, mlr_learners.module, mlr_learners.realmlp, mlr_learners.tab_resnet, mlr_learners.tabm, mlr_learners.torch_featureless, mlr_learners_torch, mlr_learners_torch_image, mlr_learners_torch_model

Description

Infer the shapes of the output of a function based on the shapes of the input. This works by running the function on the input and observing the results. For fully known input shapes this is always correct. For partially unknown shapes, the NAs are replaced with various concrete values and the output shape is computed from them. Note that this is a heuristic that might fail, so usually one wants to provide the shape (inference) explicitly.

Usage

infer_shapes(shapes_in, param_vals, output_names, fn, rowwise, id)

Arguments

Details

The inference is done as follows:

1. All NAs are replaced with three different values, which span a wide range: none of them is 1 (which broadcasts and is squeezed away), one of them is small (to detect operators that clamp to the input size, such as slicing or cropping) and the others are large (because operators such as a convolution with a large kernel need a minimum extent).

2. Three tensors are generated for the three shapes of step 1.

3. The function is called on these three tensors and the shapes are calculated. A call that fails is dropped, so that an operator is not rejected because of the smallest value; at least two of the three calls must succeed.

4. If:

   • the number of dimensions varies, an error is thrown.

   • the number of dimensions is the same, values are set to NA if the dimension is varying between the tensors and otherwise set to the unique value.

Value

(list())
A list of shapes of the output tensors.

See Also

Other Shape Inference: reshape_output_shape(), shape_to_str()

Description

Represents an entry point representing a tensor containing all categorical (factor(), ordered(), logical()) features of a task.

Usage

ingress_categ(shape = NULL)

Arguments

Value

TorchIngressToken

Description

Represents an entry point representing a tensor containing a single lazy tensor feature.

Usage

ingress_ltnsr(feature_name = NULL, shape = NULL)

Arguments

Value

TorchIngressToken

Description

Represents an entry point representing a tensor containing all numeric (integer() and double()) features of a task.

Usage

ingress_num(shape = NULL)

Arguments

Value

TorchIngressToken

Description

Checks whether an object is a lazy tensor.

Usage

is_lazy_tensor(x)

Arguments

Description

Shape of a lazy tensor. Might be NULL if the shapes is not known or varying between rows. Batch dimension is always NA.

Usage

lazy_shape(x)

Arguments

Value

(integer() or NULL)

Examples

lt = as_lazy_tensor(1:10)
lazy_shape(lt)
lt = as_lazy_tensor(matrix(1:10, nrow = 2))
lazy_shape(lt)

Description

Creates a lazy_tensor vector. Because it is a vector, it can be stored in a data.table, which gives mlr3torch the ability to use arbitrary tensors in its task. It is 'lazy', because the tensors are not stored in-memory, but only loaded when calling materialize(). The vector itself only describes how to load the data. It is also possible to preprocess lazy_tensors, e.g. via po("augment_<key>"), and po("trafo_<key>").

Usage

lazy_tensor(data_descriptor = NULL, ids = NULL)

Arguments

Examples

ds = dataset("example",
  initialize = function() self$iris = iris[, -5],
  .getitem = function(i) list(x = torch_tensor(as.numeric(self$iris[i, ]))),
  .length = function() nrow(self$iris)
)()
dd = as_data_descriptor(ds, list(x = c(NA, 4L)))
lt = as_lazy_tensor(dd)

Description

This will materialize a lazy_tensor() or a data.frame() / list() containing – among other things – lazy_tensor() columns. I.e. the data described in the underlying DataDescriptors is loaded for the indices in the lazy_tensor(), is preprocessed and then put unto the specified device. Because not all elements in a lazy tensor must have the same shape, a list of tensors is returned by default. If all elements have the same shape, these tensors can also be rbinded into a single tensor (parameter rbind).

Usage

materialize(x, device = "cpu", rbind = FALSE, ...)

## S3 method for class 'list'
materialize(x, device = "cpu", rbind = FALSE, cache = "auto", ...)

Arguments

Details

Materializing a lazy tensor consists of:

1. Loading the data from the internal dataset of the DataDescriptor.

2. Processing these batches in the preprocessing Graphs.

3. Returning the result of the PipeOp pointed to by the DataDescriptor (pointer).

With multiple lazy_tensor columns we can benefit from caching because: a) Output(s) from the dataset might be input to multiple graphs. b) Different lazy tensors might be outputs from the same graph.

For this reason it is possible to provide a cache, which is a hashtab(). The key for a) is list(dataset, indices), the key for b) is list(indices, dataset, graph, input_map). The dataset and the graph go into the key as the objects themselves, so keys are compared with identical() rather than being digested into a string, and two different keys can never share an entry.

Value

(list() of torch_tensors or a torch_tensor)

Examples

lt1 = as_lazy_tensor(torch_randn(10, 3))
materialize(lt1, rbind = TRUE)
materialize(lt1, rbind = FALSE)
lt2 = as_lazy_tensor(torch_randn(10, 4))
d = data.table::data.table(lt1 = lt1, lt2 = lt2)
materialize(d, rbind = TRUE)
materialize(d, rbind = FALSE)

Description

This lazy data backend wraps a constructor that lazily creates another backend, e.g. by downloading (and caching) some data from the internet. This backend should be used, when some metadata of the backend is known in advance and should be accessible before downloading the actual data. When the backend is first constructed, it is verified that the provided metadata was correct, otherwise an informative error message is thrown. After the construction of the lazily constructed backend, calls like ⁠$data()⁠, ⁠$missings()⁠, ⁠$distinct()⁠, or ⁠$hash()⁠ are redirected to it.

Information that is available before the backend is constructed is:

• nrow - The number of rows (set as the length of the rownames).

• ncol - The number of columns (provided via the id column of col_info).

• colnames - The column names.

• rownames - The row names.

• col_info - The column information, which can be obtained via mlr3::col_info().

Beware that accessing the backend's hash also contructs the backend.

Note that while in most cases the data contains lazy_tensor columns, this is not necessary and the naming of this class has nothing to do with the lazy_tensor data type.

Important

When the constructor generates factor() variables it is important that the ordering of the levels in data corresponds to the ordering of the levels in the col_info argument.

Super class

mlr3::DataBackend -> DataBackendLazy

Active bindings

Methods

Public methods

• DataBackendLazy$new()

• DataBackendLazy$data()

• DataBackendLazy$head()

• DataBackendLazy$distinct()

• DataBackendLazy$missings()

• DataBackendLazy$print()

DataBackendLazy$new()

Creates a new instance of this R6 class.

Usage

DataBackendLazy$new(constructor, rownames, col_info, primary_key)

Arguments

DataBackendLazy$data()

Returns a slice of the data in the specified format. The rows must be addressed as vector of primary key values, columns must be referred to via column names. Queries for rows with no matching row id and queries for columns with no matching column name are silently ignored. Rows are guaranteed to be returned in the same order as rows, columns may be returned in an arbitrary order. Duplicated row ids result in duplicated rows, duplicated column names lead to an exception.

Accessing the data triggers the construction of the backend.

Usage

DataBackendLazy$data(rows, cols)

Arguments

DataBackendLazy$head()

Retrieve the first n rows. This triggers the construction of the backend.

Usage

DataBackendLazy$head(n = 6L)

Arguments

Returns

data.table::data.table() of the first n rows.

DataBackendLazy$distinct()

Returns a named list of vectors of distinct values for each column specified. If na_rm is TRUE, missing values are removed from the returned vectors of distinct values. Non-existing rows and columns are silently ignored.

This triggers the construction of the backend.

Usage

DataBackendLazy$distinct(rows, cols, na_rm = TRUE)

Arguments

Returns

Named list() of distinct values.

DataBackendLazy$missings()

Returns the number of missing values per column in the specified slice of data. Non-existing rows and columns are silently ignored.

This triggers the construction of the backend.

Usage

DataBackendLazy$missings(rows, cols)

Arguments

Returns

Total of missing values per column (named numeric()).

DataBackendLazy$print()

Printer.

Usage

DataBackendLazy$print()

Examples

# We first define a backend constructor
constructor = function(backend) {
  cat("Data is constructed!\n")
  DataBackendDataTable$new(
    data.table(x = rnorm(10), y = rnorm(10), row_id = 1:10),
    primary_key = "row_id"
  )
}

# to wrap this backend constructor in a lazy backend, we need to provide the correct metadata for it
column_info = data.table(
  id = c("x", "y", "row_id"),
  type = c("numeric", "numeric", "integer"),
  levels = list(NULL, NULL, NULL)
)
backend_lazy = DataBackendLazy$new(
  constructor = constructor,
  rownames = 1:10,
  col_info = column_info,
  primary_key = "row_id"
)

# Note that the constructor is not called for the calls below
# as they can be read from the metadata
backend_lazy$nrow
backend_lazy$rownames
backend_lazy$ncol
backend_lazy$colnames
col_info(backend_lazy)

# Only now the backend is constructed
backend_lazy$data(1, "x")
# Is the same as:
backend_lazy$backend$data(1, "x")

Description

Base class from which callbacks should inherit (see section Inheriting). A callback set is a collection of functions that are executed at different stages of the training loop. They can be used to gain more control over the training process of a neural network without having to write everything from scratch.

When used in a torch learner, the CallbackSet is wrapped in a TorchCallback. The latter's parameter set represents the arguments of the CallbackSet's ⁠$initialize()⁠ method.

Inheriting

For each available stage (see section Stages) a public method ⁠$on_<stage>()⁠ can be defined. The evaluation context (a ContextTorch) can be accessed via self$ctx, which contains the current state of the training loop. This context is assigned at the beginning of the training loop and removed afterwards. Different stages of a callback can communicate with each other by assigning values to self.

State: To be able to store information in the ⁠$model⁠ slot of a LearnerTorch, callbacks support a state API. You can overload the ⁠$state_dict()⁠ public method to define what will be stored in ⁠learner$model$callbacks$<id>⁠ after training finishes. This then also requires to implement a ⁠$load_state_dict(state_dict)⁠ method that defines how to load a previously saved callback state into a different callback. Note that the ⁠$state_dict()⁠ should not include the parameter values that were used to initialize the callback.

In order to be able to resume a callback, it needs to work with saveRDS, so it cannot contain external pointers such as torch_tensors. Convert them to R data, e.g. via as.array().

For creating custom callbacks, the function torch_callback() is recommended, which creates a CallbackSet and then wraps it in a TorchCallback. To create a CallbackSet the convenience function callback_set() can be used. These functions perform checks such as that the stages are not accidentally misspelled.

Stages

• begin :: Run before the training loop begins.

• epoch_begin :: Run at the beginning of each epoch.

• batch_begin :: Run before the forward call.

• after_backward :: Run after the backward call.

• batch_end :: Run after the optimizer step.

• before_valid :: Run before the validation loop begins.

• batch_valid_begin :: Run before the forward call in the validation loop.

• batch_valid_end :: Run after the forward call in the validation loop.

• valid_end :: Run at the end of validation.

• epoch_end :: Run at the end of each epoch.

• end :: Run after last epoch.

• exit :: Run last, using on.exit().

Ordering

Within a stage, callbacks are called in the order in which they were passed to the learner. A callback can override this via its ⁠$weight⁠ field: callbacks with a higher weight are called after those with a lower one, and callbacks with the same weight keep the order in which they were passed. The default weight is 0. This matters for callbacks that observe what the others did, which is why CallbackSetCheckpoint has weight Inf: it always runs last and therefore saves the network and optimizer as the other callbacks left them at the end of the stage.

Terminate Training

If training is to be stopped, it is possible to set the field ⁠$terminate⁠ of ContextTorch. At the end of every epoch this field is checked and if it is TRUE, training stops. This can for example be used to implement custom early stopping.

Public fields

Active bindings

Methods

Public methods

• CallbackSet$print()

• CallbackSet$state_dict()

• CallbackSet$load_state_dict()

• CallbackSet$clone()

CallbackSet$print()

Prints the object.

Usage

CallbackSet$print(...)

Arguments

CallbackSet$state_dict()

Returns information that is kept in the LearnerTorch's state after training. This information should be loadable into the callback using ⁠$load_state_dict()⁠ to be able to continue training. This returns NULL by default.

Usage

CallbackSet$state_dict()

CallbackSet$load_state_dict()

Loads the state dict into the callback to continue training. A callback that keeps no state inherits this, which has nothing to load and therefore only warns when it is handed a state anyway – a callback that implements ⁠$state_dict()⁠ but not this method, so that a resuming run cannot give its state back.

Usage

CallbackSet$load_state_dict(state_dict)

Arguments

CallbackSet$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSet$clone(deep = FALSE)

Arguments

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.tb, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Description

Saves the optimizer, weights, and callback states every freq epochs as well as the final state. This can be used to later continue a training run via the resume parameter of LearnerTorch.

Checkpoints are written at the end of an epoch. For one written after epoch ⁠<n>⁠, three files are created in path:

• ⁠network<n>.pt⁠ :: The ⁠$state_dict()⁠ of the network.

• ⁠optimizer<n>.pt⁠ :: The ⁠$state_dict()⁠ of the optimizer.

• ⁠state<n>.rds⁠ :: The epoch, the version of mlr3torch that wrote the checkpoint, the ⁠$state_dict()⁠s of the training run's other callbacks, so that a later run can continue, as well as some other information. Additionally, there is run.rds which contains some additioanl global meta information.

Details

Saving the learner itself in the callback with a trained model is impossible, as the model slot is set after the last callback step is executed.

Resuming

This callback is special because it enables resuming a training run. Its own state is the folder it writes to, which ⁠learner$model$callbacks$<id>$path⁠ reports – the only way to learn where a path function sent a run, e.g. one fit of a resample(). That state is not part of a checkpoint and is not restored: a resuming run writes where its own path says.

Ordering

This callback has weight Inf and therefore runs last, so it captures all the changes other callbacks made.

Super class

CallbackSet -> CallbackSetCheckpoint

Public fields

Methods

Public methods

• CallbackSetCheckpoint$new()

• CallbackSetCheckpoint$state_dict()

• CallbackSetCheckpoint$on_begin()

• CallbackSetCheckpoint$on_epoch_end()

• CallbackSetCheckpoint$on_end()

• CallbackSetCheckpoint$clone()

CallbackSetCheckpoint$new()

Creates a new instance of this R6 class.

Usage

CallbackSetCheckpoint$new(path, freq)

Arguments

CallbackSetCheckpoint$state_dict()

Returns the folder this callback writes to so it can be accessed from the learner when the path was a function.

Usage

CallbackSetCheckpoint$state_dict()

CallbackSetCheckpoint$on_begin()

Checks whether the checkpoint path is valid.

Usage

CallbackSetCheckpoint$on_begin()

CallbackSetCheckpoint$on_epoch_end()

Saves the network and optimizer state dict. Does nothing if freq is not met.

Usage

CallbackSetCheckpoint$on_epoch_end()

CallbackSetCheckpoint$on_end()

Saves the final network and optimizer, unless the last epoch was already saved.

Usage

CallbackSetCheckpoint$on_end()

CallbackSetCheckpoint$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetCheckpoint$clone(deep = FALSE)

Arguments

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.progress, mlr_callback_set.tb, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Examples

cb = t_clbk("checkpoint", freq = 1)
task = tsk("iris")

pth = tempfile()
learner = lrn("classif.mlp", epochs = 3, batch_size = 1, callbacks = cb)
learner$param_set$set_values(cb.checkpoint.path = pth)

learner$train(task)

list.files(pth)

# continue training for 3 more epochs, starting from the last checkpoint
learner_resumed = lrn("classif.mlp", epochs = 6, batch_size = 1, resume = pth)
learner_resumed$train(task)
learner_resumed$model$epochs

Description

Saves the training and validation history during training. The history is saved as a data.table where the validation measures are prefixed with "valid." and the training measures are prefixed with "train.".

Resuming

The epochs of a resumed run are appended to the history of the run it continues. A measure that only one of the two runs recorded is NA for the epochs of the other.

Super class

CallbackSet -> CallbackSetHistory

Methods

Public methods

• CallbackSetHistory$on_begin()

• CallbackSetHistory$state_dict()

• CallbackSetHistory$load_state_dict()

• CallbackSetHistory$on_before_valid()

• CallbackSetHistory$on_epoch_end()

• CallbackSetHistory$clone()

CallbackSetHistory$on_begin()

Initializes lists where the train and validation metrics are stored.

Usage

CallbackSetHistory$on_begin()

CallbackSetHistory$state_dict()

Converts the lists to data.tables.

Usage

CallbackSetHistory$state_dict()

CallbackSetHistory$load_state_dict()

Remembers the history contained in the state dict, so that the epochs of the current run are appended to it by ⁠$state_dict()⁠.

Usage

CallbackSetHistory$load_state_dict(state_dict)

Arguments

CallbackSetHistory$on_before_valid()

Add the latest training scores to the history.

Usage

CallbackSetHistory$on_before_valid()

CallbackSetHistory$on_epoch_end()

Add the latest validation scores to the history.

Usage

CallbackSetHistory$on_epoch_end()

CallbackSetHistory$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetHistory$clone(deep = FALSE)

Arguments

Examples

cb = t_clbk("history")
task = tsk("iris")

learner = lrn("classif.mlp", epochs = 3, batch_size = 1,
  callbacks = t_clbk("history"), validate = 0.3)
learner$param_set$set_values(
  measures_train = msrs(c("classif.acc", "classif.ce")),
  measures_valid = msr("classif.ce")
)
learner$train(task)

print(learner$model$callbacks$history)

Description

Changes the learning rate based on the schedule specified by a torch::lr_scheduler.

As of this writing, the following are available:

• torch::lr_cosine_annealing()

• torch::lr_lambda()

• torch::lr_multiplicative()

• torch::lr_one_cycle() (where the default values for epochs and steps_per_epoch are the number of training epochs and the number of batches per epoch)

• torch::lr_reduce_on_plateau()

• torch::lr_step()

• Custom schedulers defined with torch::lr_scheduler().

Resuming

The state of the wrapped torch scheduler is stored and restored, so a resumed run continues the schedule instead of starting it over. Creating a scheduler resets the optimizer's learning rate to the one the schedule started at, so the rate the restored schedule had reached is put back afterwards.

That state contains the scheduler's configuration as well as its progress, and restoring it overwrites what the resuming run was configured with. Resuming with different scheduler arguments, or a different opt.lr, which the schedule's base rates are derived from, therefore silently continues the schedule of the checkpointed run.

Super class

CallbackSet -> CallbackSetLRScheduler

Public fields

Methods

Public methods

• CallbackSetLRScheduler$new()

• CallbackSetLRScheduler$on_begin()

• CallbackSetLRScheduler$state_dict()

• CallbackSetLRScheduler$load_state_dict()

• CallbackSetLRScheduler$clone()

CallbackSetLRScheduler$new()

Creates a new instance of this R6 class.

Usage

CallbackSetLRScheduler$new(.scheduler, step_on_epoch, ...)

Arguments

CallbackSetLRScheduler$on_begin()

Creates the scheduler using the optimizer from the context

Usage

CallbackSetLRScheduler$on_begin()

CallbackSetLRScheduler$state_dict()

Returns the state of the wrapped torch scheduler, so that a later run can continue the schedule instead of starting it over. Returns NULL if the scheduler was not created yet, i.e. before the training loop began.

Usage

CallbackSetLRScheduler$state_dict()

CallbackSetLRScheduler$load_state_dict()

Loads the state of the wrapped torch scheduler.

Usage

CallbackSetLRScheduler$load_state_dict(state_dict)

Arguments

CallbackSetLRScheduler$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetLRScheduler$clone(deep = FALSE)

Arguments

Description

Changes the learning rate based on the 1cycle learning rate policy.

Wraps torch::lr_one_cycle(), where the default values for epochs and steps_per_epoch are the number of training epochs and the number of batches per epoch.

Resuming

As for CallbackSetLRScheduler, with one additional restriction: the 1cycle policy is defined over the total number of steps of the run, so a resumed run must be configured for the same number of steps as the one that wrote the checkpoint, i.e. the same epochs and the same number of batches per epoch. A run that is not errors before its first epoch rather than somewhere in the middle.

Super classes

CallbackSet -> CallbackSetLRScheduler -> CallbackSetLRSchedulerOneCycle

Methods

Public methods

• CallbackSetLRSchedulerOneCycle$new()

• CallbackSetLRSchedulerOneCycle$on_begin()

• CallbackSetLRSchedulerOneCycle$clone()

CallbackSetLRSchedulerOneCycle$new()

Creates a new instance of this R6 class.

Usage

CallbackSetLRSchedulerOneCycle$new(...)

Arguments

CallbackSetLRSchedulerOneCycle$on_begin()

Creates the scheduler using the optimizer from the context

Usage

CallbackSetLRSchedulerOneCycle$on_begin()

CallbackSetLRSchedulerOneCycle$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetLRSchedulerOneCycle$clone(deep = FALSE)

Arguments

Description

Reduces the learning rate when the first validation measure, i.e. the first entry of the learner's measures_valid, stops improving for patience evaluation steps. Wraps torch::lr_reduce_on_plateau().

Note that patience counts evaluation steps, not epochs: when the learner's eval_freq is greater than 1, the scheduler only steps in the epochs in which the validation measures are evaluated, so patience evaluation steps correspond to patience * eval_freq epochs.

Unless mode is set, it is derived from the measure: "min" if the measure is minimized and "max" if it is maximized. Training fails when mode contradicts the measure. When the learner has no validation measure, e.g. in the final fit of an AutoTuner that tunes the epochs internally, a warning is given and the learning rate is not reduced.

Resuming

As for CallbackSetLRScheduler. For this schedule the restored state includes the best score seen so far and how long it has been stagnating, so patience keeps counting across runs instead of starting over.

Super classes

CallbackSet -> CallbackSetLRScheduler -> CallbackSetLRSchedulerReduceOnPlateau

Methods

Public methods

• CallbackSetLRSchedulerReduceOnPlateau$new()

• CallbackSetLRSchedulerReduceOnPlateau$on_begin()

• CallbackSetLRSchedulerReduceOnPlateau$clone()

CallbackSetLRSchedulerReduceOnPlateau$new()

Creates a new instance of this R6 class.

Usage

CallbackSetLRSchedulerReduceOnPlateau$new(...)

Arguments

CallbackSetLRSchedulerReduceOnPlateau$on_begin()

Creates the scheduler using the optimizer from the context, with the mode that fits the first validation measure.

Usage

CallbackSetLRSchedulerReduceOnPlateau$on_begin()

CallbackSetLRSchedulerReduceOnPlateau$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetLRSchedulerReduceOnPlateau$clone(deep = FALSE)

Arguments

Description

Prints a progress bar and the metrics for training and validation.

Resuming

This callback can be resumed without any problems.

Super class

CallbackSet -> CallbackSetProgress

Methods

Public methods

• CallbackSetProgress$new()

• CallbackSetProgress$on_begin()

• CallbackSetProgress$on_epoch_begin()

• CallbackSetProgress$on_batch_end()

• CallbackSetProgress$on_before_valid()

• CallbackSetProgress$on_batch_valid_end()

• CallbackSetProgress$on_epoch_end()

• CallbackSetProgress$on_end()

• CallbackSetProgress$state_dict()

• CallbackSetProgress$load_state_dict()

• CallbackSetProgress$clone()

CallbackSetProgress$new()

Creates a new instance of this R6 class.

Usage

CallbackSetProgress$new(digits = 2)

Arguments

CallbackSetProgress$on_begin()

Starts this run's timer.

Usage

CallbackSetProgress$on_begin()

CallbackSetProgress$on_epoch_begin()

Initializes the progress bar for training.

Usage

CallbackSetProgress$on_epoch_begin()

CallbackSetProgress$on_batch_end()

Increments the training progress bar.

Usage

CallbackSetProgress$on_batch_end()

CallbackSetProgress$on_before_valid()

Creates the progress bar for validation.

Usage

CallbackSetProgress$on_before_valid()

CallbackSetProgress$on_batch_valid_end()

Increments the validation progress bar.

Usage

CallbackSetProgress$on_batch_valid_end()

CallbackSetProgress$on_epoch_end()

Prints a summary of the training and validation process.

Usage

CallbackSetProgress$on_epoch_end()

CallbackSetProgress$on_end()

Prints the time at the end of training, and how long training took in total. A resumed run also reports how much of that total it contributed itself.

Usage

CallbackSetProgress$on_end()

CallbackSetProgress$state_dict()

Returns the seconds trained so far, so that a resumed run reports the time of all runs together rather than only its own.

Usage

CallbackSetProgress$state_dict()

CallbackSetProgress$load_state_dict()

Loads the time that the previous runs took.

Usage

CallbackSetProgress$load_state_dict(state_dict)

Arguments

CallbackSetProgress$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetProgress$clone(deep = FALSE)

Arguments

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.tb, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Examples

task = tsk("iris")

learner = lrn("classif.mlp", epochs = 5, batch_size = 1,
  callbacks = t_clbk("progress"), validate = 0.3)
learner$param_set$set_values(
  measures_train = msrs(c("classif.acc", "classif.ce")),
  measures_valid = msr("classif.ce")
)

learner$train(task)

Description

Logs training loss, training measures, and validation measures as events. To view them, use TensorBoard with tensorflow::tensorboard() (requires tensorflow) or the CLI.

Details

Logs events at most every epoch.

Resuming

This callback keeps no state of its own so it can trivially be resumed.

Super class

CallbackSet -> CallbackSetTB

Methods

Public methods

• CallbackSetTB$new()

• CallbackSetTB$on_epoch_end()

• CallbackSetTB$clone()

CallbackSetTB$new()

Creates a new instance of this R6 class.

Usage

CallbackSetTB$new(path, log_train_loss)

Arguments

CallbackSetTB$on_epoch_end()

Logs the training loss, training measures, and validation measures as TensorBoard events.

Usage

CallbackSetTB$on_epoch_end()

CallbackSetTB$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetTB$clone(deep = FALSE)

Arguments

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.unfreeze, mlr_context_torch, t_clbk(), torch_callback()

Description

Unfreeze some weights (parameters of the network) after some number of steps or epochs.

Resuming

Which weights are trainable is stored and restored, so a resumed run does not freeze again what the run it continues had already unfrozen: starting_weights is applied first, and the restored weights are unfrozen on top of it.

Super class

CallbackSet -> CallbackSetUnfreeze

Methods

Public methods

• CallbackSetUnfreeze$new()

• CallbackSetUnfreeze$on_begin()

• CallbackSetUnfreeze$state_dict()

• CallbackSetUnfreeze$load_state_dict()

• CallbackSetUnfreeze$on_epoch_begin()

• CallbackSetUnfreeze$on_batch_begin()

• CallbackSetUnfreeze$clone()

CallbackSetUnfreeze$new()

Creates a new instance of this R6 class.

Usage

CallbackSetUnfreeze$new(starting_weights, unfreeze)

Arguments

CallbackSetUnfreeze$on_begin()

Sets the starting weights

Usage

CallbackSetUnfreeze$on_begin()

CallbackSetUnfreeze$state_dict()

Returns the names of the weights that are currently trainable, so that a later run does not freeze weights again that were already unfrozen.

Usage

CallbackSetUnfreeze$state_dict()

CallbackSetUnfreeze$load_state_dict()

Marks the weights of the state dict as trainable.

Usage

CallbackSetUnfreeze$load_state_dict(state_dict)

Arguments

CallbackSetUnfreeze$on_epoch_begin()

Unfreezes weights if the training is at the correct epoch

Usage

CallbackSetUnfreeze$on_epoch_begin()

CallbackSetUnfreeze$on_batch_begin()

Unfreezes weights if the training is at the correct batch

Usage

CallbackSetUnfreeze$on_batch_begin()

CallbackSetUnfreeze$clone()

The objects of this class are cloneable with this method.

Usage

CallbackSetUnfreeze$clone(deep = FALSE)

Arguments

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.tb, mlr_context_torch, t_clbk(), torch_callback()

Examples

task = tsk("iris")
cb = t_clbk("unfreeze")
mlp = lrn("classif.mlp", callbacks = cb,
 cb.unfreeze.starting_weights = select_invert(
   select_name(c("0.weight", "3.weight", "6.weight", "6.bias"))
 ),
 cb.unfreeze.unfreeze = data.table(
   epoch = c(2, 5),
   weights = list(select_name("0.weight"), select_name(c("3.weight", "6.weight")))
 ),
 epochs = 6, batch_size = 150, neurons = c(1, 1, 1)
)

mlp$train(task)

Description

Context for training a torch learner. This is the - mostly read-only - information callbacks have access to through the argument ctx. For more information on callbacks, see CallbackSet.

Public fields

Active bindings

Methods

Public methods

• ContextTorch$new()

• ContextTorch$clone()

ContextTorch$new()

Creates a new instance of this R6 class.

Usage

ContextTorch$new(
  learner,
  task_train,
  task_valid = NULL,
  loader_train,
  loader_valid = NULL,
  measures_train = NULL,
  measures_valid = NULL,
  network,
  optimizer,
  loss_fn,
  total_epochs,
  prediction_encoder,
  eval_freq = 1L,
  device
)

Arguments

ContextTorch$clone()

The objects of this class are cloneable with this method.

Usage

ContextTorch$clone(deep = FALSE)

Arguments

See Also

Other Callback: TorchCallback, as_torch_callback(), as_torch_callbacks(), callback_set(), mlr3torch_callbacks, mlr_callback_set, mlr_callback_set.checkpoint, mlr_callback_set.progress, mlr_callback_set.tb, mlr_callback_set.unfreeze, t_clbk(), torch_callback()

Description

This base class provides the basic functionality for training and prediction of a neural network. All torch learners should inherit from this class.

Validation

To specify the validation data, you can set the ⁠$validate⁠ field of the Learner, which can be set to:

• NULL: no validation

• ratio: only proportion 1 - ratio of the task is used for training and ratio is used for validation.

• "test" means that the "test" task of a resampling is used and is not possible when calling ⁠$train()⁠ manually.

• "predefined": This will use the predefined ⁠$internal_valid_task⁠ of a mlr3::Task.

This validation data can also be used for early stopping, see the description of the Learner's parameters.

Saving a Learner

In order to save a LearnerTorch for later usage, it is necessary to call the ⁠$marshal()⁠ method on the Learner before writing it to disk, as the object will otherwise not be saved correctly. After loading a marshaled LearnerTorch into R again, you then need to call ⁠$unmarshal()⁠ to transform it into a useable state.

Early Stopping and Internal Tuning

In order to prevent overfitting, the LearnerTorch class supports early stopping via the patience and min_delta parameters, see the Learner's parameters. When tuning a LearnerTorch it is also possible to combine the explicit tuning via mlr3tuning and the LearnerTorch's internal tuning of the epochs via early stopping. To do so, you just need to include ⁠epochs = to_tune(upper = <upper>, internal = TRUE)⁠ in the search space, where ⁠<upper>⁠ is the maximally allowed number of epochs, and configure the early stopping.

Checkpointing and Resuming

It is possible to save intermediate results from a run via the t_clbk("checkpoint") callback. It is then possible to train for more epochs by setting the resume parameter of the LearnerTorch. This parameter can either be a path or TRUE which will use the path of the provided checkpoint callback. Only the number of epochs should be changed between resumed runs, other parameter changes are considered undefined behavior. Also, make sure to use the same train-validation split. When the latest written checkpoint was for n1 epochs, the learner needs to be configured to be trained for n >= n1 epochs and the training will run for n2 = n - n1 epochs. With n = n1 the checkpointed run is already finished, so nothing is trained and the model of the checkpoint is returned – which is what lets a script that restarts itself be run again after it succeeded, and what recovers the model of a run that was killed after its last epoch. Configuring n < n1 is an error. Resuming will load the network weights, optimizer states and callback states. For some callbacks, training for n1 and then n2 epochs via resuming is not the same as training for n epochs from the start. This is for example the case for learning rate schedulers that depend on the total number of epochs to train for. The callbacks document their behavior under a corresponding Resuming section in their documentation. Furthermore, rng states are not restored, which constitutes another difference between a full and a resumed training run.

Network Head and Target Encoding

Torch learners are expected to have the following output:

• binary classification: ⁠(batch_size, 1)⁠, representing the logits for the positive class.

• multiclass classification: ⁠(batch_size, n_classes)⁠, representing the logits for all classes.

• regression: ⁠(batch_size, 1)⁠ representing the response prediction.

A network may return more than one tensor, in which case it returns a list() of them. There are two typical reasons for this:

• Networks with auxiliary classifiers such as Inception v3 return additional predictions that only exist to contribute to the loss during training. Here, every element has the shape given above and the first one is the prediction of interest.

• A prediction that consists of several quantities – e.g. a mean and a standard deviation – is expressed by returning one tensor per quantity, which the prediction encoding combines.

In both cases the complete output is what the rest of the learner works with:

• The loss is applied to it. Because the configured loss expects a single tensor, a learner whose network returns a list has to wrap it in .setup_training(), see the list of methods below. ContextTorch makes the output available as ctx$y_hats.

• The prediction is encoded from it, both when predicting and when calculating the training and validation scores, so .encode_prediction() always receives the complete network output. Such a learner needs an encode_prediction() method for its task type, or has to overload the private .encode_prediction() method, because the encodings of the built-in task types expect a single tensor.

Note that the complete output is whatever the network returned in the mode it was called in, so a network whose extra tensors exist only during training – as auxiliary classifiers do – returns a different structure during training than during prediction, and .encode_prediction() has to handle both. classif.inception_v3 does this by encoding only the prediction of the main classifier.

Furthermore, the target encoding is expected to be as follows:

• regression: The numeric target variable of a TaskRegr is encoded as a torch_float with shape c(batch_size, 1).

• binary classification: The factor target variable of a TaskClassif is encoded as a torch_float with shape ⁠(batch_size, 1)⁠ where the positive class (Task$positive, which is also ensured to be the first factor level) is 1 and the negative class is 0.

• multi-class classification: The factor target variable of a TaskClassif is a label-encoded torch_long with shape (batch_size) where the label-encoding goes from 1 to n_classes.

Predicting Tensors

The predict type "lazy_tensor", available for the task type "torch", hands back what the network produced – a lazy_tensor with one element per observation – instead of asking the task's default_encoder to turn it into a response. It is how to get at the logits of a classifier or the reconstruction of an autoencoder, and a task predicted this way needs no encoder at all. Unlike "prob" and "se" it is not opt-in: every learner for this task type has it among its ⁠$predict_types⁠, because handing the output back does not depend on how the learner encodes a prediction. Set learner$predict_type = "lazy_tensor" to use it. A network with more than one head hands back one lazy_tensor per head, held in a data.table with one column per head so that the prediction is still one row per observation; as.data.table() spreads it into ⁠lazy_tensor.<head>⁠ columns.

Two things to know before using it:

• Such a prediction does not survive saveRDS(). It holds torch tensors, which are external pointers: saving succeeds, and the object then fails with external pointer is not valid the next time the tensors are touched, in this session or in another. This applies to a ResampleResult holding one as well – its row ids and scores survive, its tensors do not.

• Nothing about it is lazy. A lazy_tensor built from a tensor holds that tensor, so a prediction of this type is the network's output in memory, and resample() holds every fold's – combining the folds concatenates them, since lazy tensors from different networks share no data descriptor and cannot be concatenated lazily.

Important Runtime Considerations

There are a few hyperparameters settings that can have a considerable impact on the runtime of the learner. These include:

• device: Use a GPU if possible.

• num_threads: Set this to the number of CPU cores available if training on CPU. When resampling, benchmarking or tuning in parallel, each worker uses num_threads threads, so divide the available cores among the workers instead to avoid oversubscribing the machine.

• tensor_dataset: Set this to TRUE (or "device" if on a GPU) if the dataset fits into memory. This loads and stacks every batch once up front, so it must not be used with a lazy_tensor that applies random data augmentation – the augmentation would then be drawn only once.

• batch_size: Especially for very small models, choose a larger batch size.

• batch_size_predict: Prediction has no backward pass and so fits larger batches than training.

• jit_trace: Set this to TRUE to remove the per-batch R interpreter overhead, but only for a network whose control flow and shapes do not depend on the data. See the parameter's own entry.

• num_workers: Load batches in parallel worker processes.

• pin_memory: With a GPU, this speeds up the host-to-device copy of each batch.

Also, see the Early Stopping and Internal Tuning section for how to terminate training early.

Multiple GPUs

A single model is trained on one device. Set device to "cuda" for the default GPU, or to "cuda:<index>", e.g. "cuda:1", for a specific one.

To spread resampling, benchmarking or tuning over several GPUs, start one mirai daemon per GPU and restrict each daemon to its own GPU with the environment variable CUDA_VISIBLE_DEVICES. Inside a daemon, its GPU is then the only one, so device = "cuda" is correct for every resampling iteration. A device index such as "cuda:1" does not help here, because all iterations share the same parameter values. mlr3 uses the daemons of the compute profile "mlr3_parallelization", and a daemon inherits the environment variables of the R session that launches it:

library(mirai)
gpus = c("0", "1")
daemons(url = local_url(), .compute = "mlr3_parallelization")
for (id in gpus) {
  Sys.setenv(CUDA_VISIBLE_DEVICES = id)
  launch_local(1, .compute = "mlr3_parallelization")
}
Sys.unsetenv("CUDA_VISIBLE_DEVICES")

learner = lrn("classif.mlp", device = "cuda", epochs = 50, batch_size = 64)
rr = resample(tsk("spam"), learner, rsmp("cv", folds = 10))
daemons(0, .compute = "mlr3_parallelization")

Each resampling iteration goes to the next free daemon, so all GPUs stay busy until fewer iterations than GPUs remain.

Things to avoid:

• daemons(n) alone: every daemon sees all GPUs, and "cuda" is the first GPU in each of them, so all iterations share that one GPU.

• Forking a process that has already initialized CUDA, e.g. with future::plan("multicore").

• A high num_threads: data loading and preprocessing still run on the CPU in all daemons at once, so divide the CPU cores among them.

Several daemons per GPU only pay off when one model leaves the GPU underused, e.g. because it is small and training is bound by the per-batch overhead in R. Then all models must also fit into that GPU's memory together.

Model

The Model is a list of class "learner_torch_model" with the following elements:

• network :: The trained network.

• optimizer :: The ⁠$state_dict()⁠ optimizer used to train the network.

• loss_fn :: The ⁠$state_dict()⁠ of the loss used to train the network.

• callbacks :: The callbacks used to train the network.

• seed :: The seed that was / is used for training and prediction.

• epochs :: How many epochs the model was trained for (early stopping).

• task_col_info :: A data.table() containing information about the train-task.

Parameters

General:

The parameters of the optimizer, loss and callbacks, prefixed with "opt.", "loss." and "cb.<callback id>." respectively, as well as:

• epochs :: integer(1)
  The number of epochs.

• device :: character(1)
  The device. One of "auto", "cpu", or "cuda" or other values defined in mlr_reflections$torch$devices. A specific device can be selected by appending its index, e.g. "cuda:1" for the second GPU. The value is initialized to "auto", which will select "cuda" if possible, then try "mps" and otherwise fall back to "cpu".

• num_threads :: integer(1)
  The number of threads for intraop parallelization (if device is "cpu"). This value is initialized to 1. When resampling, benchmarking or tuning in parallel, each worker uses this many threads, so divide the available cores among the workers instead of setting this to the number of cores.

• num_interop_threads :: integer(1)
  The number of threads for interop parallelization (if device is "cpu"). Note that this can only be set once per session, so setting this for one learner also changes the behavior of other learners, and a later learner asking for a different value errors. NULL (default) uses whatever is set. In order to use different values for this parameter, use encapsulation to train the learners in separate R sessions.

• seed :: integer(1) or "random" or NULL
  The torch seed that is used during training and prediction. This value is initialized to "random", which means that a random seed will be sampled at the beginning of the training phase. This seed (either set or randomly sampled) is available via ⁠$model$seed⁠ after training and used during prediction. Note that by setting the seed during the training phase this will mean that by default (i.e. when seed is "random"), clones of the learner will use a different seed. If set to NULL, no seeding will be done. This parameter only seeds torch's random number generator, it does not seed R's. Anything that is drawn from R's RNG is therefore unaffected by it, so to make those parts reproducible you need to seed R's RNG as well, e.g. via set.seed().

• tensor_dataset :: logical(1) | "device"
  Whether to load all batches at once at the beginning of training and stack them. This is initialized to FALSE. If set to "device", the device of the tensors will be set to the value of device, which can avoid unnecessary moving of tensors between devices. When your dataset fits into memory this will make the loading of batches faster. Note that this should not be set for datasets that contain lazy_tensors with random data augmentation, as this augmentation will only be applied once at the beginning of training.

• cache_task_data :: logical(1)
  Whether to retrieve the data from the task once and to take the batches from it, instead of retrieving every batch from the task, which is slow. This is initialized to TRUE. Set it to FALSE if a copy of the task data does not fit into memory (lazy tensor columns only contain indices and are small).

• jit_trace :: logical(1)
  Whether to trace the network with torch::jit_trace() once at the start of training and then train the traced module instead of the original one. Not all learners support this. A traced network takes its inputs by position and ignores their names (mlverse/torch#1495). The learner passes the inputs in the right order, but when calling the traced ⁠$network⁠ of a trained learner with several inputs directly, they must be passed by position in the order given by attr(learner$network, "input_order").

Evaluation:

• measures_train :: Measure or list() of Measures
  Measures to be evaluated during training.

• measures_valid :: Measure or list() of Measures
  Measures to be evaluated during validation.

• eval_freq :: integer(1)
  How often the train / validation predictions are evaluated using measures_train / measures_valid. This is initialized to 1. Note that the final model is always evaluated.

Resuming:

• resume :: character(1) or TRUE
  Continues training from a checkpoint written by t_clbk("checkpoint"), either the folder it wrote to or TRUE, which takes that folder from the checkpoint callback of this learner. Note that epochs is the total number of epochs, i.e. it includes the epochs the checkpoint was already trained for: resuming a checkpoint from epoch 5 with epochs = 8 trains 3 more epochs.

Early Stopping:

• patience :: integer(1)
  This activates early stopping using the validation scores. If the performance of a model does not improve for patience evaluation steps, training is ended. Note that this counts evaluation steps, not epochs: when eval_freq is greater than 1, patience evaluation steps correspond to patience * eval_freq epochs. Note that the final model is stored in the learner, not the best model, unless restore_best_weights is set to TRUE. This is initialized to 0, which means no early stopping. The first entry from measures_valid is used as the metric. A missing (NA) score counts as no improvement, and every score improves on a missing one. If all scores are missing, the first evaluated epoch is reported as the best one. This also requires to specify the ⁠$validate⁠ field of the Learner, as well as measures_valid.

• min_delta :: double(1)
  The minimum improvement threshold for early stopping. Is initialized to 0.

• restore_best_weights :: logical(1)
  Whether to restore the weights of the best epoch when training ends, instead of keeping those of the last epoch that was trained. Like min_delta, this only has an effect when early stopping is active. Is initialized to FALSE, i.e. the network of the last epoch is stored. Setting this to TRUE makes the stored network the one of the epoch that ⁠$internal_tuned_values⁠ reports, and costs one additional copy of the network's parameters in memory.

Dataloader:

• batch_size :: integer(1)
  The batch size used by the training and prediction dataloader. It is required for training (unless a batch_sampler is provided, which already determines the batches) and it is required for prediction (unless batch_size_predict is set).

• batch_size_predict :: integer(1)
  The batch size used by the prediction dataloader (this includes the validation data during training). When set, it overrides batch_size for prediction. The batch size does not change the predictions, but smaller batches take longer and require less memory.

• shuffle :: logical(1)
  Whether to shuffle the instances in the dataset. This is initialized to TRUE, which differs from the default (FALSE). It is ignored when a sampler or batch_sampler is provided.

• sampler :: torch::sampler
  Object that defines how the dataloader draws samples, i.e. the order in which the observations are drawn. This must be the sampler generator (as returned by torch::sampler()), not an instance, as it is instantiated with the training dataset internally.

• batch_sampler :: torch::sampler
  Object that defines how the dataloader draws batches. As for sampler, this must be the generator. When it is provided, the parameters batch_size, shuffle and drop_last are ignored during training, because the batch sampler already determines the batches.

• num_workers :: integer(1)
  The number of workers for data loading (batches are loaded in parallel). The default is 0, which means that data will be loaded in the main process.

• collate_fn :: function
  How to merge a list of samples to form a batch.

• pin_memory :: logical(1)
  Whether the dataloader copies tensors into CUDA pinned memory before returning them.

• drop_last :: logical(1)
  Whether to drop the last training batch in each epoch during training. Default is FALSE. If it is TRUE, the batch size is capped at the number of training observations, so that not all of them are dropped. It is ignored when a batch_sampler is provided.

• timeout :: numeric(1)
  The timeout value for collecting a batch from workers. Negative values mean no timeout and the default is -1.

• worker_init_fn :: ⁠function(id)⁠
  A function that receives the worker id (in ⁠[1, num_workers]⁠) and is executed after seeding on the worker but before data loading.

• worker_globals :: list() | character()
  When loading data in parallel, this makes it possible to export globals to the workers. If this is a character vector, the objects in the global environment with those names are copied to the workers.

• worker_packages :: character()
  Which packages to load on the workers.

Also see torch::dataloader for more information.

Inheriting

There are no separate classes for classification and regression to inherit from. Instead, the task_type must be specified as a construction argument. Any task type that is registered in mlr_reflections$task_types can be used. Support for a task type that mlr3torch does not know is added by implementing methods for the three S3 generics that hold the task-type-specific behaviour: output_dim_for() (how many output neurons the network needs), get_target_batchgetter() (how the target is turned into a tensor) and encode_prediction() (how the network's output is turned back into a prediction). Such a learner also has to be given a loss explicitly, unless a default loss is registered for the task type by adding the id of a loss from mlr3torch_losses to mlr_reflections$torch$default_losses, e.g. mlr_reflections$torch$default_losses$surv = "my_surv_loss". See the Adding a New Task Type article for a complete example. This class can also be used for custom task types, see TaskTorch and the Custom Learning Problems article for more information.

When inheriting from this class, one should overload the following methods:

• .network(task, param_vals)
  (Task, list()) -> nn_module
  Construct a torch::nn_module object for the given task and parameter values, i.e. the neural network that is trained by the learner. Note that a specific output shape is expected from the returned network, see section Network Head and Target Encoding. That section also describes when a network can return more than one tensor. You can use output_dim_for() to obtain the correct output dimension for a given task.

• .setup_training(ctx, param_vals)
  (ContextTorch, list()) -> NULL
  Customizes a training run by modifying the context in place; the default does nothing. It is called once the data loaders, the network and the configured loss (self$loss$generate(task)) are created, and before training (or resuming) starts. At this point, ctx$optimizer is NULL and ctx$callbacks contains the configured callbacks. The method may:

  • replace ctx$network. This is also the network that is used for prediction.

  • replace ctx$loss_fn, e.g. to wrap the configured loss when the network returns more than one prediction, see the aux_logits parameter of classif.inception_v3.

  • set ctx$optimizer, e.g. to self$optimizer$generate(groups) with parameter groups for parameter-specific learning rates. Otherwise, the optimizer is generated from the final ctx$network afterwards. Use self$optimizer$generate(), so that the optimizer's parameters (including param_groups) are respected, and set the optimizer after replacing the network.

  • add callbacks to ctx$callbacks. The configured callbacks may not be removed or replaced, and the id "early_stopping" is reserved.

  Call super$.setup_training(ctx, param_vals) first. The method must be deterministic given param_vals, so that resuming from a checkpoint can restore the optimizer and callback states. With jit_trace = TRUE, ctx$network is already traced.

• .ingress_tokens(task, param_vals)
  (Task, list()) -> named list() with TorchIngressTokens
  Create the TorchIngressTokens that are passed to the task_dataset constructor. The number of ingress tokens must correspond to the number of input parameters of the network. If there is more than one input, the names must correspond to the inputs of the network. See ingress_num, ingress_categ, and ingress_ltnsr on how to easily create the correct tokens. For more flexibility, you can also directly implement the .dataset(task, param_vals) method, see below.

• .dataset(task, param_vals)
  (Task, list()) -> torch::dataset
  Create the dataset for the task. Don't implement this if the .ingress_tokens() method is defined. The dataset must return a named list where:

  • x is a list of torch tensors that are the input to the network. For networks with more than one input, the names must correspond to the inputs of the network.

  • y is the target tensor.

  • .index are the indices of the batch (integer() or a torch_int()).

  For information on the expected target encoding of y, see section Network Head and Target Encoding. Moreover, one needs to pay attention respect the row ids of the provided task. It is recommended to relu on task_dataset for creating the dataset.

It is also possible to overwrite the private .dataloader() method. This must respect the dataloader parameters from the ParamSet.

• .dataloader(dataset, param_vals)
  (dataset, list()) -> torch::dataloader
  Create a dataloader from the dataset. Needs to respect at least batch_size and shuffle (otherwise predictions will be incorrectly ordered). Use get_batch_size(param_vals, "train") to obtain the batch size for the respective phase, which takes the batch_size_predict parameter into account.

To change the predict types, it is possible to overwrite the method below:

• .encode_prediction(network_output, task)
  (torch_tensor or list() of them, Task) -> list()
  Take in the raw predictions from self$network (network_output) and encode them into a format that can be converted to valid mlr3 predictions using mlr3::as_prediction_data(). For classification, task has its classes in the order of the training task. It is a list() of tensors when the network returns more than one, see section Network Head and Target Encoding. This method must take self$predict_type into account.

While it is possible to add parameters by specifying the param_set construction argument, it is currently not possible to remove existing parameters, i.e. those listed in section Parameters. None of the parameters provided in param_set can have an id that starts with "loss.", "opt.", or "cb.", as these are preserved for the dynamically constructed parameters of the optimizer, the loss function, and the callbacks.

To perform additional input checks on the task, the private .check_train_task(task, param_vals) and .check_predict_task(task, param_vals) can be overwritten. These should return TRUE if the input task is valid and otherwise a string with an error message.

For learners that have other construction arguments that should change the hash of a learner, it is required to implement the private ⁠$.additional_phash_input()⁠.

Super class

mlr3::Learner -> LearnerTorch

Active bindings

Methods

Public methods

• LearnerTorch$new()

• LearnerTorch$format()

• LearnerTorch$print()

• LearnerTorch$marshal()

• LearnerTorch$unmarshal()

• LearnerTorch$dataset()

• LearnerTorch$clone()

LearnerTorch$new()

Creates a new instance of this R6 class.

Usage

LearnerTorch$new(
  id,
  task_type,
  param_set,
  properties = character(),
  man,
  label,
  feature_types,
  optimizer = NULL,
  loss = NULL,
  packages = character(),
  predict_types = NULL,
  callbacks = list(),
  jittable = FALSE
)

Arguments