Various code enhancements following June's REAL meeting

profiles_eval/configs/facility_pairs.json

@@ -0,0 +1,7 @@
+{
+  "sgp": {
+    "C1": {
+      "supplementary_facilities": ["E13"]
+    }
+  }
+}

profiles_eval/configs/hsrl.json

@@ -28,15 +28,15 @@
       "name_in_file": "extinction_aerosol",
       "units": "1/m"
     },
-    "linear_depol_ratio": {
+    "particulate_linear_depol_ratio": {
       "name_in_file": "linear_depol",
       "units": "1"
     },
-    "linear_depol_ratio_1064nm": {
+    "particulate_linear_depol_ratio_1064nm": {
       "name_in_file": "linear_depol_1064",
       "units": "1"
     },
-    "optical_depth": {
+    "particulate_optical_depth": {
       "name_in_file": "od_aerosol",
       "units": "1"
     },

profiles_eval/configs/hsrl5s.json

@@ -0,0 +1,75 @@
+{
+  "instrument_info": {
+    "name": "High spectral resolution lidar (HSRL) 5-second resolution",
+    "type": "lidar",
+    "instrument_class": "hsrl5s",
+    "level": "a1",
+    "requires_corrections": false
+  },
+  "variables": {
+    "time": {
+      "name_in_file": "time",
+      "units": "sec"
+    },
+    "range": {
+      "name_in_file": "range",
+      "units": "m"
+    },
+    "particulate_backscatter": {
+      "name_in_file": "beta_a_backscatter",
+      "units": "1/(m*sr)"
+    },
+    "particulate_backscatter_1064nm": {
+      "name_in_file": "beta_a_1064_backscatter",
+      "units": "1/(m*sr)"
+    },
+    "particulate_extinction": {
+      "name_in_file": "extinction_aerosol",
+      "units": "1/m"
+    },
+    "particulate_linear_depol_ratio": {
+      "name_in_file": "linear_depol",
+      "units": "1"
+    },
+    "particulate_linear_depol_ratio_1064nm": {
+      "name_in_file": "linear_depol_1064",
+      "units": "1"
+    },
+    "particulate_optical_depth": {
+      "name_in_file": "od_aerosol",
+      "units": "1"
+    },
+    "molecular_attenuated_backscatter": {
+      "name_in_file": "atten_beta_r_backscatter",
+      "units": "1/(m*sr)"
+    },
+    "attenuated_backscatter": {
+      "name_in_file": "atten_beta_a_backscatter",
+      "units": "1/(m*sr)"
+    },
+    "attenuated_backscatter_1064nm": {
+      "name_in_file": "atten_beta_a_1064nm_backscatter",
+      "units": "1/(m*sr)"
+    },
+    "particulate_backscatter_std": {
+      "name_in_file": "beta_a_backscatter_std",
+      "units": "1/(m*sr)"
+    },
+    "molecular_signal_to_noise": {
+      "name_in_file": "molecular_signal_to_noise",
+      "units": "1"
+    },
+    "particulate_backscatter_signal_to_noise": {
+      "name_in_file": "particulate_backscatter_signal_to_noise",
+      "units": "1"
+    },
+    "color_ratio": {
+      "name_in_file": "color_ratio",
+      "units": "1"
+    }
+  },
+  "coordinates": {
+    "time": "time",
+    "range": "range"
+  }
+}

profiles_eval/real_prof_init.py

@@ -151,4 +151,72 @@ def find_instrument_type(
                 return cfg_path.stem
         except Exception:
             continue
-    return None
+    return None
+
+
+def load_facility_pairs(config_dir: str = "./configs") -> Dict:
+    """
+    Load the facility-pairing configuration.
+
+    Reads ``facility_pairs.json`` from *config_dir* to determine which
+    (site, facility) combinations have supplementary facilities. Returns
+    an empty dict if the file does not exist.
+
+    Parameters
+    ----------
+    config_dir : str, optional
+        Directory containing JSON configuration files, by default "./configs"
+
+    Returns
+    -------
+    Dict
+        Parsed dictionary with structure::
+
+            {
+              "site_code": {
+                "facility_code": { "supplementary_facilities": ["fac1", "fac2"] }
+              }
+            }
+
+        Returns ``{}`` if facility_pairs.json does not exist.
+    """
+    pairs_file = Path(config_dir) / "facility_pairs.json"
+
+    if not pairs_file.exists():
+        return {}
+
+    try:
+        with open(pairs_file, "r") as f:
+            pairs = json.load(f)
+        return pairs
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON in facility pairs file {pairs_file}: {e}")
+
+
+def get_supplementary_facilities(
+    site: str, facility: str, config_dir: str = "./configs"
+) -> list[str]:
+    """
+    Get the list of supplementary facilities for a given (site, facility) pair.
+
+    Consults the facility-pairing configuration (loaded via
+    :func:`load_facility_pairs`) and returns any supplementary facilities
+    configured for the given primary (site, facility) combination.
+
+    Parameters
+    ----------
+    site : str
+        ARM site code, e.g. ``"sgp"``.
+    facility : str
+        ARM facility code, e.g. ``"C1"``.
+    config_dir : str, optional
+        Directory containing JSON configuration files, by default "./configs"
+
+    Returns
+    -------
+    list[str]
+        List of supplementary facility codes, or empty list if none are
+        defined for this (site, facility) pair.
+    """
+    pairs = load_facility_pairs(config_dir)
+    return pairs.get(site, {}).get(facility, {}).get("supplementary_facilities", [])