Skip to content

Dealing with Neural Networks

Bases: ABC, LightningModule, LoggerMixin

Base abstract class for Kit4DL modules.

Source code in kit4dl/nn/base.py 
133
134
135
136
def __init__(self, *args: Any, **kwargs: Any) -> None:
    super().__init__()
    self.configure(*args, **kwargs)
    self.save_hyperparameters()

configure abstractmethod 

configure(*args: Any, **kwargs: Any) -> None

Configure the architecture of the neural network.

Parameters

args: Any List of positional arguments to setup the network architecture *kwargs : Any List of named arguments required to setup the network architecture

Examples

def configure(self, input_dims, output_dims) -> None:
    self.fc1 = nn.Sequential(
        nn.Linear(input_dims, output_dims),
    )
Source code in kit4dl/nn/base.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
@abstractmethod
def configure(self, *args: Any, **kwargs: Any) -> None:
    """Configure the architecture of the neural network.

    Parameters
    ----------
    *args: Any
        List of positional arguments to setup the network architecture
    **kwargs : Any
        List of named arguments required to setup the network architecture

    Examples
    --------
    ```python
    def configure(self, input_dims, output_dims) -> None:
        self.fc1 = nn.Sequential(
            nn.Linear(input_dims, output_dims),
        )
    ```
    """
    raise NotImplementedError

run_step abstractmethod 

run_step(batch, batch_idx) -> tuple[Tensor, ...]

Carry out single train/validation/test step for the given batch.

Return a tuple of two torch.Tensor's: true labels and predicted scores. If you need to define separate logic for validation or test step, implement val_step or test_step methods, respectivelly.

Parameters

batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor The output of the Dataloader batch_idx : int Index of the batch

Returns

result : tuple of torch.Tensor A tuple of 2 or 3 items: - if a tuple of 2 elements: 1. torch.Tensor of ground-truth labels, 2. torch.Tensor output of the network, - if a tuple of 3 elements: 1. torch.Tensor of ground-truth labels, 2. torch.Tensor output of the network, 4. torch.Tensor with loss value.

Examples

...
def run_step(self, batch, batch_idx) -> tuple[torch.Tensor,  ...]:
    feature_input, label_input = batch
    scores = self(feature_input)
    return (label_input, scores)

...
def run_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
    feature_input, label_input = batch
    scores = self(feature_input)
    loss = super().compute_loss(prediction=logits, target=is_fire)
    return (label_input, scores, loss)
Source code in kit4dl/nn/base.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
@abstractmethod
def run_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
    """Carry out single train/validation/test step for the given `batch`.

    Return a tuple of two `torch.Tensor`'s: true labels and predicted scores.
    If you need to define separate logic for validation or test step,
    implement `val_step` or `test_step` methods, respectivelly.

    Parameters
    ----------
    batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor
        The output of the Dataloader
    batch_idx : int
        Index of the batch

    Returns
    -------
    result : tuple of `torch.Tensor`
        A tuple of 2 or 3 items:
        - if a tuple of 2 elements:
            1. `torch.Tensor` of ground-truth labels,
            2. `torch.Tensor` output of the network,
        - if a tuple of 3 elements:
            1. `torch.Tensor` of ground-truth labels,
            2. `torch.Tensor` output of the network,
            4. `torch.Tensor` with loss value.

    Examples
    --------
    ```python
    ...
    def run_step(self, batch, batch_idx) -> tuple[torch.Tensor,  ...]:
        feature_input, label_input = batch
        scores = self(feature_input)
        return (label_input, scores)
    ```

    ```python
    ...
    def run_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
        feature_input, label_input = batch
        scores = self(feature_input)
        loss = super().compute_loss(prediction=logits, target=is_fire)
        return (label_input, scores, loss)
    ```
    """
    raise NotImplementedError

run_val_step 

run_val_step(batch, batch_idx) -> tuple[Tensor, ...]

Carry out single validation step for the given batch.

Return a tuple of two torch.Tensor's: true labels and predicted scores. If you need to define separate logic for validation or test step, implement val_step or test_step methods, respectivelly.

Parameters

batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor The output of the Dataloader batch_idx : int Index of the batch

Returns

