Support regional retrievals and standard plots

AGENTS.md

@@ -20,6 +20,9 @@ The Python distribution name is `robert-exoplanets`; avoid introducing packaging
   explicit commands such as `conda run -n robert-exoplanets python ...` and
   `conda run -n robert-exoplanets python -m pytest ...`; do not rely on the
   currently activated shell environment.
+- Always use Git over SSH for GitHub operations, with remotes such as
+  `git@github.com:owner/repository.git`. Do not require or use the GitHub CLI
+  (`gh`); create commits locally and fetch or push them through the SSH remote.
 - Keep physics-facing APIs explicit and typed so later scientific implementations can replace stubs without changing user-facing examples.
 - Prefer small, well-tested modules over broad framework code.
 - Do not add numerical approximations that look like real retrieval physics unless they are clearly labeled as placeholders.

configurations/README.md

@@ -32,7 +32,8 @@ same prior in every sampler variant.
 
 The WASP-69b cloud-free native-mode and fixed-catalogue Mie cases also ship as
 an inference benchmark matrix. Each file extends the corresponding science
-configuration, so only the inference engine and run/output identity change:
+configuration, so only the inference engine and run identity change. Writable
+directories are local defaults beside each run's `configuration.yaml`:
 
 | Workflow | Cloud-free YAML | Mie-catalogue YAML |
 | --- | --- | --- |
@@ -68,5 +69,6 @@ calibration-sensitivity test.
 
 For new projects, start from `TEMPLATE_all_supported_options.yaml`. It groups
 the editable inputs into system, data, atmosphere, cloud, opacity/RT, priors,
-sampler, and housekeeping sections. The active block is a valid cloud-free retrieval;
-commented alternatives show the currently supported optional modes and priors.
+sampler, plotting, and one top-level paths section. The active block is a valid
+cloud-free retrieval; commented alternatives show the supported one-region,
+diluted, two-region, chemistry, cloud, and prior modes.

configurations/TEMPLATE_all_supported_options.yaml

@@ -8,6 +8,19 @@
 
 schema_version: 2
 
+# =============================================================================
+# PATHS: ALL MACHINE-SPECIFIC LOCATIONS LIVE HERE.
+# Relative paths resolve beside this YAML. ROBERT creates ./outputs, ./scratch,
+# and ./opacity_cache automatically, so they do not need to be configured.
+# Environment variables such as ${ROBERT_DATA_ROOT} are supported.
+# =============================================================================
+paths:
+  project_directory: .
+  observations_directory: /path/to/observations
+  fastchem_directory: /path/to/fastchem
+  k_table_directory: /path/to/opacity
+  optical_constants_directory: /path/to/optical_constants
+
 # =============================================================================
 # RUN IDENTITY
 # =============================================================================
@@ -62,7 +75,7 @@ observations:
     #   uncertainty_scale: 1.15          # Fixed 15% inflation.
     #   uncertainty_scale_parameter: miri_error_scale
     #   jitter_parameter: miri_jitter
-  # path is populated from housekeeping.observations_directory.
+  # path is populated from paths.observations_directory.
 
 # =============================================================================
 # ATMOSPHERE PROPERTIES
@@ -106,7 +119,7 @@ atmosphere:
     model: fastchem_equilibrium
     metallicity_parameter: metallicity
     carbon_to_oxygen_parameter: CtoO
-    # fastchem_path is populated from housekeeping.fastchem_directory.
+    # fastchem_path is populated from paths.fastchem_directory.
     species:
       - {label: H2O, fastchem_name: H2O1}
       - {label: CO2, fastchem_name: C1O2}
@@ -165,7 +178,7 @@ clouds:
   # geometric_stddev: 1.0
   # quadrature_points: 1
   # multiple_scattering_backend: sh4
-  # optical_constants_path is populated from housekeeping.optical_constants_directory.
+  # optical_constants_path is populated from paths.optical_constants_directory.
 
   # Shared emission/transmission retrieved refractive-index Mie cloud:
   # model: mie_direct_nk
@@ -177,6 +190,35 @@ clouds:
   # quadrature_points: 1
   # multiple_scattering_backend: sh4
 
+# =============================================================================
+# PROJECTED-DISK EMISSION
+# The top-level atmosphere/clouds define the primary (hot) column. Regional
+# overrides inherit every omitted field. Two-region and dilution modes require
+# their fraction parameter in `parameters` with bounds inside [0, 1].
+# =============================================================================
+disk_emission:
+  model: one_region
+  # Diluted one-column alternative:
+  # model: diluted_one_region
+  # dilution_parameter: dayside_dilution
+  # Two-column alternative ("2tp" is accepted as an alias):
+  # model: two_region
+  # hot_fraction_parameter: hot_area_fraction
+  # hot_region: {}                  # Inherits the top-level atmosphere/clouds.
+  # cold_region:
+  #   atmosphere:
+  #     temperature:
+  #       model: isothermal
+  #       parameter_name: cold_temperature
+  #     chemistry:                  # Omit to share top-level chemistry.
+  #       model: free
+  #       species: [H2O, CO2, CO, CH4, NH3, SO2]
+  #       parameter_names: {H2O: cold_log_H2O, CO2: cold_log_CO2, CO: cold_log_CO, CH4: cold_log_CH4, NH3: cold_log_NH3, SO2: cold_log_SO2}
+  #       background_species: [H2, He]
+  #       background_fractions: [0.8547, 0.1453]
+  #   clouds:
+  #     model: none
+
 # =============================================================================
 # OPACITY AND RADIATIVE TRANSFER
 # =============================================================================
