cesm_hawc.orbit_files¶

source

Read observation geometry from HAWC orbit files.

Also converts the simulator’s L1b output to an xarray.Dataset. The expected orbit file contents are described in the documentation’s “Orbit files” page.

load_orbit_files¶

def load_orbit_files(orbit_dir: str, pattern: str = 'orbit_*.nc') -> list[str]

source

List the orbit files in a directory.

Parameters¶

• orbit_dir (str) — Directory to search.

• pattern (str, optional) — Glob pattern. Default "orbit_*.nc".

Returns¶

• list of str — Matching paths, sorted.

Raises¶

• FileNotFoundError — If nothing matches.

orbit_file_start_time¶

def orbit_file_start_time(path: str) -> pd.Timestamp

source

Read an orbit file’s start time.

Parameters¶

• path (str) — Orbit file.

Returns¶

• pandas.Timestamp — The file’s start_time global attribute.

Raises¶

• KeyError — If the file has no start_time attribute.

build_orbit_day_index¶

def build_orbit_day_index(
    orbit_files: list[str],
    epoch: pd.Timestamp,
    cache_path: str | os.PathLike | None = None,
) -> dict[int, list[str]]

source

Group orbit files by day since the orbit epoch.

Parameters¶

• orbit_files (list of str) — Orbit files to index.

• epoch (pandas.Timestamp) — Time origin of the orbit file set; day 0 is epoch’s date.

• cache_path (str or os.PathLike, optional) — JSON file to cache the index in. Reading every file’s start time can take minutes for a large set, so the cached index is reused until a file is added, removed or modified.

Returns¶

• dict of int to list of str — {day: [path, ...]}, where day is the number of days from epoch to each file’s start_time. A day can have several files.

extract_observations¶

def extract_observations(
    orbit_files: list[str],
    sim_date: pd.Timestamp,
    cadence_s: float,
    center_pixel: int,
    epoch: pd.Timestamp,
) -> list[dict]

source

Sample observations from one day’s orbit files onto a model date.

Parameters¶

• orbit_files (list of str) — The orbit files for one orbit day.

• sim_date (pandas.Timestamp) — Model date to place the observations on.

• cadence_s (float) — Spacing between sampled observations [s].

• center_pixel (int) — Across-track pixel used as the tangent point.

• epoch (pandas.Timestamp) — Time origin of the orbit files; their time values are seconds since this date.

Returns¶

• list of dict — One dict per observation with time (pandas.Timestamp on sim_date), lat, lon (tangent point [degrees]), observer_lat, observer_lon [degrees] and observer_alt [m].

Notes¶

Each observation keeps its real time of day and satellite geometry; only its date changes. The starting offset of the sampling is rotated from file to file. Each file is about one orbit of a sun-synchronous satellite, so with the same offset every file would sample nearly the same latitudes.

l1b_image_to_dataset¶

def l1b_image_to_dataset(
    l1b,
    wavelengths_nm,
    true_extinction: dict | None = None,
    alt_grid_m=None,
) -> xr.Dataset

source

Convert simulator L1b output to an xarray.Dataset.

Parameters¶

• l1b (aliprocessing.l1b.data.L1bImage) — The "l1b" product from simulator.run().

• wavelengths_nm (array-like) — The simulated wavelengths [nm].

• true_extinction (dict, optional) — Truth extinction from cesm_hawc.constituents.build_waccm_constituents() with return_extinction=True. Its wavelength-resolved {mode}_extinction_per_m entries are added to the dataset.

• alt_grid_m (array-like, optional) — The model altitude grid [m] that true_extinction is on. Required for true_extinction to be added.

Returns¶

• xarray.Dataset — radiance, radiance_noise, dolp and dolp_noise on (wavelength, altitude_m), with tangent latitude, longitude and solar zenith angle as coordinates along altitude_m and the observation time as the time attribute. With truth extinction, each {mode}_extinction_per_m is added interpolated onto the instrument’s altitude_m grid, and as {mode}_extinction_per_m_atm on the model grid (atm_altitude_m). Datasets from several observations can be joined with xarray.concat.