result : tuple of torch.Tensor A tuple of 2 or 3 items: - if a tuple of 2 elements: 1. torch.Tensor of ground-truth labels, 2. torch.Tensor output of the network, - if a tuple of 3 elements: 1. torch.Tensor of ground-truth labels, 2. torch.Tensor output of the network, 4. torch.Tensor with loss value.

Examples

...
def run_val_step(self, batch, batch_idx) -> tuple[torch.Tensor,  ...]:
    feature_input, label_input = batch
    scores = self(feature_input)
    return (label_input, scores)

...
def run_val_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
    feature_input, label_input = batch
    scores = self(feature_input)
    loss = super().compute_loss(prediction=logits, target=is_fire)
    return (label_input, scores, loss)
Source code in kit4dl/nn/base.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
def run_val_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
    """Carry out single validation step for the given `batch`.

    Return a tuple of two `torch.Tensor`'s: true labels and predicted scores.
    If you need to define separate logic for validation or test step,
    implement `val_step` or `test_step` methods, respectivelly.

    Parameters
    ----------
    batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor
        The output of the Dataloader
    batch_idx : int
        Index of the batch

    Returns
    -------
    result : tuple of `torch.Tensor`
        A tuple of 2 or 3 items:
        - if a tuple of 2 elements:
            1. `torch.Tensor` of ground-truth labels,
            2. `torch.Tensor` output of the network,
        - if a tuple of 3 elements:
            1. `torch.Tensor` of ground-truth labels,
            2. `torch.Tensor` output of the network,
            4. `torch.Tensor` with loss value.

    Examples
    --------
    ```python
    ...
    def run_val_step(self, batch, batch_idx) -> tuple[torch.Tensor,  ...]:
        feature_input, label_input = batch
        scores = self(feature_input)
        return (label_input, scores)
    ```

    ```python
    ...
    def run_val_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
        feature_input, label_input = batch
        scores = self(feature_input)
        loss = super().compute_loss(prediction=logits, target=is_fire)
        return (label_input, scores, loss)
    ```
    """
    return self.run_step(batch, batch_idx)

run_test_step 

run_test_step(batch, batch_idx) -> tuple[Tensor, ...]

Carry out single test step for the given batch.

Return a tuple of two torch.Tensor's: true labels and predicted scores. If you need to define separate logic for validation or test step, implement val_step or test_step methods, respectivelly.

Parameters

batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor The output of the Dataloader batch_idx : int Index of the batch

Returns

result : tuple of torch.Tensor A tuple of 2 or 3items: - if a tuple of 2 elements: 1. torch.Tensor of ground-truth labels, 2. torch.Tensor output of the network, - if a tuple of 3 elements: 1. torch.Tensor of ground-truth labels, 2. torch.Tensor output of the network, 4. torch.Tensor with loss value.

Examples

...
def run_test_step(self, batch, batch_idx) -> tuple[torch.Tensor,  ...]:
    feature_input, label_input = batch
    scores = self(feature_input)
    return (label_input, scores)

...
def run_test_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
    feature_input, label_input = batch
    scores = self(feature_input)
    loss = super().compute_loss(prediction=logits, target=is_fire)
    return (label_input, scores, loss)
Source code in kit4dl/nn/base.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
def run_test_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
    """Carry out single test step for the given `batch`.

    Return a tuple of two `torch.Tensor`'s: true labels and predicted scores.
    If you need to define separate logic for validation or test step,
    implement `val_step` or `test_step` methods, respectivelly.

    Parameters
    ----------
    batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor
        The output of the Dataloader
    batch_idx : int
        Index of the batch

    Returns
    -------
    result : tuple of `torch.Tensor`
        A tuple of 2 or 3items:
        - if a tuple of 2 elements:
            1. `torch.Tensor` of ground-truth labels,
            2. `torch.Tensor` output of the network,
        - if a tuple of 3 elements:
            1. `torch.Tensor` of ground-truth labels,
            2. `torch.Tensor` output of the network,
            4. `torch.Tensor` with loss value.

    Examples
    --------
    ```python
    ...
    def run_test_step(self, batch, batch_idx) -> tuple[torch.Tensor,  ...]:
        feature_input, label_input = batch
        scores = self(feature_input)
        return (label_input, scores)
    ```

    ```python
    ...
    def run_test_step(self, batch, batch_idx) -> tuple[torch.Tensor, ...]:
        feature_input, label_input = batch
        scores = self(feature_input)
        loss = super().compute_loss(prediction=logits, target=is_fire)
        return (label_input, scores, loss)
    ```
    """
    return self.run_step(batch, batch_idx)

