Recipe 03
General Feature Extraction
Cosmology, plasma, GW, hydrodynamics.
When to use this
Use this recipe when you need translation- and rotation-invariant, multiscale, deformation-stable features for any tensor-valued scientific data — and you do not want to train a model to produce them. The scattering transform is a fixed, analytic feature extractor: no training, no data-hungry fitting, no hyperparameter search beyond the wavelet bank geometry.
First-order coefficients S₁ recover power-spectrum-like information (second-order statistics). Second-order coefficients S₂ recover bispectrum-like structure — the non-Gaussian information that the power spectrum is blind to and that distinguishes physically different fields with identical two-point functions. This has been validated in weak-lensing cosmology (Cheng & Ménard, 2021), molecule property prediction (Eickenberg et al., 2018), and plasma turbulence.
The engine is designed to be runtime-configurable: pass (dim, group, J, Q, L) as flags and the same binary handles 1-D gravitational-wave strain, 2-D CMB patches, and 3-D density fields. No recompilation, no model retraining, no rebuild per domain.
What it needs
Any tensor data. The engine accepts 1-D arrays, 2-D images, and 3-D volumes from ROOT, HDF5, NumPy, VTK, and FITS sources. Provide the path, the dataset name (for HDF5/ROOT), and the (dim, group) config; the engine handles the rest.
# 1-D: gravitational-wave strain / time series
strain.h5 # dataset "strain", shape (N_segments, T)
# 2-D: weak-lensing convergence maps / CMB patches
kappa_maps.fits # shape (N_patches, 512, 512)
# 2-D: jet images (use hep-tagging recipe for mass decorrelation)
jet_images.h5 # shape (N_events, 64, 64)
# 3-D: density field / plasma simulation / nuclear structure
density.h5 # shape (N_snapshots, 128, 128, 128)
field.vtk # VTK UnstructuredGrid or ImageData
# NumPy arrays — any shape matching dim
data.npy # shape (..., *spatial_dims)How it works
MCP tool call sequence
vikshep/ingest
vikshep/compute_scattering
- dim=1, group=trivial → 1-D Morlet wavelets
- dim=2, group=so2 → oriented 2-D Morlet bank (SE(2))
- dim=3, group=so3 → solid-harmonic wavelets (SO(3))
vikshep/reduce_scattering
mean (spatial average), std (spatial standard deviation, captures texture scale), log_mean (log-space averaging, recommended for scale-spanning data), ratio (S₂/S₁, for dimensionless comparison). Multiple methods can be concatenated by passing a comma-separated list.(export)
What you get
- →features.h5 — feature matrix, shape (N_samples, D_features), with provenance metadata
- →provenance.json — { dim, group, J, Q, L, reduction, engine_version, source_oid_hash }
- →feature_oids.txt — SHA3-256 OIDs of intermediate tensors (reusable without recompute)
- →coefficient_shapes.json — shape and dtype of each intermediate coefficient tensor
Configure it
| param | default | description |
|---|---|---|
| dim | 2 | Spatial dimensionality of the input tensor |
| group | so2 | so2 for 2-D roto-translation; so3 for 3-D rotation; trivial for 1-D |
| J | 4–8 | Scales. GW strain: J=8. Lensing maps: J=6. Density fields: J=4 |
| Q | 1–8 | Voices per octave. Q=8 for fine-grained spectral resolution (GW, audio) |
| L | 8 | Orientations (ignored for dim=1 and group=trivial) |
| L_max | 3 | Max spherical-harmonic order ℓ for SO(3). L_max=2 captures most non-Gaussianity |
| reduction | log_mean | Feature reduction method |
| order | 2 | Maximum scattering order. order=2 for most applications |
| normalise | true | Normalise input to unit variance before scattering |
| output_format | hdf5 | Output format: hdf5, numpy, or oid_only |
Run it — CLI
# Weak-lensing maps
bun run main.ts process \
--input kappa_maps.fits \
--recipe feature-extract \
--dim 2 --group so2 --J 6 --L 8 \
--output results/lensing-features/
# 3-D density field
bun run main.ts process \
--input density.h5 --dataset density \
--recipe feature-extract \
--dim 3 --group so3 --J 4 --L-max 3 \
--output results/density-features/
# Gravitational-wave strain
bun run main.ts process \
--input strain.h5 --dataset strain \
--recipe feature-extract \
--dim 1 --group trivial --J 8 --Q 8 \
--output results/gw-features/Run it — Dashboard
⬜
Dashboard screenshot — coming in Pilot
The dashboard shows per-scale energy profiles (S₁ per j) and cross-scale correlation heatmaps (S₂ as a j₁×j₂ grid) for a sample of the input data. Useful for inspecting which scales carry the most discriminating information before running a downstream classifier or clustering pipeline. Available in the Pilot release.
Run on your own data