Pipeline

End-to-end DEBRA run, Eqs. 1-22.

End-to-end entry points: one call per algorithm, scene in, fields out.

run_debra() is DEBRA, Eqs. 1-22: regrid ancillary onto the scene grid, derive solar zenith and land mask, then chain background -> cloud mask -> dust tests -> confidence. Enhanced imagery (Eqs. 23-29) is in shachen.imagery.

run_dust_rgb() is the classic Dust RGB baseline, which needs no ancillary data at all but does need to know which sensor it is looking at. Callers reach both through this module rather than the per-equation modules, so adding an algorithm does not change how one is run.

shachen.pipeline.run_debra(scene: Dataset, skin_temperature: DataArray, emissivity: Dataset | None = None, constants: DebraConstants = DebraConstants(cloud_mask=CloudMaskConstants(cm1_cold_offset_k=50.0, cm2=Bounds(min=0.0, max=25.0), cm3=Bounds(min=2.0, max=4.5), cm4=Bounds(min=5.0, max=8.0), r1=Bounds(min=0.0, max=3.5), r2=Bounds(min=-1.0, max=3.0), cm_norm=Bounds(min=0.45, max=0.8)), dust_tests=DustTestConstants(dt1_max_rsw_k=3.5, dt2_max_btd_k=3.0, dt3_shift_land_k=-10.0, dt3_shift_ocean_k=5.0, dt3_depth_k=50.0), confidence=ConfidenceConstants(dt3_weight_trm=0.5, dt3_weight_ngt=0.5, cf_norm=Bounds(min=0.25, max=2.5), blend_exponent=1.5, ngt_trm_zenith_deg=Bounds(min=105.0, max=90.0), trm_day_zenith_deg=Bounds(min=90.0, max=75.0)), imagery=ImageryConstants(bg_blend_zenith_deg=Bounds(min=79.0, max=89.0), bg_blend_exponent=1.5, cf_cap=0.5, blue_dimming=0.1, gun_max=1.2)), *, background: Dataset | None = None) → Dataset[source]

Run DEBRA on one scene; returns CF_comb plus all intermediate fields.

scene is a shachen.io.satellite.load_scene() Dataset (bt_* in K on the 2-km grid, with area and start_time attrs); skin_temperature is MERRA-2 TS (K) on its native lat/lon grid, regridded here via shachen.geo.regrid_latlon(). The visible/NIR reflectance variables are not used here; they feed the enhanced imagery.

Exactly one background source must be given (ValueError otherwise):

  • emissivity: the CAMEL band Dataset (emis_*) on its native lat/lon grid; regridded here, then fed through shachen.background.background_signals() (semianalytic mode);

  • background: a precomputed Dataset already on the scene grid (e.g. shachen.composite.composite_background()) carrying rsw_bg, btd_bg and bt_bg_tir_86/104/123; missing variables or 2-D shapes differing from the scene raise ValueError. Its n_valid is passed through to the output when present.

Returns a Dataset on the scene grid carrying cf_comb, cf_day, cf_trm, cf_ngt, cm_norm_day, cm_norm_ngt, dt1-dt3, rsw_bg, btd_bg, and zenith_deg, with the scene’s area and start_time attrs preserved. Pixels with NaN inputs (off-disk, bad pixels) carry NaN confidence.

shachen.pipeline.run_dust_rgb(scene: Dataset, constants: DustRGBConstants | None = None) → Dataset[source]

Run the classic Dust RGB baseline on one scene.

The counterpart of run_debra() for the recipe in shachen.dustrgb: same scene in, but no ancillary data, no cloud mask and no confidence field — three fixed stretches of bt_tir_86/104/112/123 (11.2 um is the extra band DEBRA itself never reads). A scene loaded with roles=DEBRA_BANDS therefore raises ValueError here.

The stretches are per sensor. Unlike DEBRA, the Dust RGB has no one canonical set of numbers: it was tuned for SEVIRI and then re-tuned for each later imager, because the corresponding channels do not sit at the same wavelengths. With constants=None (the default) the set is chosen from scene.attrs["reader"] through shachen.constants.DUST_RGB_BY_READER — ABI gets the Quick Guide’s adjusted values, AHI the original SEVIRI ones — so the baseline matches that sensor’s operational product. An unknown or absent reader falls back to shachen.constants.DUST_RGB (SEVIRI); pass constants explicitly to pin one set across sensors, e.g. to compare the two.

Returns a Dataset carrying dust_rgb — dims (y, x, gun), floats in [0, 1], ready for shachen.imagery.to_uint8() — with the scene’s area and start_time attrs preserved, so it merges straight into a run_debra() result for side-by-side rendering.