@@ -189,7 +231,7 @@ opacity:
     use_rebin: false
     remove_zeros: true
     g_points: 8               # Used by exomol_cross_section_hdf only.
-  # path and cache_directory are populated from housekeeping.
+  # path is populated from paths.k_table_directory; cache defaults locally.
 
 radiative_transfer:
   model: emission             # Alternative: transmission
@@ -356,6 +398,9 @@ plotting:
   image_format: png              # png, pdf, or svg.
   dpi: 180
   max_posterior_samples: 20000   # Plotting limit; statistics always use all samples.
+  posterior_predictive_samples: 200 # Forward calls for spectral and T-P envelopes.
+  posterior_predictive_seed: 0
+  corner_max_parameters: 20      # Larger states retain marginals/correlation only.
   dataset_colors:                # Optional dataset-name overrides.
     f322w2: "#20639b"
     f444w: "#ef5675"
@@ -369,16 +414,3 @@ plotting:
 
 runtime:
   mpi_processes: auto
-
-# =============================================================================
-# HOUSEKEEPING: ALL MACHINE- AND PROJECT-SPECIFIC PATHS LIVE HERE.
-# Relative paths resolve relative to this YAML file.
-# =============================================================================
-housekeeping:
-  observations_directory: /lustre/dirac3/scratch/dp448/dc-tayl1/ROBERT-code/data/wasp69b_schlawin2024
-  fastchem_directory: /lustre/dirac3/scratch/dp448/dc-tayl1/ROBERT-code/data/chemistry/fastchem
-  k_table_directory: /lustre/dirac3/scratch/dp448/dc-tayl1/ktables_exomol
-  optical_constants_directory: /lustre/dirac3/scratch/dp448/dc-tayl1/ROBERT-code/data/optical_constants/exo_skryer
-  opacity_cache_directory: opacity_cache
-  output_directory: outputs
-  scratch_directory: scratch

configurations/l98_59b_clr_transmission_multinest.yaml

@@ -1,5 +1,9 @@
 schema_version: 2
 
+paths:
+  observations_directory: ../data/observations/l98_59b_bello_arufe2025
+  k_table_directory: /Users/jaketaylor/Dropbox/ktables_exomol
+
 run:
   name: l98-59b-clr-transmission-multinest
   description: >-
@@ -25,7 +29,6 @@ bodies:
 
 observations:
   loader: bello_arufe2025_l9859b
-  path: ../data/observations/l98_59b_bello_arufe2025
   datasets: [nrs1, nrs2]
   verify_checksum: true
   miri_offset_parameter: nrs2_offset
@@ -56,10 +59,8 @@ clouds:
 
 opacity:
   format: exomol_kta
-  path: /Users/jaketaylor/Dropbox/ktables_exomol
   resolution: R1000
   species: [SO2, H2S, CO2]
-  cache_directory: ../examples/outputs/l98_59b_clr_transmission/opacity_cache
   binning:
     num: 100
     use_rebin: false
@@ -102,8 +103,6 @@ sampler:
   seed: 2719
   invalid_loglike_floor: -1.0e100
 
-outputs:
-  directory: ../examples/outputs/l98_59b_clr_transmission
 
 plotting:
   enabled: true
@@ -124,4 +123,3 @@ plotting:
 
 runtime:
   mpi_processes: 3
-  scratch_directory: ../examples/outputs/l98_59b_clr_transmission/scratch

configurations/picaso_jwst_transmission_retrieval_multinest.yaml

@@ -1,5 +1,9 @@
 schema_version: 2
 
+paths:
+  observations_directory: ../examples/outputs/picaso_jwst_transmission_retrieval/picaso_jwst_asimov_observation.npz
+  k_table_directory: ../opacity_data/exomol_xsec
+
 run:
   name: picaso-jwst-transmission-retrieval
   description: >-
@@ -23,7 +27,6 @@ bodies:
 
 observations:
   loader: robert_npz
-  path: ../examples/outputs/picaso_jwst_transmission_retrieval/picaso_jwst_asimov_observation.npz
   datasets: [picaso_asimov]
   verify_checksum: false
   miri_offset_parameter: null
@@ -67,10 +70,8 @@ clouds:
 
 opacity:
   format: exomol_cross_section_hdf
-  path: ../opacity_data/exomol_xsec
   resolution: R100
   species: [H2O, CO, CO2, CH4]
-  cache_directory: ../examples/outputs/picaso_jwst_transmission_retrieval/opacity_cache
   binning:
     num: 100
     use_rebin: false
@@ -141,8 +142,6 @@ sampler:
   show_status: true
   seed: 2718
 
-outputs:
-  directory: ../examples/outputs/picaso_jwst_transmission_retrieval
 
 plotting:
   enabled: true
@@ -166,4 +165,3 @@ plotting:
 
 runtime:
   mpi_processes: 2
-  scratch_directory: ../examples/outputs/picaso_jwst_transmission_retrieval/scratch

configurations/synthetic_six_molecule_cloudy_transmission_injection_recovery_multinest.yaml

@@ -1,5 +1,9 @@
 schema_version: 2
 
+paths:
+  observations_directory: ../examples/outputs/synthetic_six_molecule_cloudy_transmission_injection_recovery/synthetic_transmission_observation.npz
+  k_table_directory: ../opacity_data/exomol_xsec
+
 run:
   name: synthetic-six-molecule-cloudy-transmission-injection-recovery
   description: >-
@@ -21,7 +25,6 @@ bodies:
 
 observations:
   loader: robert_npz
-  path: ../examples/outputs/synthetic_six_molecule_cloudy_transmission_injection_recovery/synthetic_transmission_observation.npz
   datasets: [synthetic_transit]
   verify_checksum: false
   miri_offset_parameter: null
@@ -67,10 +70,8 @@ clouds:
 
 opacity:
   format: exomol_cross_section_hdf
-  path: ../opacity_data/exomol_xsec
   resolution: R100
   species: [H2O, CO, CO2, CH4, NH3, HCN]
-  cache_directory: ../examples/outputs/synthetic_six_molecule_cloudy_transmission_injection_recovery/opacity_cache
   binning:
     num: 100
     use_rebin: false
@@ -149,8 +150,6 @@ sampler:
   show_status: true
   seed: 2717
 
-outputs:
-  directory: ../examples/outputs/synthetic_six_molecule_cloudy_transmission_injection_recovery
 
 plotting:
   enabled: true
@@ -176,4 +175,3 @@ plotting:
 
 runtime:
   mpi_processes: 2
-  scratch_directory: ../examples/outputs/synthetic_six_molecule_cloudy_transmission_injection_recovery/scratch

configurations/synthetic_six_molecule_transmission_injection_recovery_multinest.yaml

@@ -1,5 +1,9 @@
 schema_version: 2
 
+paths:
+  observations_directory: ../examples/outputs/synthetic_six_molecule_transmission_injection_recovery/synthetic_transmission_observation.npz
+  k_table_directory: ../opacity_data/exomol_xsec
+
 run:
   name: synthetic-six-molecule-transmission-injection-recovery
   description: >-
@@ -21,7 +25,6 @@ bodies:
 
 observations:
   loader: robert_npz
-  path: ../examples/outputs/synthetic_six_molecule_transmission_injection_recovery/synthetic_transmission_observation.npz
   datasets: [synthetic_transit]
   verify_checksum: false
   miri_offset_parameter: null
@@ -57,10 +60,8 @@ clouds:
 
 opacity:
   format: exomol_cross_section_hdf
-  path: ../opacity_data/exomol_xsec
   resolution: R100
   species: [H2O, CO, CO2, CH4, NH3, HCN]
-  cache_directory: ../examples/outputs/synthetic_six_molecule_transmission_injection_recovery/opacity_cache
   binning:
     num: 100
     use_rebin: false
@@ -123,8 +124,6 @@ sampler:
   show_status: true
   seed: 2716
 
-outputs:
-  directory: ../examples/outputs/synthetic_six_molecule_transmission_injection_recovery
 
 plotting:
   enabled: true
@@ -146,4 +145,3 @@ plotting:
 
 runtime:
   mpi_processes: 2
-  scratch_directory: ../examples/outputs/synthetic_six_molecule_transmission_injection_recovery/scratch

configurations/synthetic_transmission_injection_recovery_multinest.yaml

@@ -1,5 +1,9 @@
 schema_version: 2
 
+paths:
+  observations_directory: ../examples/outputs/synthetic_transmission_injection_recovery/synthetic_transmission_observation.npz
+  k_table_directory: ../opacity_data/exomol_xsec
+
 run:
   name: synthetic-transmission-injection-recovery
   description: >-
@@ -21,7 +25,6 @@ bodies:
 
 observations:
   loader: robert_npz
-  path: ../examples/outputs/synthetic_transmission_injection_recovery/synthetic_transmission_observation.npz
   datasets: [synthetic_transit]
   verify_checksum: false
   miri_offset_parameter: null
@@ -51,10 +54,8 @@ clouds:
 
 opacity:
   format: exomol_cross_section_hdf
-  path: ../opacity_data/exomol_xsec
   resolution: R100
   species: [H2O]
-  cache_directory: ../examples/outputs/synthetic_transmission_injection_recovery/opacity_cache
   binning:
     num: 100
     use_rebin: false
@@ -97,8 +98,6 @@ sampler:
   show_status: true
   seed: 2715
 
-outputs:
-  directory: ../examples/outputs/synthetic_transmission_injection_recovery
 
 plotting:
   enabled: true
@@ -115,4 +114,3 @@ plotting:
 
 runtime:
   mpi_processes: 2
-  scratch_directory: ../examples/outputs/synthetic_transmission_injection_recovery/scratch