cesm_hawc.file_index¶

source

Find CAM history files and read the dates in their names.

CAM history files are named <case>.cam.hN.YYYY-MM.nc (e.g. monthly means) or <case>.cam.hN.YYYY-MM-DD-SSSSS.nc, where SSSSS is the second of the day.

list_files¶

def list_files(directory: str, pattern: str) -> list[str]

source

List the files in a directory that match a glob pattern.

Parameters¶

• directory (str) — Directory to search.

• pattern (str) — Glob pattern, e.g. "*.cam.h0.*.nc".

Returns¶

• list of str — Matching paths, sorted.

Raises¶

• FileNotFoundError — If nothing matches.

filename_date¶

def filename_date(path: str) -> str | None

source

Read the date from a CAM history file name.

Parameters¶

• path (str) — File path; only the file name is used.

Returns¶

• str or None — "YYYY-MM" for *.YYYY-MM.nc names, "YYYY-MM-DD" for *.YYYY-MM-DD-SSSSS.nc names, or None if the name has no date.

filename_time¶

def filename_time(path: str) -> pd.Timestamp | None

source

Choose a representative time for a CAM history file from its name.

Parameters¶

• path (str) — File path; only the file name is used.

Returns¶

• pandas.Timestamp or None — The 15th at 12:00 for *.YYYY-MM.nc names; otherwise the date plus the SSSSS seconds of day (0 if absent). None if the name has no date.

date_in_range¶

def date_in_range(date: str, start: str | None, end: str | None) -> bool

source

Check whether a file date falls within a date range.

Bounds are compared at date’s own precision, so a month is in range if any part of it is.

Parameters¶

• date (str) — "YYYY-MM" or "YYYY-MM-DD", as returned by filename_date().

• start, end (str or None) — Inclusive bounds as "YYYY-MM-DD"; None means unbounded.

Returns¶

• bool — True if date is within [start, end].

index_by_date¶

def index_by_date(directory: str, pattern: str) -> dict[str, str]

source

Index daily history files by calendar date.

Parameters¶

• directory (str) — Directory to search.

• pattern (str) — Glob pattern, e.g. "*.cam.h2.*.nc". Only names ending in YYYY-MM-DD-SSSSS.nc are indexed.

Returns¶

• dict of str to str — {"YYYY-MM-DD": path}.

Raises¶

• FileNotFoundError — If nothing matches pattern.

Notes¶

Keeps one file per date: if a date has several (e.g. 12-hourly output), only the last in sorted order is kept and the rest are dropped without warning. Use index_by_timestamp() for sub-daily output.

index_by_timestamp¶

def index_by_timestamp(directory: str, pattern: str) -> dict[pd.Timestamp, str]

source

Index history files by date and time of day.

Unlike index_by_date(), every file is kept when there are several per day (e.g. ...-00000.nc and ...-43200.nc for 12-hourly output).

Parameters¶

• directory (str) — Directory to search.

• pattern (str) — Glob pattern. Only names ending in YYYY-MM-DD-SSSSS.nc are indexed.

Returns¶

• dict of pandas.Timestamp to str — {date + SSSSS seconds: path}.

Raises¶

• FileNotFoundError — If nothing matches pattern.