run_predict_step 

run_predict_step(batch, batch_idx) -> Tensor

Carry out single predict step for the given batch.

Return a torch.Tensor - the predicted scores. If not overriden, the implementation of step method is used.

Parameters

batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor The output of the Dataloader batch_idx : int Index of the batch

Returns

result : torch.Tensor The score being the output of of the network

Note

The function returns just score values as for prediction we do not have the ground-truth labels.

Examples

...
def run_predict_step(self, batch, batch_idx) -> torch.Tensor:
    feature_input = batch
    return self(feature_input)
Source code in kit4dl/nn/base.py 
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
def run_predict_step(self, batch, batch_idx) -> torch.Tensor:
    """Carry out single predict step for the given `batch`.

    Return a `torch.Tensor` - the predicted scores.
    If not overriden, the implementation of `step` method is used.

    Parameters
    ----------
    batch : torch.Tensor or tuple of torch.Tensor or list of torch.Tensor
        The output of the Dataloader
    batch_idx : int
        Index of the batch

    Returns
    -------
    result : torch.Tensor
        The score being the output of of the network


    Note
    ----
    The function returns just score values as for prediction we do not have
    the ground-truth labels.

    Examples
    --------
    ```python
    ...
    def run_predict_step(self, batch, batch_idx) -> torch.Tensor:
        feature_input = batch
        return self(feature_input)
    ```
    """
    _, scores = self.run_step(batch, batch_idx)
    return scores

compute_loss 

compute_loss(prediction: Tensor, target: Tensor) -> Tensor

Compute the loss based on the prediction and target.

Source code in kit4dl/nn/base.py 
345
346
347
348
349
350
def compute_loss(
    self, prediction: torch.Tensor, target: torch.Tensor
) -> torch.Tensor:
    """Compute the loss based on the prediction and target."""
    assert self.criterion.is_defined, "criterion is not defined"
    return self.criterion(prediction, target)

training_step 

training_step(batch, batch_idx)

Carry out a single training step.

Source code in kit4dl/nn/base.py 
352
353
354
355
356
357
358
359
360
361
362
363
364
365
def training_step(
    self, batch, batch_idx
):  # pylint: disable=arguments-differ
    """Carry out a single training step."""
    res = self.run_step(batch, batch_idx)
    match res:
        case (y_true, y_scores):
            loss = self.compute_loss(y_scores, y_true)
        case (y_true, y_scores, loss):
            pass
        case _:
            self.error("wrong size of tuple returned by `run_step`")
            raise ValueError("wrong size of tuple returned by `run_step`")
    return self._prepare_step_output(pred=y_scores, true=y_true, loss=loss)

validation_step 

validation_step(batch, batch_idx)

Carry out a single validation step.

Source code in kit4dl/nn/base.py 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
def validation_step(
    self, batch, batch_idx
):  # pylint: disable=arguments-differ
    """Carry out a single validation step."""
    res = self.run_val_step(batch, batch_idx)
    match res:
        case (y_true, y_scores):
            loss = self.compute_loss(y_scores, y_true)
        case (y_true, y_scores, loss):
            pass
        case _:
            self.error("wrong size of tuple returned by `run_step`")
            raise ValueError("wrong size of tuple returned by `run_step`")
    return self._prepare_step_output(pred=y_scores, true=y_true, loss=loss)

test_step 

test_step(batch, batch_idx)

Carry out a single test step.

Source code in kit4dl/nn/base.py 
382
383
384
385
386
387
388
389
390
391
392
393
def test_step(self, batch, batch_idx):  # pylint: disable=arguments-differ
    """Carry out a single test step."""
    res = self.run_test_step(batch, batch_idx)
    match res:
        case (y_true, y_scores):
            loss = self.compute_loss(y_scores, y_true)
        case (y_true, y_scores, loss):
            pass
        case _:
            self.error("wrong size of tuple returned by `run_step`")
            raise ValueError("wrong size of tuple returned by `run_step`")
    return self._prepare_step_output(pred=y_scores, true=y_true, loss=loss)