srforge 0.16.0__tar.gz → 0.16.2__tar.gz

{srforge-0.16.0 → srforge-0.16.2}/CHANGELOG.md

@@ -7,6 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.2] - 2026-10-19
+
+### Added
+
+- **A loss that trains nothing is caught.** A loss with a non-zero weight
+  that passes no gradient — a hard `F1Score`, a metric calling `.detach()`
+  or `.item()`, a library metric computed without gradients — used to train
+  silently on nothing. Now:
+  - **`Metric.differentiable`** (default `True`) declares it. False for the
+    hard confusion ratios (true only with `soft=True`), the confusion
+    counts and `TBE`; `UncertaintyLoss` / `CorrectedLoss` follow their base
+    metric; a torchmetrics metric is differentiable when the library says so
+    and `aggregate="macro"`, a pyiqa metric when created with
+    `as_loss=True`. Each class's docstring states which configurations are
+    differentiable.
+  - **The trainer refuses** a training criterion (including every
+    criterion a `LossScheduler` switches to, and the GAN runner's D and G
+    criteria) that holds a declared non-differentiable metric with a
+    non-zero weight, naming it and what to use instead.
+  - **`LossGradientCheck`**, installed on every training runner, checks each
+    weighted loss once, on its first batch: not connected to the model
+    stops training, an exactly zero gradient warns. Hook-added loss terms
+    are checked too; weight-0 metrics are skipped. The runners'
+    `check_losses` option — `on` (default), `strict`, `off` — controls it.
+- **`get_class_weights(scheme="inverse_sqrt_freq")`** — weights `∝ 1/√f_c`,
+  for strongly imbalanced data where `inverse_freq` gets extreme (a class on
+  0.1% of the pixels: 32× instead of 1000×). Like `inverse_freq` it averages
+  to 1 over the pixels, keeping the weighted loss on the unweighted scale.
+- **More dataset statistics in `srforge.dataset.stats`**, each computed once
+  from the dataset when the config is built and passed on with `${ref:...}`:
+  `channel_mean_std` (per-channel mean and std), `value_range` (robust
+  per-channel low/high at chosen percentiles, with `bounds()` for
+  `Normalize` and `data_range()` for PSNR), `field_report` (shapes, dtypes,
+  NaN/inf and constant entries per field), `mask_coverage` and
+  `indices_with_coverage` (for a `SubsetDataset` without near-empty
+  samples), and `spatial_sizes`. They skip non-finite values, take
+  `mask_field`, and `max_samples` reads a seeded random subset.
+- **`Standardize` and `Destandardize` take one mean and std per channel**,
+  or `stats=` — the result of `channel_mean_std` — instead of the two.
+- **A `${ref:...}` may resolve to a number computed by a `_target`** or
+  returned by a method (`${ref:value_range}.data_range()`). The refusal
+  remains for references to plain config values, which belong in `${...}`.
+- **`Sigmoid`, `Softmax`, `SelectChannels` and `IgnoreValue` transforms** —
+  the glue between a real model and dataset and the classification metrics,
+  which read probabilities and a mask: logits become probabilities in the
+  runner's `postprocessor`, `SelectChannels` picks the positive class of a
+  two-channel model, and `IgnoreValue` turns a label's ignore value (e.g.
+  255) into a clean label plus a mask for `y_mask`.
+- **Documentation:** *Datasets* has a *Dataset Statistics* section;
+  *Classification Metrics* shows the path from logits and ignore labels;
+  *Trainers & Runners* → *Losses that train nothing*;
+  *Writing a Metric* covers `differentiable`.
+- **Documentation:** a rule of thumb for choosing the scheme — up to ~10×
+  imbalance `inverse_freq`, beyond that `inverse_sqrt_freq` or unweighted
+  BCE + `DiceLoss`.
+
+## [0.16.1] - 2026-09-25
+
+### Added
+
+- **Every confusion ratio can be trained on: `soft=True`.** F1, IoU and
+  the other ratios threshold the prediction, so no gradient passes through
+  them. With `soft=True` the same `ratio()` runs on soft counts
+  (`TP = Σ p·y`, …), equal to the hard counts on a 0/1 prediction — your
+  own ratios included. The ratio keeps its direction: soft F1 is
+  higher-is-better and the training total negates it, as for PSNR or SSIM,
+  so a negative weighted Dice is what "maximising" looks like. `smooth`
+  defaults to 1 when soft (0 when hard), without which a batch with no
+  positives gives no gradient; the default name becomes `Soft<Class>` so a
+  soft value is never logged under the hard metric's name, and an explicit
+  `name` is kept. A `threshold` is refused with `soft=True`.
+- **`DiceLoss`, `JaccardLoss`, `TverskyLoss`** — `F1Score`, `IoU` and
+  `TverskyIndex` with `soft=True` built in, by the names they are known
+  under.
+- **`BinaryCrossEntropy`** — per-pixel `−[y·log p + (1−y)·log(1−p)]` on a
+  probability map, with optional `class_weights=(negative, positive)`. The
+  usual change-detection criterion is it plus `DiceLoss`.
+- **`TverskyIndex(alpha, beta)`** — F1 and IoU with false alarms and missed
+  positives priced apart.
+- **`CrossEntropy` takes `class_weights`** (one per class) **and class-index
+  targets** (`[B, H, W]` or `[B, 1, H, W]`, integer) as well as one-hot or
+  soft ones — what projects wrote their own class-balanced CE for.
+- **`srforge.dataset.stats.get_class_weights`** — class-balancing weights
+  counted once from a dataset when the config is built, for the losses'
+  `class_weights` (`${ref:...}` passes them on). `inverse_freq` (rare classes
+  weigh more) or `proportional`; `ignore_index` and `mask_field` leave
+  elements out. `class_counts` gives the raw counts. The first of the
+  dataset-statistics helpers, so losses no longer iterate the data.
+- **Documentation:** *Classification Metrics* has a *Training with them*
+  section.
+
+### Fixed
+
+- **`CrossEntropy` was not a cross-entropy on a yes/no map.** It computed
+  `−y·log p` per element and averaged over classes too: on one channel there
+  was no term for the negative class, so predicting "yes" everywhere scored
+  a perfect 0. It now sums over the class axis (`−Σ_c y_c·log p_c` per
+  pixel) and refuses a one-channel prediction, pointing to
+  `BinaryCrossEntropy`. **Breaking:** on a multi-class map its value is `C`
+  times what it was (the mean no longer divides by the class count) —
+  rescale its `weight` in a `LossCombiner` to keep the old balance.
+- **`LPIPS` could return NaN gradients.** The `lpips` package normalises
+  each feature vector by `sqrt(sum(x²))` with `eps` only in the divisor, so
+  where the squared norm underflows to 0 the backward is infinite — tiny
+  activations in float32, and routinely small ones under float16 mixed
+  precision. Building `LPIPS` now swaps in a normalisation with `eps` under
+  the root and the norm computed in float32; values are unchanged to ~1e-10.
+
 ## [0.16.0] - 2026-09-25
 
 ### Changed
