justdata 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. justdata/__init__.py +3 -0
  2. justdata/acoustic/__init__.py +381 -0
  3. justdata/acoustic/adapters.py +329 -0
  4. justdata/acoustic/augment/__init__.py +119 -0
  5. justdata/acoustic/augment/batch.py +813 -0
  6. justdata/acoustic/augment/configs.py +204 -0
  7. justdata/acoustic/augment/patchout.py +331 -0
  8. justdata/acoustic/augment/spectrogram.py +806 -0
  9. justdata/acoustic/augment/waveform.py +879 -0
  10. justdata/acoustic/batching.py +27 -0
  11. justdata/acoustic/channel.py +53 -0
  12. justdata/acoustic/compat/__init__.py +95 -0
  13. justdata/acoustic/compat/ast.py +626 -0
  14. justdata/acoustic/compat/ced.py +152 -0
  15. justdata/acoustic/compat/efficientat.py +243 -0
  16. justdata/acoustic/compat/panns.py +115 -0
  17. justdata/acoustic/compat/passt.py +191 -0
  18. justdata/acoustic/configs.py +519 -0
  19. justdata/acoustic/corruptions/__init__.py +33 -0
  20. justdata/acoustic/corruptions/codec.py +92 -0
  21. justdata/acoustic/corruptions/datasets.py +155 -0
  22. justdata/acoustic/corruptions/device.py +39 -0
  23. justdata/acoustic/corruptions/dynamics.py +55 -0
  24. justdata/acoustic/corruptions/filters.py +105 -0
  25. justdata/acoustic/corruptions/noise.py +173 -0
  26. justdata/acoustic/corruptions/registry.py +230 -0
  27. justdata/acoustic/corruptions/reverb.py +49 -0
  28. justdata/acoustic/corruptions/timefreq.py +127 -0
  29. justdata/acoustic/datasets.py +52 -0
  30. justdata/acoustic/dcase2025.py +814 -0
  31. justdata/acoustic/decoding.py +73 -0
  32. justdata/acoustic/eval_views.py +54 -0
  33. justdata/acoustic/evals.py +71 -0
  34. justdata/acoustic/filters.py +18 -0
  35. justdata/acoustic/frontends/__init__.py +37 -0
  36. justdata/acoustic/frontends/ast.py +116 -0
  37. justdata/acoustic/frontends/kaldi.py +34 -0
  38. justdata/acoustic/frontends/log.py +94 -0
  39. justdata/acoustic/frontends/mel.py +173 -0
  40. justdata/acoustic/frontends/mfcc.py +26 -0
  41. justdata/acoustic/frontends/pcen.py +26 -0
  42. justdata/acoustic/frontends/stft.py +174 -0
  43. justdata/acoustic/jax.py +23 -0
  44. justdata/acoustic/labels.py +169 -0
  45. justdata/acoustic/layouts.py +86 -0
  46. justdata/acoustic/metadata.py +152 -0
  47. justdata/acoustic/normalization.py +196 -0
  48. justdata/acoustic/pipelines.py +112 -0
  49. justdata/acoustic/postprocessing.py +328 -0
  50. justdata/acoustic/preprocessing.py +175 -0
  51. justdata/acoustic/presets.py +257 -0
  52. justdata/acoustic/registry.py +381 -0
  53. justdata/acoustic/resampling.py +218 -0
  54. justdata/acoustic/schema.py +51 -0
  55. justdata/acoustic/segment.py +369 -0
  56. justdata/acoustic/sources.py +503 -0
  57. justdata/acoustic/stages.py +59 -0
  58. justdata/acoustic/stats.py +50 -0
  59. justdata/acoustic/tasks.py +375 -0
  60. justdata/audio/__init__.py +20 -0
  61. justdata/core/__init__.py +74 -0
  62. justdata/core/adapters.py +46 -0
  63. justdata/core/augmentations.py +34 -0
  64. justdata/core/filters.py +94 -0
  65. justdata/core/finalization.py +173 -0
  66. justdata/core/label_mixing.py +129 -0
  67. justdata/core/loader.py +384 -0
  68. justdata/core/metadata.py +250 -0
  69. justdata/core/presets.py +155 -0
  70. justdata/core/registry.py +229 -0
  71. justdata/core/sources.py +87 -0
  72. justdata/core/stats.py +227 -0
  73. justdata/corruptions.py +52 -0
  74. justdata/py.typed +0 -0
  75. justdata/vision/__init__.py +17 -0
  76. justdata/vision/augmentations/__init__.py +31 -0
  77. justdata/vision/augmentations/auto.py +480 -0
  78. justdata/vision/augmentations/color.py +163 -0
  79. justdata/vision/augmentations/composed.py +156 -0
  80. justdata/vision/augmentations/geometric.py +302 -0
  81. justdata/vision/augmentations/mixing.py +232 -0
  82. justdata/vision/augmentations/registry.py +142 -0
  83. justdata/vision/corruptions/__init__.py +16 -0
  84. justdata/vision/corruptions/blur.py +65 -0
  85. justdata/vision/corruptions/digital.py +26 -0
  86. justdata/vision/corruptions/noise.py +20 -0
  87. justdata/vision/corruptions/registry.py +113 -0
  88. justdata/vision/corruptions/weather.py +100 -0
  89. justdata/vision/datasets.py +34 -0
  90. justdata/vision/encodings/__init__.py +1 -0
  91. justdata/vision/encodings/heatmaps.py +196 -0
  92. justdata/vision/minic.py +69 -0
  93. justdata/vision/pipelines.py +62 -0
  94. justdata/vision/presets.py +509 -0
  95. justdata/vision/sources.py +1080 -0
  96. justdata/vision/stages.py +271 -0
  97. justdata/vision/tasks/__init__.py +1 -0
  98. justdata/vision/tasks/classification.py +321 -0
  99. justdata/vision/tasks/depth.py +25 -0
  100. justdata/vision/tasks/segmentation.py +194 -0
  101. justdata/vision/transforms.py +113 -0
  102. justdata/vision/utils.py +741 -0
  103. justdata-1.0.0.dist-info/METADATA +860 -0
  104. justdata-1.0.0.dist-info/RECORD +106 -0
  105. justdata-1.0.0.dist-info/WHEEL +4 -0
  106. justdata-1.0.0.dist-info/licenses/LICENSE +23 -0
@@ -0,0 +1,860 @@
1
+ Metadata-Version: 2.4
2
+ Name: justdata
3
+ Version: 1.0.0
4
+ Summary: A TensorFlow-native data pipeline library with a modality-neutral core and first-class computer vision and acoustic recipes
5
+ Author: clementpoiret
6
+ Author-email: clementpoiret <clement@linux.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Requires-Dist: loguru>=0.7.3
10
+ Requires-Dist: tensorflow>=2.18.1
11
+ Requires-Dist: tensorflow-datasets>=4.9.9
12
+ Requires-Dist: datasets[audio]>=4.5.0 ; extra == 'acoustic'
13
+ Requires-Dist: soundfile>=0.12 ; extra == 'acoustic'
14
+ Requires-Dist: soxr>=0.5 ; extra == 'acoustic'
15
+ Requires-Dist: librosa>=0.11 ; extra == 'acoustic'
16
+ Requires-Dist: torch==2.10.0 ; extra == 'acoustic'
17
+ Requires-Dist: torchcodec==0.10.0 ; extra == 'acoustic'
18
+ Requires-Dist: datasets[audio]>=4.5.0 ; extra == 'dev'
19
+ Requires-Dist: datasets[vision]>=4.5.0 ; extra == 'dev'
20
+ Requires-Dist: filelock>=3.20 ; extra == 'dev'
21
+ Requires-Dist: librosa>=0.11 ; extra == 'dev'
22
+ Requires-Dist: matplotlib>=3.10.8 ; extra == 'dev'
23
+ Requires-Dist: pillow>=12.2.0 ; extra == 'dev'
24
+ Requires-Dist: pytest>=9.0.2 ; extra == 'dev'
25
+ Requires-Dist: ruff==0.15.20 ; extra == 'dev'
26
+ Requires-Dist: soundfile>=0.12 ; extra == 'dev'
27
+ Requires-Dist: soxr>=0.5 ; extra == 'dev'
28
+ Requires-Dist: torch==2.10.0 ; extra == 'dev'
29
+ Requires-Dist: torchcodec==0.10.0 ; extra == 'dev'
30
+ Requires-Dist: torchaudio==2.10.0 ; extra == 'golden'
31
+ Requires-Dist: torchlibrosa==0.1.0 ; extra == 'golden'
32
+ Requires-Dist: datasets[vision]>=4.5.0 ; extra == 'vision'
33
+ Requires-Dist: filelock>=3.20 ; extra == 'vision'
34
+ Requires-Dist: pillow>=12.2.0 ; extra == 'vision'
35
+ Requires-Dist: wilds>=2.0.0 ; extra == 'wilds'
36
+ Requires-Python: >=3.11, <3.14
37
+ Provides-Extra: acoustic
38
+ Provides-Extra: dev
39
+ Provides-Extra: golden
40
+ Provides-Extra: vision
41
+ Provides-Extra: wilds
42
+ Description-Content-Type: text/markdown
43
+
44
+ # justdata
45
+
46
+ A TensorFlow-native data pipeline library with a modality-neutral core and first-class computer vision and acoustic recipes. `justdata.core` owns loading, adapter, preset, metadata, padding, and seeded execution machinery; `justdata.vision` owns image schemas, transforms, augmentations, corruptions, tasks, and vision presets. `justdata.acoustic` owns audio schemas, decoding, resampling, segmentation, frontends, augmentations, corruptions, DCASE helpers, stats, metadata/JAX helpers, and acoustic presets.
47
+
48
+ ______________________________________________________________________
49
+
50
+ ## Table of Contents
51
+
52
+ 1. [Installation](#installation)
53
+ 1. [Architecture](#architecture)
54
+ 1. [Data Pipeline Stages](#data-pipeline-stages)
55
+ 1. [Supervised Learning — Training Pipelines](#supervised-learning--training-pipelines)
56
+ 1. [Automatic Augmentation Policies: RandAugment, TrivialAugment, and TrivialAugmentWide](#automatic-augmentation-policies-randaugment-trivialaugment-and-trivialaugmentwide)
57
+ 1. [Supervised Learning — Validation Pipelines](#supervised-learning--validation-pipelines)
58
+ 1. [The `timm` ImageNet Recipes (ResNet Strikes Back: A1/A2/A3)](#the-timm-imagenet-recipes-resnet-strikes-back-a1a2a3)
59
+ 1. [Self-Supervised Learning Pipeline (DINOv2)](#self-supervised-learning-pipeline-dinov2)
60
+ 1. [Registry System](#registry-system)
61
+ 1. [Presets and Smart Merging](#presets-and-smart-merging)
62
+ 1. [Acoustic Pipelines](#acoustic-pipelines)
63
+ 1. [Dataset Adapters](#dataset-adapters)
64
+ 1. [Mini-C Corruption Benchmark](#mini-c-corruption-benchmark)
65
+ 1. [Audio Corruption Benchmark](#audio-corruption-benchmark)
66
+ 1. [Usage](#usage)
67
+ 1. [Development](#development)
68
+
69
+ ______________________________________________________________________
70
+
71
+ ## Installation
72
+
73
+ ```bash
74
+ pip install justdata
75
+ ```
76
+
77
+ **Requirements:** Python 3.11–3.13, TensorFlow ≥ 2.18.1, TensorFlow Datasets ≥ 4.9.9. Install optional modality extras with `justdata[vision]` for Hugging Face vision datasets, `justdata[wilds]` for WILDS image classification datasets, or `justdata[acoustic]` for audio dataset/source dependencies.
78
+
79
+ ______________________________________________________________________
80
+
81
+ ## Architecture
82
+
83
+ `justdata` is structured around a fixed, four-stage pipeline abstraction. The currently supported vision tasks, classification and segmentation, each expose exactly four composable functions. Object detection and depth estimation are future scope and are not registered capabilities.
84
+
85
+ ```
86
+ (preprocess_fn, augment_fn, late_augment_fn, postprocess_fn)
87
+ ```
88
+
89
+ These are assembled by `justdata.core.load_ds` into the following execution graph:
90
+
91
+ ```
92
+ fetch_ds -> adapter -> preprocess -> cache -> augment -> shuffle -> postprocess -> batch -> late_augment -> pad -> prefetch
93
+ ```
94
+
95
+ The strict ordering reflects the execution domain requirements articulated throughout this document: format normalization occurs before the optional preprocessing cache; spatial and photometric distortions precede tensor conversion and normalization; and batch-level operations (Mixup, CutMix, random erasing) occur after batching on the GPU. An optional model-input cache can be inserted after deterministic postprocessing and before batching; for training it must be explicitly opted in and is placed before shuffle so epoch order is not frozen.
96
+
97
+ ### Core Public API
98
+
99
+ | Function | Description |
100
+ | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
101
+ | `justdata.core.fetch_ds(dataset_names, splits_info, data_dir)` | Raw dataset loading through registered source loaders. Returns a `tf.data.Dataset` in canonical schema. |
102
+ | `justdata.core.load_ds(...)` | Full pipeline for training or evaluation. Handles caching, augmentation, shuffling, batching, and prefetching. |
103
+ | `justdata.vision.minic.create_minic_datasets(...)` | Constructs Mini-C corruption benchmark datasets from a shared preprocessed base dataset. |
104
+ | `justdata.acoustic.corruptions.create_audio_corruption_datasets(...)` | Constructs acoustic corruption benchmark datasets from a shared preprocessed base dataset. |
105
+ | `justdata.acoustic.dcase2025.make_source_dataset(...)` | Builds DCASE Task 1 source-domain datasets with split-safety checks. |
106
+
107
+ Import `justdata.vision` before resolving built-in vision datasets or pipelines. Hugging Face vision datasets are referenced with the `hf:` prefix (e.g., `hf:cifar10`), and WILDS image classification datasets are referenced with the `wilds:` prefix (e.g., `wilds:camelyon17`).
108
+
109
+ ______________________________________________________________________
110
+
111
+ ## Data Pipeline Stages
112
+
113
+ ### Stage 1: Preprocessing (before cache)
114
+
115
+ Format normalization is performed before the optional decoded-dataset cache. Operations include rank fixing (2D -> 3D), CHW -> HWC transposition, grayscale -> RGB expansion, and RGBA -> RGB projection. The output shape is forced to `[None, None, 3]`.
116
+
117
+ ### Stage 2: Augmentation (per-sample, training only)
118
+
119
+ Per-sample spatial and photometric augmentations are applied after the optional cache stage, ensuring that each training epoch receives independently sampled augmentations. All augmentation functions use `tf.random.split` for stateless randomization, enabling full reproducibility.
120
+
121
+ ### Stage 3: Postprocessing (every sample)
122
+
123
+ Resize, channel-wise normalization to zero mean and unit standard deviation, and optional HWC -> CHW transposition. This stage runs unconditionally for both training and evaluation.
124
+
125
+ Set `cache_model_inputs=True` with `model_input_cache_path` to cache these
126
+ resized, normalized tensors on local SSD. For `dataset_type="train"`, also set
127
+ `allow_train_model_input_cache=True` and use it only when the training view is
128
+ deterministic; stochastic crops or photometric augmentation will be materialized
129
+ into the cache on first fill.
130
+
131
+ ### Stage 4: Late Augmentation (per-batch, training only)
132
+
133
+ Batch-level operations—Mixup, CutMix, and random erasing—are applied after batching. These operations are strictly training-only and require a formed batch to operate across the sample dimension.
134
+
135
+ ______________________________________________________________________
136
+
137
+ ## Supervised Learning — Training Pipelines
138
+
139
+ To ensure mathematical correctness, the training pipeline is strictly segregated by execution domain. Spatial and photometric distortions are applied to `[0, 255]` image tensors (PIL-equivalent domain) before zero-mean tensor normalization.
140
+
141
+ ### 1. Image Domain Augmentations
142
+
143
+ #### Geometric Augmentations
144
+
145
+ - **CIFAR-10/100:** `RandomCrop(32, padding=4, padding_mode='zeros')` -> `RandomHorizontalFlip(p=0.5)`.
146
+ - **ImageNet-1K:** `RandomResizedCrop(size=224)` (or **256**). Scale: **(0.08, 1.0)**, Aspect ratio: **(0.75, 1.33)**, Interpolation: Bicubic. -> `RandomHorizontalFlip(p=0.5)`.
147
+
148
+ #### Photometric Augmentations (Mutually Exclusive Branches)
149
+
150
+ The photometric augmentation strategy is architecture-dependent and the two branches are mutually exclusive.
151
+
152
+ - **Modern Branch (ViT / ConvNeXt):** Apply `RandAugment(num_ops=2, magnitude=9)`, `TrivialAugment`, or `TrivialAugmentWide` (see the [Automatic Augmentation Policies](#automatic-augmentation-policies-randaugment-trivialaugment-and-trivialaugmentwide) section for full specifications). Color Jitter is explicitly disabled to prevent redundant and destructive color space distortion.
153
+ - **Legacy Branch (ResNet):** Apply `ColorJitter(brightness=0.4, contrast=0.4, saturation=0.4, hue=0.1)`. RandAugment is disabled.
154
+
155
+ ### 2. Tensor Domain
156
+
157
+ - **Conversion & Scaling:** `ToImage()` -> `ToDtype(float32, scale=True)`. Maps **[0, 255]** -> **[0.0, 1.0]**.
158
+ - **Normalization:**
159
+ - **CIFAR-10:** `mean=(0.4914, 0.4822, 0.4465)`, `std=(0.2023, 0.1994, 0.2010)`
160
+ - **CIFAR-100:** `mean=(0.5071, 0.4867, 0.4408)`, `std=(0.2675, 0.2565, 0.2761)`
161
+ - **ImageNet-1K:** `mean=(0.485, 0.456, 0.406)`, `std=(0.229, 0.224, 0.225)`
162
+ - **Random Erasing (Cutout):** Applied to the normalized tensor. `p=0.25`, `scale=(0.02, 0.33)`, `ratio=(0.3, 3.3)`.
163
+
164
+ ### 3. Mini-Batch Domain
165
+
166
+ Applied across the batch dimension during training.
167
+
168
+ - **Repeated Augmentation (RA):** Enabled for ViTs. Typically **3** repetitions per sample per mini-batch.
169
+ - **Mixup & CutMix:** Controlled by `mixup_prob=1.0` (probability of batch mixing) and `switch_prob=0.5` (probability of selecting CutMix over Mixup).
170
+ - **Mixup:** $\tilde{x} = \lambda x_i + (1 - \lambda) x_j$, where $\lambda \sim \mathrm{Beta}(0.8,, 0.8)$.
171
+ - **CutMix:** Replaces a rectangular bounding box region; $\lambda \sim \mathrm{Beta}(1.0,, 1.0)$.
172
+ - *Note: The $\alpha$ values (0.8 and 1.0) reflect the DeiT baseline. Mixup/CutMix parameters are strictly recipe-dependent; see the A1/A2/A3 section for ResNet-specific variations.*
173
+ - **Label Smoothing:** Cross-entropy loss modification with $\varepsilon = 0.1$.
174
+
175
+ ______________________________________________________________________
176
+
177
+ ## Automatic Augmentation Policies: RandAugment, TrivialAugment, and TrivialAugmentWide
178
+
179
+ `justdata` provides native TensorFlow implementations of three closely related automatic augmentation policies: **RandAugment** (Cubuk et al., 2020), **TrivialAugment** (Müller & Hutter, 2021), and **TrivialAugmentWide** (Müller & Hutter, 2021). All three are registered under the `augment_strategy` registry and share a common operation pool and magnitude discretization framework.
180
+
181
+ ### 1. Pipeline Position and Domain Constraints
182
+
183
+ To guarantee deterministic reproduction of published results, all three policies are applied exclusively in the **image domain** (integer `uint8` tensors, pixel values $\in [0, 255]$), before tensor conversion to floating-point and channel-wise normalization. The canonical execution order within the per-sample augmentation stage is:
184
+
185
+ 1. Random Resized Crop (or Random Pad Crop for CIFAR)
186
+ 2. **RandAugment / TrivialAugment / TrivialAugmentWide**
187
+ 3. Random Horizontal Flip *(integrated into the crop strategy)*
188
+ 4. `ToTensor` — scales to float $[0.0, 1.0]$ *(postprocessing stage)*
189
+ 5. `Normalize` — subtracts dataset mean, divides by standard deviation *(postprocessing stage)*
190
+
191
+ Applying photometric and geometric distortions prior to floating-point conversion ensures that operations such as `Posterize` and `Solarize`, which are defined on integer pixel arithmetic, remain numerically well-founded, and that fill values for geometric operations are expressed in the same integer domain as the source image.
192
+
193
+ ### 2. The RA Operation Space ($K = 14$)
194
+
195
+ All three algorithms draw from the **RA augmentation space**, a fixed pool of $K = 14$ operations. The pool is partitioned into two subsets based on magnitude dependency.
196
+
197
+ #### Magnitude-Independent Operations (3 ops)
198
+
199
+ These operations ignore the sampled magnitude $m$ entirely.
200
+
201
+ | Operation | Description |
202
+ | :--- | :--- |
203
+ | `Identity` | Returns the image unmodified. |
204
+ | `AutoContrast` | Linearly scales the pixel intensity histogram so that the darkest pixel maps to 0 and the brightest to 255. |
205
+ | `Equalize` | Equalizes the image histogram per channel using a cumulative distribution function. |
206
+
207
+ #### Magnitude-Dependent Operations (11 ops)
208
+
209
+ These operations scale their physical intensity as a function of the sampled magnitude index $m$.
210
+
211
+ **Sign randomization.** For all geometric operations (`Rotate`, `ShearX`, `ShearY`, `TranslateX`, `TranslateY`) and all color enhancement operations (`Brightness`, `Color`, `Contrast`, `Sharpness`), the direction of the applied transformation is randomized bidirectionally. Given a raw physical magnitude $v$ computed from $m$, the applied value is:
212
+
213
+ $$v' = v \cdot s, \quad s \sim \mathcal{U}\{-1, +1\}$$
214
+
215
+ This sign randomization is sampled independently per operation per sample, using a stateless seed derived from the layer's random state.
216
+
217
+ **Geometric fill.** When pixels are shifted outside the image boundary by `Rotate`, `ShearX`, `ShearY`, `TranslateX`, or `TranslateY`, the vacated regions are filled with a constant value (default: 128). Geometric operations use the implementation's fixed nearest-neighbor interpolation for images.
218
+
219
+ For segmentation pipelines, these geometric operations reuse the same sampled
220
+ parameters for the image and segmentation map. The image uses bilinear
221
+ interpolation, while the map uses nearest-neighbor interpolation and preserves
222
+ its integer dtype. Vacated map pixels use the configurable `mask_fill_value`
223
+ (default `255`), which must be treated as an ignore label by the training loss.
224
+ Photometric operations continue to affect only the image.
225
+
226
+ **Solarize semantics.** `Solarize` inverts all pixel values that are greater than or equal to the computed threshold $\tau$. Formally, for each pixel $p$:
227
+
228
+ $$p' = \begin{cases} 255 - p & \text{if } p \geq \tau \\ p & \text{otherwise} \end{cases}$$
229
+
230
+ where $\tau = 255 \cdot (1 - m / B)$. At $m = 0$, the threshold is 255 (no pixels inverted); at $m = B$, the threshold is 0 (all pixels inverted).
231
+
232
+ ### 3. Magnitude Discretization and Physical Mappings
233
+
234
+ The magnitude scale is a **31-bin discrete framework** with bin indices $m \in \{0, 1, \ldots, 30\}$ and $B = 30$ (the maximum bin index). This parameterization is the native scale of the `torchvision` (v0.13+) implementation of both RandAugment and TrivialAugmentWide.
235
+
236
+ The table below specifies the physical mapping formula and the operation-specific bound for each of the two spaces. $W$ and $H$ denote the input image width and height at the moment the augmentation is applied.
237
+
238
+ | Operation | Sign Rand. | Physical Mapping | Standard Bound (RA / TA) | Wide Bound (TA-Wide) |
239
+ | :--- | :---: | :--- | :--- | :--- |
240
+ | **Rotate** | Yes | $(m / B) \cdot \text{MaxDeg} \cdot s$ | 30.0° | 135.0° |
241
+ | **TranslateX** | Yes | $(m / B) \cdot \text{MaxPx}_X \cdot s$ | $(150 / 331) \times W$ | 32.0 px |
242
+ | **TranslateY** | Yes | $(m / B) \cdot \text{MaxPx}_Y \cdot s$ | $(150 / 331) \times H$ | 32.0 px |
243
+ | **ShearX** | Yes | $(m / B) \cdot \text{MaxShear} \cdot s$ | 0.3 | 0.99 |
244
+ | **ShearY** | Yes | $(m / B) \cdot \text{MaxShear} \cdot s$ | 0.3 | 0.99 |
245
+ | **Brightness** | Yes | $1.0 + (m / B) \cdot \text{MaxDelta} \cdot s$ | 0.9 | 0.99 |
246
+ | **Color** | Yes | $1.0 + (m / B) \cdot \text{MaxDelta} \cdot s$ | 0.9 | 0.99 |
247
+ | **Contrast** | Yes | $1.0 + (m / B) \cdot \text{MaxDelta} \cdot s$ | 0.9 | 0.99 |
248
+ | **Sharpness** | Yes | $1.0 + (m / B) \cdot \text{MaxDelta} \cdot s$ | 0.9 | 0.99 |
249
+ | **Posterize** | No | $8 - \mathrm{round}\!\left((m / B) \cdot \text{MaxBits}\right)$ | MaxBits = 4 (min 4 bits retained) | MaxBits = 6 (min 2 bits retained) |
250
+ | **Solarize** | No | $255.0 \cdot (1 - m / B)$ | threshold down to 0 | threshold down to 0 |
251
+ | **Identity** | — | — | — | — |
252
+ | **AutoContrast** | — | — | — | — |
253
+ | **Equalize** | — | — | — | — |
254
+
255
+ > **Note on TranslateX / TranslateY:** Translation is a deliberate exception to the "wider bounds" pattern. The TA-Wide space specifies a fixed ceiling of 32 px for both axes. For any image dimension exceeding approximately 71 px, the Standard RA space—whose ceiling scales proportionally with the image dimension—admits a **larger** maximum translation than the Wide space.
256
+
257
+ ### 4. Algorithm Specifications
258
+
259
+ #### 4.1 RandAugment (RA)
260
+
261
+ RandAugment (Cubuk et al., 2020) reduces the search space of AutoAugment from $\mathcal{O}(K^N)$ policies to two scalar hyperparameters: the number of sequential operations $N$ and the global magnitude $M$.
262
+
263
+ **Procedure.** Given a training image $x$:
264
+
265
+ 1. Independently sample $N$ operation indices $k_1, \ldots, k_N$ uniformly at random **with replacement** from the pool of $K$ operations.
266
+ 2. For each selected operation $T_{k_i}$, map the fixed global magnitude $M$ to a physical parameter via the operation-specific formula in the table above, applying sign randomization where applicable.
267
+ 3. Apply the operations sequentially: $x \leftarrow T_{k_N}(\cdots T_{k_1}(x))$.
268
+
269
+ The magnitude $M$ is expressed on the **31-bin scale** ($M \in \{0, \ldots, 30\}$) used throughout `justdata`. An optional magnitude perturbation $\sigma > 0$ samples the effective level per layer from $\mathcal{N}(M, \sigma^2)$, clipped to $[0, B]$.
270
+
271
+ **API parameters** (`augment_strategy = "rand_augment"` or direct call to `rand_augment`):
272
+
273
+ | Parameter | Type | Default | Description |
274
+ | :--- | :--- | :--- | :--- |
275
+ | `num_layers` | `int` | 2 | Number of operations $N$ applied per image. |
276
+ | `magnitude` | `float` | 9.0 | Global magnitude $M$ on the 31-bin scale. |
277
+ | `magnitude_std` | `float` | 0.0 | Per-layer Gaussian magnitude noise $\sigma$. Set to 0.5 to replicate `timm` stochastic magnitude. |
278
+ | `prob_to_apply` | `float \| None` | `None` | If set, each layer is skipped with probability $1 - p$. |
279
+ | `rotate_max` | `float` | 30.0 | Maximum rotation angle in degrees. |
280
+ | `shear_max` | `float` | 0.3 | Maximum shear coefficient (Standard RA space). |
281
+ | `enhance_max` | `float` | 0.9 | Maximum delta for brightness, color, contrast, sharpness. |
282
+ | `posterize_max_bits` | `int` | 4 | Bits removed at maximum magnitude; min retained = $8 - \text{MaxBits}$. |
283
+ | `translate_const` | `float` | 100.0 | Absolute translate ceiling in pixels. For Standard RA, set to $(150/331) \times \text{image\_width}$. |
284
+ | `exclude_ops` | `list[str] \| None` | `None` | Operations to exclude from the sampling pool. |
285
+
286
+ **Published optimal hyperparameters and 31-bin scale conversion.** The original paper (Cubuk et al., 2020) reports hyperparameters on an **11-level scale** ($M_{\text{paper}} \in \{0, \ldots, 10\}$). To replicate those results using the 31-bin scale employed by `justdata`, apply the conversion $m = M_{\text{paper}} \times 3$.
287
+
288
+ | Dataset | Architecture | $N$ | $M_{\text{paper}}$ | $m$ (31-bin) |
289
+ | :--- | :--- | :---: | :---: | :---: |
290
+ | CIFAR-10 | WideResNet-28-2 | 3 | 4 | 12 |
291
+ | CIFAR-10 | WideResNet-28-10 | 3 | 5 | 15 |
292
+ | CIFAR-10 | PyramidNet + ShakeDrop | 3 | 7 | 21 |
293
+ | CIFAR-10 | Shake-Shake | 3 | 9 | 27 |
294
+ | ImageNet-1K | ResNet-50 | 2 | 9 | 27 |
295
+ | ImageNet-1K | EfficientNet-B7 | 2 | — | 28† |
296
+
297
+ > †The EfficientNet-B7 value was reported on an extended scale beyond 10; cross-verify against the target codebase before use. The `torchvision` default of `magnitude=9` on the 31-bin scale corresponds to moderate augmentation and is **not** equivalent to the paper's $M_{\text{paper}} = 9$.
298
+
299
+ #### 4.2 TrivialAugment (TA)
300
+
301
+ TrivialAugment (Müller & Hutter, 2021) eliminates hyperparameter search entirely by selecting a single operation and sampling its magnitude uniformly at random from the full discrete range on each forward pass.
302
+
303
+ **Procedure.** Given a training image $x$:
304
+
305
+ 1. Sample one operation index $k \sim \mathcal{U}\{1, \ldots, K\}$ uniformly from the 14-op RA pool.
306
+ 2. Sample a magnitude $m \sim \mathcal{U}\{0, 1, \ldots, 30\}$ uniformly from the full 31-bin range.
307
+ 3. Map $m$ to a physical parameter via the **Standard** bounds in the table above, applying sign randomization where applicable.
308
+ 4. Apply the single operation: $x \leftarrow T_k(x)$.
309
+
310
+ The proportional translate ceiling is computed dynamically as $(150 / 331) \times W$ (image width), matching the Standard RA space definition.
311
+
312
+ **API:** `augment_strategy = "trivial_augment"`. Accepts `translate_const` (float, optional; computed from image width if not supplied) and `exclude_ops` (list of strings, optional).
313
+
314
+ #### 4.3 TrivialAugmentWide (TA-Wide)
315
+
316
+ TrivialAugmentWide (Müller & Hutter, 2021) is the native `torchvision` variant of TrivialAugment. It uses the same zero-hyperparameter, single-operation protocol as baseline TA, but operates over the **Wide** magnitude bounds, substantially expanding the geometric and photometric search range.
317
+
318
+ **Procedure.** Identical to TrivialAugment, with two differences:
319
+
320
+ 1. The **Wide** physical bounds from the table above are applied in place of the Standard bounds.
321
+ 2. The translate ceiling is a fixed **32 px** (not image-proportional).
322
+
323
+ Wide bounds summary:
324
+
325
+ | Transformation | Standard RA / TA | TA-Wide |
326
+ | :--- | :--- | :--- |
327
+ | Rotation range | ±30° | **±135°** |
328
+ | Shear range (X and Y) | ±0.3 | **±0.99** |
329
+ | Enhancement delta (Brightness, Color, Contrast, Sharpness) | ±0.9 | **±0.99** |
330
+ | Posterize (minimum bits retained) | 4 | **2** |
331
+ | Translation (fixed ceiling) | $(150/331) \times \text{dim}$ | **32 px** |
332
+
333
+ **API:** `augment_strategy = "trivial_augment_wide"`. Accepts `exclude_ops` (list of strings, optional). The wide bounds are fixed by design and cannot be overridden via kwargs; to use custom bounds, call `rand_augment` directly with `num_layers=1` and the desired parameters.
334
+
335
+ ### 5. Algorithm Comparison
336
+
337
+ | Property | RandAugment | TrivialAugment | TrivialAugmentWide |
338
+ | :--- | :--- | :--- | :--- |
339
+ | **Operations applied per image** | $N$ (tunable, with replacement) | 1 (fixed) | 1 (fixed) |
340
+ | **Magnitude $m$** | Fixed global $M$, constant across ops | Sampled: $m \sim \mathcal{U}\{0, \ldots, 30\}$ | Sampled: $m \sim \mathcal{U}\{0, \ldots, 30\}$ |
341
+ | **Hyperparameter search required** | Grid search over $(N, M)$ | None | None |
342
+ | **Transformation bounds** | Standard RA space | Standard RA space | Wide space |
343
+ | **Translate ceiling** | Configurable (default 100 px) | $(150/331) \times W$ (image-proportional) | 32 px (fixed) |
344
+ | **Reference implementation** | `torchvision` | `automl/trivialaugment` | `torchvision` |
345
+ | **`justdata` registry key** | `rand_augment` | `trivial_augment` | `trivial_augment_wide` |
346
+
347
+ ### 6. Non-RA Operations
348
+
349
+ The following internal primitives exist in the implementation but are **excluded from the fixed 14-op RA pool** and cannot be selected through RandAugment, TrivialAugment, or TrivialAugmentWide. The public `exclude_ops` parameter can remove operations from the pool; it cannot add these primitives.
350
+
351
+ | Operation | Notes |
352
+ | :--- | :--- |
353
+ | `Invert` | Inverts all pixel values: $p' = 255 - p$. |
354
+ | `Cutout` | Erases a random square patch (fill with constant). Superseded by the `random_erasing` late-augmentation stage. |
355
+ | `SolarizeAdd` | Additive solarization variant. |
356
+ | `Grayscale` | Converts to single-channel luminance and broadcasts to RGB. |
357
+
358
+ ______________________________________________________________________
359
+
360
+ ## Supervised Learning — Validation Pipelines
361
+
362
+ Validation pipelines are strictly deterministic. The objective shifts from regularization to feature preservation and scale alignment.
363
+
364
+ ### CIFAR-10 / CIFAR-100 Standard Validation
365
+
366
+ Because CIFAR images are inherently **32×32** and contain minimal background, spatial cropping destroys the primary subject.
367
+
368
+ **Pipeline:** `ToImage()` -> `ToDtype(float32, scale=True)` -> `Normalize` (training-set statistics as above).
369
+
370
+ ### ImageNet-1K Standard Baseline (The 0.875 Rule)
371
+
372
+ For standard supervised models and baseline linear probing, the canonical **0.875** crop ratio discards peripheral background.
373
+
374
+ **Pipeline:** `Resize(256, interpolation=Bicubic)` -> `CenterCrop(224)` -> `ToImage()` -> `ToDtype(float32, scale=True)` -> `Normalize`.
375
+
376
+ ### ImageNet-1K Modern Recipes (FixRes Strategy)
377
+
378
+ Modern recipes correct train-test resolution discrepancies by manipulating the validation crop percentage (`crop_pct`).
379
+
380
+ - **A3 (Light) Validation:** Train at **160×160**, validate at **224×224**. Resize shorter edge to **≈236**, then `CenterCrop(224)`.
381
+ - **A1 / A2 (Heavy/Moderate) Validation:** Default test at **224×224** (`crop_pct=1.0`, so `Resize(224)` -> `CenterCrop(224)`). Accuracy improves further via FixRes evaluation at **288×288** (`Resize(288)` -> `CenterCrop(288)`) as demonstrated in the RSB paper.
382
+
383
+ ______________________________________________________________________
384
+
385
+ ## The `timm` ImageNet Recipes (ResNet Strikes Back: A1/A2/A3)
386
+
387
+ The "ResNet Strikes Back" (RSB) recipes dynamically scale augmentation intensity and training schedules to match model capacity.
388
+
389
+ > **Crucial context:** These recipes were designed specifically for **ResNet-family architectures**. ViTs typically use distinct recipes (e.g., DeiT, BEiT) with different Mixup $\alpha$, optimizers (AdamW), and loss functions. While the principle of scaling augmentation with model capacity generalizes, the specific hyperparameters below do not transfer directly to ViTs.
390
+
391
+ | Parameter | A1 (Heavy) | A2 (Moderate) | A3 (Light) |
392
+ | :---------------------- | :--------------------------------------------------- | :---------------------- | :-------------------------------------------- |
393
+ | **Target Architecture** | Large ResNets (e.g., ResNet-152/200) or high compute | ResNet-50 (standard) | ResNet-50 (fast) or smaller (e.g., ResNet-18) |
394
+ | **Training Resolution** | 224 | 224 | **160** (FixRes strategy) |
395
+ | **Test Resolution** | 224 (scales to 288 via FixRes) | 224 | **224** |
396
+ | **Epochs** | **600** | **300** | **100** |
397
+ | **Optimizer** | LAMB | LAMB | LAMB |
398
+ | **LR Schedule** | Cosine with warmup | Cosine with warmup | Cosine with warmup |
399
+ | **Loss Function** | **BCE** (per-class binary) | **BCE** | **CE** (standard) |
400
+ | **RandAugment** | $m \approx 7$, $n = 2$ | $m \approx 6$, $n = 2$ | $m \approx 6$, $n = 2$ |
401
+ | **Random Erasing** | `p=0.35` | `p=0.25` | **Disabled** (`p=0.0`) |
402
+ | **Repeated Aug (RA)** | Enabled (3×) | Enabled (3×) | **Disabled** |
403
+ | **Mixup** $\alpha$ | 0.2 | 0.2 | 0.1 |
404
+ | **CutMix** $\alpha$ | 1.0 | 1.0 | 1.0 |
405
+ | **Stochastic Depth** | Capacity-dependent (e.g., 0.05+) | 0.0 | 0.0 |
406
+ | **EMA** | Yes | Yes | No (or lighter) |
407
+ | **Weight Decay** | 0.02 | 0.02 | 0.02 |
408
+
409
+ *Note: RandAugment parameter $n$ defaults to 2 per the original specification, though exact magnitude strings fluctuate across `timm` versions.*
410
+
411
+ ______________________________________________________________________
412
+
413
+ ## Self-Supervised Learning Pipeline (DINOv2)
414
+
415
+ DINOv2 employs a Teacher-Student knowledge distillation framework operating on multi-crop asymmetry to force the learning of semantic invariance over low-level frequency matching.
416
+
417
+ ### Multi-Crop Geometric Strategy
418
+
419
+ - **Global Crops (Context):** 2 crops at **224×224**. Scale: **(0.32, 1.0)**. Passed to both Teacher and Student.
420
+ - **Local Crops (Detail):** 8 crops at **96×96** (default). *Use **98×98** ($14 \times 7$) to avoid positional embedding interpolation when using ViT-14 backbones.* Scale: **(0.05, 0.32)**. Passed to Student only.
421
+
422
+ ### Asymmetric Pipeline Implementation
423
+
424
+ The per-crop asymmetry is structurally enforced by three distinct `Compose` pipelines rather than conditional branching within a single block. Each source image passes through all three pipelines to produce the full 10-crop suite.
425
+
426
+ - **`global_transform_1`**: Global Crop 1. Enforces strict blurring (`p=1.0`), disables solarization (`p=0.0`).
427
+ - **`global_transform_2`**: Global Crop 2. Minimizes blurring (`p=0.1`), enables solarization (`p=0.2`).
428
+ - **`local_transform`**: The 8 Local Crops. Moderate blurring (`p=0.5`), disables solarization (`p=0.0`).
429
+
430
+ ### Execution Order and Domain Separation (Per Crop)
431
+
432
+ | Step | Operation | Parameters / Per-Crop Asymmetry | Domain |
433
+ | :--- | :--------------------- | :------------------------------------------------------------------------------------------------------------------ | :----------------- |
434
+ | 1 | `RandomResizedCrop` | Aspect ratio **(0.75, 1.33)**, Bicubic interpolation. | Image |
435
+ | 2 | `RandomHorizontalFlip` | `p=0.5` (all crops) | Image |
436
+ | 3 | `ColorJitter` | `p=0.8` (all crops). `b=0.4, c=0.4, s=0.2, h=0.1` | Image |
437
+ | 4 | `RandomGrayscale` | `p=0.2` (all crops) | Image |
438
+ | 5 | `GaussianBlur` | $\sigma \sim \mathrm{Uniform}(0.1, 2.0)$, dynamic kernel. Global 1: `p=1.0` · Global 2: `p=0.1` · Local: `p=0.5` | Image |
439
+ | 6 | `Solarization` | Invert pixels $> 128$. Global 1: `p=0.0` · Global 2: `p=0.2` · Local: `p=0.0` | Image |
440
+ | 7 | Convert & Scale | `ToImage()` -> `ToDtype(float32, scale=True)` | Image -> Tensor |
441
+ | 8 | `Normalize` | ImageNet `mean` and `std`. | Tensor (zero-mean) |
442
+
443
+ ### SSL Downstream Evaluation
444
+
445
+ **Image-Level Classification (Linear Probing / $k$-NN):**
446
+ Standard supervised inference transforms: `Resize(256, Bicubic)` -> `CenterCrop(224)` -> `ToImage()` -> `ToDtype(float32)` -> `Normalize`. Features are extracted from the `[CLS]` token or a concatenation of `[CLS]` and average-pooled patch tokens.
447
+
448
+ **Dense Tasks (Segmentation / Depth Validation — Patch Alignment):**
449
+ To avoid dropping boundary pixels or forcing complex interpolation during dense evaluation, images are resized to the target scale and padded (reflection or zero) on the bottom and right edges such that both height and width are exact multiples of the ViT patch size (e.g., 14). This is implemented in `justdata.vision.transforms.pad_to_patch_multiple`.
450
+
451
+ ______________________________________________________________________
452
+
453
+ ## Registry System
454
+
455
+ All extensible components in `justdata` use a decorator-based registry pattern with thread-safe lookups.
456
+
457
+ | Registry | Decorator | Lookup |
458
+ | :-------------------- | :---------------------------------- | :---------------------------- |
459
+ | Crop strategies | `@register_crop_strategy(name)` | `justdata.vision.augmentations.get_crop_strategy(name)` |
460
+ | Augment strategies | `@register_augment_strategy(name)` | `justdata.vision.augmentations.get_augment_strategy(name)` |
461
+ | Corruptions | `@register_corruption(name)` | `justdata.vision.corruptions.apply_minic_corruption(...)` |
462
+ | Dataset adapters | `@register_adapter(dataset_name)` | `justdata.core.get_adapter(dataset_name)` |
463
+ | Source loaders | `@register_source_loader(prefix)` | `justdata.core.get_source_loader(dataset_name)` |
464
+ | Pipelines | `@register_pipeline("modality/task")` | `justdata.core.get_pipeline(...)` |
465
+ | Dataset metadata | `register_dataset(name, task_type, modality=...)` | `justdata.core.get_dataset_info(name)` |
466
+ | Audio frontends | `@register_audio_frontend(name)` | `justdata.acoustic.get_audio_frontend(name)` |
467
+ | Audio components | `@register_audio_*` decorators | `justdata.acoustic.get_audio_*`, `list_audio_*`, `has_audio_*` |
468
+
469
+ `get_pipeline` is the high-level resolver: it infers the task type from the dataset name, merges preset defaults with user-supplied kwargs (via smart merge; see below), and invokes the appropriate pipeline factory.
470
+
471
+ **Built-in crop strategies:** `random_resized`, `random_pad`, `random_hflip`, `resize_random_hflip`, `random_rot90_hflip`.
472
+
473
+ **Built-in augment strategies:** `rand_augment`, `trivial_augment`, `trivial_augment_wide`, `color_jitter`, `none`.
474
+
475
+ The acoustic package registers audio decoders, resamplers, channel strategies, segment strategies, frontends, augmentations, normalizations, eval views, postprocessors, and corruptions. Use `list_audio_*` helpers to inspect registered acoustic components.
476
+
477
+ ______________________________________________________________________
478
+
479
+ ## Presets and Smart Merging
480
+
481
+ `justdata.vision.presets` stores dataset-specific default kwargs for all four vision pipeline stages. The vision `_default` preset (ImageNet statistics, 224px, RandAugment) serves as the fallback for vision only.
482
+
483
+ **Available presets:**
484
+
485
+ | Preset | Description |
486
+ | :---------------- | :-------------------------------------------------------- |
487
+ | `_default` | ImageNet-1K statistics, 224px, RandAugment, modern branch |
488
+ | `cifar` | 32px, TrivialAugmentWide, CIFAR-10 normalization, no resizing |
489
+ | `cifar100` | 32px, TrivialAugmentWide, CIFAR-100 normalization |
490
+ | `imagenet_resnet` | ImageNet statistics, legacy branch with ColorJitter |
491
+ | `imagenet_a1` | RSB A1: heavy augmentation, BCE loss, 600 epochs |
492
+ | `imagenet_a2` | RSB A2: moderate augmentation, BCE loss, 300 epochs |
493
+ | `imagenet_a3` | RSB A3: light augmentation, CE loss, 160px training |
494
+ | `dinov2` | Asymmetric multi-crop SSL pipeline |
495
+ | `wilds:*` | WILDS benchmark defaults; matching `_strong` presets are opt-in |
496
+
497
+ `merge_with_presets(dataset, user_kwargs)` implements a **smart merge**: user-supplied kwargs that are identical to the `_default` preset values are treated as "not explicitly overridden," allowing dataset-specific preset values to take precedence. Only kwargs that genuinely differ from the defaults are considered intentional user overrides.
498
+
499
+ Resolved presets are serializable and hashable across modalities. Use `get_resolved_preset(name)` from `justdata.vision.presets`, `justdata.acoustic.presets`, or `justdata.core.presets` to obtain an object with `.to_json()` and `.hash()`. Hashes use canonical JSON with sorted keys and a 16-character SHA-256 prefix.
500
+
501
+ Acoustic presets are typed with `AudioPreset` and nested frozen config dataclasses for preprocessing, segmentation, frontends, labels, normalization, train augment settings, eval views, layout, and metadata policy. The `justdata.audio` namespace is a compatibility alias for `justdata.acoustic`.
502
+
503
+ See [docs/presets.md](docs/presets.md) for acoustic preset contracts, including EfficientAT/DyMN, PaSST, and CED.
504
+
505
+ ### Automatic preset resolution
506
+
507
+ When a vision dataset has a registered preset (e.g., `cifar10` -> `cifar`, `cifar100` -> `cifar100`), `get_pipeline` automatically applies it. Vision datasets without a dedicated preset fall back to the vision `_default`.
508
+
509
+ ```python
510
+ import justdata.vision
511
+ from justdata.core.registry import get_pipeline
512
+
513
+ # cifar10 automatically gets the 'cifar' preset (32px, TrivialAugmentWide, CIFAR-10 stats)
514
+ pipeline = get_pipeline(dataset="cifar10")
515
+ ```
516
+
517
+ ### Applying a named preset to any dataset
518
+
519
+ The `dataset` argument in `get_pipeline` drives preset lookup, not just task inference. To apply a specific named preset to a dataset that does not have its own preset (e.g., using `imagenet_a3` for `imagenette`), pass it as `preset`:
520
+
521
+ ```python
522
+ import justdata.vision
523
+ from justdata.core.loader import load_ds
524
+ from justdata.core.registry import get_pipeline
525
+
526
+ # Resolve the A3 (RSB light) pipeline for imagenette
527
+ pipeline = get_pipeline(
528
+ dataset="imagenette",
529
+ preset="imagenet_a3", # drives preset lookup: 160px train, 224px val, RandAugment m=6
530
+ )
531
+
532
+ train_ds, N = load_ds(
533
+ dataset_names_arg=["imagenette"], # actual dataset to load
534
+ splits_arg={"imagenette": ["train"]},
535
+ dataset_type="train",
536
+ batch_size=128,
537
+ seed=42,
538
+ pipeline=pipeline,
539
+ num_classes=10,
540
+ cache_dataset=False,
541
+ )
542
+ ```
543
+
544
+ The validation pipeline uses the same preset name; the A3 preset's FixRes strategy (`train_image_size=160`, `val_resize_size=236`) is applied automatically:
545
+
546
+ ```python
547
+ # The same pipeline can be used for validation; `load_ds` automatically sets `is_training=False` based on `dataset_type`
548
+ # and applies the deterministic center-crop resize (FixRes 236 → CenterCrop 224)
549
+ val_ds, N = load_ds(
550
+ dataset_names_arg=["imagenette"],
551
+ splits_arg={"imagenette": ["validation"]},
552
+ dataset_type="validation",
553
+ batch_size=256,
554
+ seed=0,
555
+ pipeline=pipeline,
556
+ num_classes=10,
557
+ cache_dataset=False,
558
+ )
559
+ ```
560
+
561
+ ______________________________________________________________________
562
+
563
+ ## Acoustic Pipelines
564
+
565
+ Import `justdata.acoustic` before resolving built-in acoustic datasets or pipelines. Acoustic samples use the canonical keys `waveform`, `sample_rate`, optional `label`, `features`, `duration`, and `metadata`.
566
+
567
+ ```python
568
+ import justdata.acoustic
569
+ from justdata.core.loader import load_ds
570
+ from justdata.core.registry import get_pipeline
571
+
572
+ pipeline = get_pipeline(
573
+ dataset="dcase2025_task1",
574
+ preset="dcase2025_task1_efficientat_32k_1s",
575
+ )
576
+
577
+ ds, n = load_ds(
578
+ dataset_names_arg=["dcase2025:task1"],
579
+ splits_arg={"dcase2025:task1": ["dev_train_25"]},
580
+ dataset_type="train",
581
+ batch_size=64,
582
+ seed=0,
583
+ pipeline=pipeline,
584
+ num_classes=10,
585
+ cache_dataset=False,
586
+ data_dir="/path/to/dcase",
587
+ metadata_mode="numeric_only",
588
+ as_numpy=True,
589
+ )
590
+ ```
591
+
592
+ Modality documentation:
593
+
594
+ - [docs/vision.md](docs/vision.md): vision schema, four stages, preset contracts, metadata modes, Mini-C, and parity matrix.
595
+ - [docs/acoustic.md](docs/acoustic.md): canonical schema, four stages, metadata modes, golden tests, corruption benchmark, and parity matrix.
596
+ - [docs/dcase2025.md](docs/dcase2025.md): DCASE Task 1 source/target helpers and split safety.
597
+ - [docs/presets.md](docs/presets.md): vision and acoustic preset selection and hashable contracts.
598
+ - [docs/golden_tests.md](docs/golden_tests.md): optional golden compatibility test workflow.
599
+
600
+ Examples are split by modality under `examples/vision/` and
601
+ `examples/acoustic/`. Each directory includes loading, Hugging Face source,
602
+ statistics, and corruption benchmark examples.
603
+
604
+ ______________________________________________________________________
605
+
606
+ ## Dataset Adapters
607
+
608
+ Core adapters normalize raw records into the modality-specific schema expected by a selected pipeline. `justdata.core` itself is schema-neutral, and the identity adapter is applied when no dataset-specific adapter is registered.
609
+
610
+ ### Vision adapter
611
+
612
+ Vision pipelines expect `image`, optional `label`, and task-specific fields such as `mask`.
613
+
614
+ ```python
615
+ from justdata.core.adapters import register_adapter
616
+
617
+ @register_adapter("my_dataset")
618
+ def my_adapter(sample):
619
+ return {"image": sample["img"], "label": sample["class_id"]}
620
+ ```
621
+
622
+ ### Acoustic adapter
623
+
624
+ Acoustic pipelines expect `waveform`, `sample_rate`, and an optional `label`.
625
+
626
+ ```python
627
+ from justdata.core.adapters import register_adapter
628
+
629
+ @register_adapter("my_audio_dataset")
630
+ def my_audio_adapter(sample):
631
+ result = {
632
+ "waveform": sample["audio"],
633
+ "sample_rate": sample["sampling_rate"],
634
+ }
635
+ if "target" in sample:
636
+ result["label"] = sample["target"]
637
+ return result
638
+ ```
639
+
640
+ ______________________________________________________________________
641
+
642
+ ## Mini-C Corruption Benchmark
643
+
644
+ `create_minic_datasets` constructs Mini-C benchmark evaluation datasets by forking from a preprocessed base dataset and applying severity-parameterized corruptions in place of standard augmentation. Pass `cache_dataset=True` with an explicit disk path when avoiding source re-reads across corruptions is worth the storage cost; otherwise the base remains streaming.
645
+
646
+ **Corruption categories and implementations:**
647
+
648
+ | Category | Corruptions |
649
+ | :------- | :---------------------------- |
650
+ | Blur | Defocus blur (disk kernel) |
651
+ | Noise | Gaussian noise, impulse noise |
652
+ | Digital | JPEG compression, pixelation |
653
+ | Weather | Fog, frost, rain, snow |
654
+
655
+ Each corruption is parameterized by severity levels 1–5 via pre-defined lookup tables.
656
+
657
+ ```python
658
+ import justdata.vision
659
+ from justdata.vision.minic import create_minic_datasets
660
+ from justdata.core.registry import get_pipeline
661
+
662
+ pipeline = get_pipeline(dataset="imagenet")
663
+
664
+ datasets = create_minic_datasets(
665
+ corruption_types=["gaussian_noise", "defocus_blur", "fog"],
666
+ severity=3,
667
+ dataset_names_arg=["imagenet2012"],
668
+ splits_arg={"imagenet2012": ["validation"]},
669
+ dataset_type="validation",
670
+ batch_size=256,
671
+ seed=0,
672
+ pipeline=pipeline,
673
+ num_classes=1000,
674
+ )
675
+ ```
676
+
677
+ ______________________________________________________________________
678
+
679
+ ## Audio Corruption Benchmark
680
+
681
+ `create_audio_corruption_datasets` mirrors Mini-C for acoustic evaluation. It applies deterministic severity 1-5 corruptions in the waveform or spectrogram domain, attaches corruption metadata, runs the normal postprocessing stage, and preserves `padding_mask`.
682
+
683
+ ```python
684
+ import justdata.acoustic
685
+ from justdata.acoustic.corruptions.datasets import create_audio_corruption_datasets
686
+ from justdata.core.registry import get_pipeline
687
+
688
+ pipeline = get_pipeline(
689
+ dataset="dcase2025_task1",
690
+ preset="dcase2025_task1_efficientat_32k_1s",
691
+ )
692
+
693
+ datasets, n = create_audio_corruption_datasets(
694
+ corruption_types=["additive_white_noise", "clipping"],
695
+ severity=3,
696
+ base_dataset="dcase2025:task1",
697
+ preset="dcase2025_task1_efficientat_32k_1s",
698
+ split="dev_test",
699
+ pipeline=pipeline,
700
+ batch_size=64,
701
+ seed=0,
702
+ num_classes=10,
703
+ metadata_mode="numeric_only",
704
+ )
705
+ ```
706
+
707
+ ______________________________________________________________________
708
+
709
+ ## Usage
710
+
711
+ ### Basic Classification Pipeline
712
+
713
+ ```python
714
+ import justdata.vision
715
+ from justdata.core.loader import load_ds
716
+ from justdata.core.registry import get_pipeline
717
+
718
+ pipeline = get_pipeline(dataset="cifar10")
719
+
720
+ train_ds, N = load_ds(
721
+ dataset_names_arg=["cifar10"],
722
+ splits_arg={"cifar10": ["train"]},
723
+ dataset_type="train",
724
+ batch_size=128,
725
+ seed=42,
726
+ pipeline=pipeline,
727
+ num_classes=10,
728
+ # CIFAR-10 is small enough for an intentional memory cache.
729
+ cache_dataset=True,
730
+ )
731
+ ```
732
+
733
+ ### Loading a Hugging Face Dataset
734
+
735
+ ```python
736
+ train_ds, n_batches = load_ds(
737
+ dataset_names_arg=["hf:cifar10"],
738
+ splits_arg={"hf:cifar10": ["train"]},
739
+ cache_dataset=False,
740
+ ...
741
+ )
742
+ ```
743
+
744
+ `load_ds` returns the dataset and its batch cardinality. The cardinality is a
745
+ Python integer when TensorFlow can determine it and `None` for unknown or
746
+ infinite pipelines.
747
+
748
+ For remote/downloaded sources, `data_dir` is a cache root. justdata namespaces
749
+ source-owned caches under it: `tfds/`, `hf/vision/`, `hf/acoustic/`, `wilds/`,
750
+ and `zenodo/`. If omitted, the root is `~/.cache/justdata`.
751
+
752
+ Loader caches are separate from source-owned caches. `cache_dataset/cache_path`
753
+ caches decoded, preprocessed samples before augmentation. Loader caching is off
754
+ by default, so datasets remain streaming when `cache_dataset` is omitted. Set
755
+ `cache_dataset=True` with an empty `cache_path` to opt into memory caching, or
756
+ provide a nonempty path to cache on the filesystem. Large datasets should use
757
+ an explicit disk path or remain uncached. `cache_model_inputs` and
758
+ `model_input_cache_path` cache resized, normalized model inputs before batching.
759
+ Use different paths for the two cache stages. This default changes performance,
760
+ not output values.
761
+
762
+ ### Loading a WILDS Dataset
763
+
764
+ WILDS image classification datasets use the `wilds:` source prefix. Source
765
+ options such as FMoW temporal split schemes live in the dataset string; when
766
+ using a `splits_arg` dictionary, reuse that exact string as the key.
767
+ Downloads are disabled by default (`download=false`). To download through
768
+ WILDS under `data_dir/wilds`, add `download=true` to the dataset string. Use
769
+ `&` between query options, not a second `?`.
770
+ The automatic presets are benchmark-faithful: Camelyon17 96 px, FMoW 224 px,
771
+ iWildCam 448 px, and RxRx1 256 px with per-image channel standardization.
772
+ Use `preset="wilds:fmow_strong"` or another `_strong` name to opt into stronger
773
+ training augmentation.
774
+
775
+ ```python
776
+ local_ssd = "/local_ssd/justdata"
777
+ wilds_ds = "wilds:fmow?split_scheme=time_after_2016&download=true"
778
+ pipeline = get_pipeline(dataset="wilds:fmow")
779
+
780
+ train_ds, N = load_ds(
781
+ dataset_names_arg=[wilds_ds],
782
+ splits_arg={wilds_ds: ["train"]},
783
+ dataset_type="train",
784
+ batch_size=32,
785
+ seed=42,
786
+ pipeline=pipeline,
787
+ num_classes=62,
788
+ data_dir=f"{local_ssd}/sources",
789
+ cache_dataset=True,
790
+ cache_path=f"{local_ssd}/decoded/fmow-train",
791
+ cache_model_inputs=True,
792
+ model_input_cache_path=f"{local_ssd}/model-inputs/fmow-train-224",
793
+ allow_train_model_input_cache=True,
794
+ metadata_mode="numeric_only",
795
+ )
796
+ ```
797
+
798
+ The base `wilds:fmow` preset has no stochastic per-sample training
799
+ augmentation, so train model-input caching is safe when explicitly opted in. Do
800
+ not use train model-input caching with `wilds:fmow_strong` unless freezing the
801
+ first pass of stochastic augmentation is intentional.
802
+
803
+ ### Applying a Named Preset
804
+
805
+ To use a specific preset for any dataset, pass the preset name as `preset`:
806
+
807
+ ```python
808
+ # Load imagenette with the RSB A3 (light) recipe: 160px training, RandAugment m=6, Mixup α=0.1
809
+ pipeline = get_pipeline(
810
+ dataset="imagenette",
811
+ preset="imagenet_a3", # apply the A3 preset to the imagenette task
812
+ )
813
+
814
+ train_ds, N = load_ds(
815
+ dataset_names_arg=["imagenette"],
816
+ splits_arg={"imagenette": ["train"]},
817
+ dataset_type="train",
818
+ batch_size=128,
819
+ seed=42,
820
+ pipeline=pipeline,
821
+ num_classes=10,
822
+ cache_dataset=False,
823
+ )
824
+ ```
825
+
826
+ ### Overriding Preset Parameters
827
+
828
+ ```python
829
+ pipeline = get_pipeline(
830
+ dataset="imagenet",
831
+ aug_kwargs={"augment_type": "trivial_augment"}, # overrides preset default
832
+ )
833
+ ```
834
+
835
+ ### DINOv2 SSL Pipeline
836
+
837
+ ```python
838
+ pipeline = get_pipeline(
839
+ preset="dinov2",
840
+ pipeline_name="vision/classification",
841
+ )
842
+ ```
843
+
844
+ ______________________________________________________________________
845
+
846
+ ## Development
847
+
848
+ This project uses [devenv](https://devenv.sh/) (Nix-based) with `uv` for Python dependency management.
849
+
850
+ ```bash
851
+ devenv shell # enter the development environment
852
+ direnv allow # approve automatic devenv activation once
853
+ uv sync # install/update dependencies
854
+ uv run pytest # run all tests
855
+ uv run ruff check . # run lint checks
856
+ uv run ruff format --check . # check formatting
857
+ uv run pytest tests/path/to/test_file.py::test_name # run a single test
858
+ ```
859
+
860
+ The project targets Python 3.12 (see `.python-version`). `LD_LIBRARY_PATH` is configured by devenv for native libraries.