API reference#

Loading data#

imdtrack.load(update=False, source='github', url='https://rsmcnewdelhi.imd.gov.in/download.php?path=uploads/best-track/78b4b0_Best_Tracks__Data__1982-2026_.xlsx', path=None, cache_dir=None, force=False)[source]#

Load the best-track record as a BestTracks bundle.

Parameters:

  • update (if True, check the source for a newer copy and re-download when it) – has changed (a cheap conditional GET, so it’s a no-op when current).

  • source (where the data comes from. "github" (default) downloads the) – pre-parsed dataset published in the project’s GitHub repo — no IMD download or Excel parsing on your machine. "imd" fetches and parses the IMD workbook directly (the pipeline’s path; needs the pipeline extra for openpyxl).

  • url (IMD source workbook URL (only used when source="imd").)

  • path (parse this local .xlsx instead of fetching (overrides source).)

  • cache_dir (where to store downloaded files and any parsed cache.)

  • force (force a fresh download even if the cache looks current.)

  • the (Parsed results (source="imd") are cached as parquet keyed by)

  • hash (workbook's content)

  • re-parse. (so only a genuinely new file triggers a)

Return type:

BestTracks

imdtrack.update(**kwargs)[source]#

Convenience wrapper for load(update=True, ...).

Return type:

BestTracks

The BestTracks bundle#

class imdtrack.BestTracks(observations, remarks, storms, sha256=None)[source]#

A parsed snapshot of the IMD best-track record.

Variables:

  • observations (one tidy row per 3-hourly fix (the main table).)

  • remarks (free-text landfall / weakening notes, linked by storm_id.)

  • storms (one summary row per storm.)

  • sha256 (content hash of the workbook these frames came from.)

Parameters:
clean(how='drop', fix_dates=False)[source]#

Return a copy with QC-flagged errors handled (source never altered).

pos_suspect marks fixes whose coordinates imply an impossible jump; date_suspect marks day/month-transposed dates. Both are source data-entry errors.

howhow to treat pos_suspect fixes — "drop" removes them (and

renumbers step); "mask" keeps the rows but nulls lat/lon.

fix_datesif True, correct date_suspect fixes by swapping day and

month, then re-sort each track chronologically.

Parameters:
Return type:

BestTracks

observations: DataFrame#
remarks: DataFrame#
sha256: str | None = None#
storm(key)[source]#

Track for a single storm, by storm_id ("2021-002") or name (case-insensitive, e.g. "tauktae"), sorted by time.

Parameters:

key (str)

Return type:

DataFrame

storms: DataFrame#
to_dataframe()[source]#

Return the tidy observations frame (alias for .observations).

Return type:

DataFrame

to_xarray()[source]#

Return a 2-D (storm, step) xarray.Dataset.

Pipeline (rebuild from the IMD workbook)#

imdtrack.build(data_dir, url='https://rsmcnewdelhi.imd.gov.in/download.php?path=uploads/best-track/78b4b0_Best_Tracks__Data__1982-2026_.xlsx', force=False, cache_dir=None)[source]#

Fetch → (maybe) parse → validate → publish into data_dir.

Returns a BuildResult. Raises validate.ValidationError (or a parse error) without modifying data_dir if the new data is bad.

Parameters:
Return type:

BuildResult

imdtrack.parse_workbook(path)[source]#

Parse a workbook file into {"observations", "remarks", "storms"} frames.

Parameters:

path (str | Path)

Return type:

dict[str, DataFrame]

imdtrack.fetch_workbook(url='https://rsmcnewdelhi.imd.gov.in/download.php?path=uploads/best-track/78b4b0_Best_Tracks__Data__1982-2026_.xlsx', cache_dir=None, force=False, timeout=120.0)[source]#

Ensure a current copy of the workbook is on disk, downloading if needed.

Uses stored ETag / Last-Modified for a conditional request; a 304 Not Modified response (or force=False with no prior download) reuses the cached file. Only the standard library is used, so there is no hard dependency on requests.

Parameters:
Return type:

FetchResult

imdtrack.fetch_data_from_repo(cache_dir=None, update=False, timeout=120.0)[source]#

Download the published parquet dataset from the GitHub repo into the cache.

Returns {"observations": path, "remarks": path, "storms": path, "manifest": path}. With update=False a previously-cached copy is reused offline; update=True does a cheap conditional GET per file.

Parameters:
Return type:

dict