File Naming Conventions

{system}.{date}.{time}.{resolution}.{bundle}.{region}.{lead_time}.{format}

sof-d.20260911.t06z.0p125.basic.global.f006.grib2

cwc.{date}.{time}.0p027.basic.{region}.grib2

cwc.20260911.t11z.0p027.basic.europe.grib2

smi.{date}.t12z.6000m.{product}.{region}.v{version}.{nc|tif}

smi.20260907.t12z.6000m.d-mssm.global.v0201.nc

lightning.{date}.tHHmMM.05km.core.conus-equal-area.f01m00.nc

lightning.20250130.t21m15.05km.core.conus-equal-area.f01m00.nc

{saifs-s2s-regimes|saifs-wx-regimes}.{date}.{time}.{CONUS|EUATL}.daily.csv

saifs-s2s-regimes.20260911.t00z.CONUS.daily.csv

{date}/
  {hour}/
    {filename}

20260911/
  00/
    sof-d.20260911.t00z.0p125.basic.global.f000.grib2
    sof-d.20260911.t00z.0p125.basic.global.f006.grib2
  12/
    sof-d.20260911.t12z.0p125.basic.global.f000.grib2

import re
from dataclasses import dataclass
from datetime import datetime
from typing import Optional

@dataclass
class ForecastFileInfo:
    system: str
    date: datetime
    issuance_hour: int
    resolution: str
    bundle: str
    region: str
    lead: str            # raw lead-time token, e.g. "f006", "f006m00", "D001", "W001"
    lead_hours: Optional[float]
    format: str

PATTERN = re.compile(
    r'^(?P<system>[a-z0-9-]+)\.'
    r'(?P<date>\d{8})\.'
    r't(?P<hour>\d{2})z\.'
    r'(?P<res>\d+p\d+|\d+km|\d+m)\.'
    r'(?P<bundle>[a-z0-9-]+)\.'
    r'(?P<region>[A-Za-z0-9_-]+)\.'
    r'(?P<lead>f\d{3}(?:m\d{2})?|[DW]\d{3})\.'
    r'(?P<fmt>\w+)$'
)

def lead_to_hours(lead):
    """Convert a lead-time token to hours; None for daily/weekly periods."""
    if lead.startswith('f'):
        hours = int(lead[1:4])
        minutes = int(lead[5:7]) if 'm' in lead else 0
        return hours + minutes / 60
    return None  # Dnnn / Wnnn periods

def parse_forecast_filename(filename):
    """Parse a standard forecast filename into components."""
    match = PATTERN.match(filename)
    if not match:
        raise ValueError(f"Could not parse filename: {filename}")

    g = match.groupdict()
    return ForecastFileInfo(
        system=g['system'],
        date=datetime.strptime(g['date'], '%Y%m%d'),
        issuance_hour=int(g['hour']),
        resolution=g['res'],
        bundle=g['bundle'],
        region=g['region'],
        lead=g['lead'],
        lead_hours=lead_to_hours(g['lead']),
        format=g['fmt'],
    )

# Example usage
for filename in [
    "sof-d.20260911.t06z.0p125.basic.global.f006.grib2",
    "srfs.20260911.t06z.03km.core-v2.europe.f006m00.grib2",
    "saifs-s2s.20260911.t00z.0p5.surface.europe.W001.grib2",
]:
    info = parse_forecast_filename(filename)
    print(f"{info.system:10} {info.date:%Y-%m-%d} {info.issuance_hour:02d}Z "
          f"{info.resolution:6} {info.bundle:10} {info.region:10} "
          f"lead={info.lead} ({info.lead_hours} h)")

def filter_by_lead_time(filenames, min_hours=0, max_hours=48):
    """Filter forecast files by lead time range (hour-based files only)."""
    result = []
    for filename in filenames:
        try:
            info = parse_forecast_filename(filename)
        except ValueError:
            continue
        if info.lead_hours is not None and min_hours <= info.lead_hours <= max_hours:
            result.append(filename)
    return result

# Get only 0-24 hour forecasts
short_range = filter_by_lead_time(file_list, max_hours=24)