@@ -1494,7 +1602,9 @@ likelihood of affecting a given codebase:
 - `Preprocessor` and `TransformationSpec` removed; `EntryTransform` is standalone.
 - Codebase cleanup: `assert` replaced with proper exceptions, `super()` modernized.
 
-[Unreleased]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.16.0...HEAD
+[Unreleased]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.16.2...HEAD
+[0.16.2]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.16.1...v0.16.2
+[0.16.1]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.16.0...v0.16.1
 [0.16.0]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.15.4...v0.16.0
 [0.15.4]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.15.3...v0.15.4
 [0.15.3]: https://gitlab.com/tarasiewicztomasz/sr-forge/-/compare/v0.15.2...v0.15.3

{srforge-0.16.0/srforge.egg-info → srforge-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srforge
-Version: 0.16.0
+Version: 0.16.2
 Summary: Super‑resolution research framework for PyTorch with a focus on simplicity and flexibility using config files.
 Author-email: Tomasz Tarasiewicz <tomasz.tarasiewicz@polsl.pl>
 Project-URL: Homepage, https://gitlab.com/tarasiewicztomasz/sr-forge

srforge-0.16.2/docs/src/api/dataset/stats.md

@@ -0,0 +1,3 @@
+# Dataset Statistics
+
+::: srforge.dataset.stats

{srforge-0.16.0 → srforge-0.16.2}/docs/src/configuration.md

@@ -331,7 +331,8 @@ b: ${ref:a}
 | Reuse a config block (e.g., same transforms for train and val) | `${path}` | Each dataset gets its own independent pipeline |
 | Share one object (e.g., optimizer needs the model's params) | `${ref:path}` | Must be the exact same Python object |
 | Call a method on another object | `${ref:path}.method()` | Only references support method chains |
-| Copy a scalar value (number, string) | `${path}` | `${ref:}` raises TypeError on primitives |
+| Copy a scalar value (number, string) | `${path}` | `${ref:}` to a plain value raises TypeError |
+| Use a number *computed* by a `_target` (e.g. a [dataset statistic](datasets.md#dataset-statistics)) | `${ref:path}` or `${ref:path}.method()` | It has no `${...}` spelling — it exists only once built |
 
 ---
 

{srforge-0.16.0 → srforge-0.16.2}/docs/src/datasets.md

@@ -404,6 +404,110 @@ Supports optional internal disk caching (`use_internal_cache=True`) with cross-p
 
 ---
 
+## Dataset Statistics
+
+Some numbers a run needs are properties of the data: the mean and std to
+standardise with, the value range PSNR measures against, the class balance
+a loss weighs by. Guessing them, or copying them from another project, is
+how they go stale. `srforge.dataset.stats` computes them from the dataset
+**once, when the config is built**, and `${ref:...}` hands them on.
+
+| Helper | Gives you | Feeds |
+|---|---|---|
+| `channel_mean_std` | mean and std per channel | `Standardize` / `Destandardize` (`stats=`) |
+| `value_range` | robust low/high per channel (percentiles) | `Normalize(range=...)`, `PSNR(data_range=...)` |
+| `get_class_weights` | one weight per class | the cross-entropies' `class_weights` — see [Classification Metrics](metrics/classification-metrics.md#training-with-them) |
+| `class_counts` | elements per class | your own use |
+| `field_report` | shapes, dtypes, NaN/inf, constant entries | a check before training |
+| `mask_coverage` / `indices_with_coverage` | the valid share of each entry's mask | a `SubsetDataset` without near-empty samples |
+| `spatial_sizes` | the height × width the entries come in | choosing a patch size |
+
+```yaml
+stats:
+  _target: srforge.dataset.stats.channel_mean_std
+  params:
+    dataset: ${ref:dataset.training}
+    field: lr
+
+value_range:
+  _target: srforge.dataset.stats.value_range
+  params:
+    dataset: ${ref:dataset.training}
+    field: hr
+    percentiles: [0, 100]
+
+# ... in the transforms:
+- _target: srforge.transform.data.Standardize
+  params:
+    stats: ${ref:stats}            # one mean and std per channel
+
+# ... in the metrics:
+- _target: srforge.metrics.regression.PSNR
+  params:
+    data_range: ${ref:value_range}.data_range()
+```
+
+??? tip "Why per channel, and why percentiles"
+
+    Each band of a multispectral or SAR image has its own scale; one mean
+    and std for all of them leaves the quiet bands nearly flat. That is why
+    `channel_mean_std` works per channel, and why `Standardize` and
+    `Destandardize` now accept one value per channel.
+
+    `value_range` defaults to the 1st and 99th percentile rather than the
+    true minimum and maximum, which a single saturated pixel or speckle
+    outlier can set on its own. Pass `percentiles: [0, 100]` for the exact
+    ends — right for `PSNR`, whose `data_range` should be the real
+    peak-to-peak span. On a large dataset the percentiles are estimated from
+    up to a million values per channel, drawn evenly across the entries.
+
+??? tip "Checking the data: `field_report`"
+
+    ```python
+    from srforge.dataset.stats import field_report
+
+    report = field_report(train_dataset)      # logs one line per field
+    report["hr"].non_finite                    # NaN / inf count
+    report["hr"].problems()                    # ['12 non-finite value(s) (0.01%)', ...]
+    ```
+
+    It flags NaN and infinite values, constant entries (a blank tile, a
+    failed read), and fields whose shape or dtype changes between entries.
+    A field holding a mapping of bands is reported band by band. Nothing is
+    changed — it is a report, to run before training rather than find a NaN
+    an epoch in.
+
+??? tip "Dropping almost-empty samples: `indices_with_coverage`"
+
+    ```yaml
+    dataset:
+      training:
+        _target: srforge.dataset.SubsetDataset
+        params:
+          dataset: ${ref:dataset.full}
+          indices:
+            _target: srforge.dataset.stats.indices_with_coverage
+            params:
+              dataset: ${ref:dataset.full}
+              mask_field: valid
+              minimum: 0.2            # keep entries at least 20% valid
+    ```
+
+**Common to all of them:**
+
+- Each reads the whole dataset once through `dataset[i]`, so the dataset's
+  transforms run first. Two helpers mean two passes; `max_samples` reads a
+  seeded random subset instead, for datasets too large to walk at start-up.
+- The value helpers take `mask_field` — elements where that mask is 0 are
+  left out — and skip NaN and infinite values.
+- Under `torchrun` every process computes the same result independently.
+- A field holding a mapping of bands is refused by the per-channel helpers;
+  select or stack the bands with a transform first.
+
+The full signatures are in the [API reference](api/dataset/stats.md).
+
+---
+
 ## DataLoader Integration
 
 `DataLoaderFactory` creates a PyTorch `DataLoader` with the right collation for your dataset. It takes the same `batch_size`, `shuffle`, `num_workers`, `pin_memory`, and other keyword arguments you'd normally pass to `DataLoader`, plus an optional `device` parameter for multi-GPU detection: