From 3f786898899917582e1aacc2fb6668dd8427445f Mon Sep 17 00:00:00 2001 From: helloiamvu Date: Sat, 6 Jun 2026 14:40:41 +0200 Subject: [PATCH] docs(research): clarify research() returns daily rows, not hourly obs (#52) A user asked why research() returns daily means and how to access hourly station observations. Clarify in the Returns section that research() yields one daily settlement-summary row per date (obs_* are window aggregates), not sub-daily rows, and point to weather.obs() and the Sprint 0.5+ raw_metar roadmap. --- packages/core/src/mostlyright/research.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/packages/core/src/mostlyright/research.py b/packages/core/src/mostlyright/research.py index 940622f..e8daad8 100644 --- a/packages/core/src/mostlyright/research.py +++ b/packages/core/src/mostlyright/research.py @@ -1540,8 +1540,16 @@ def research( (all entries are covered). Returns: - DataFrame (or ``list[dict]`` when ``as_dataframe=False``) with one - row per settlement date in ``[from_date, to_date]``. Columns: + DataFrame (or ``list[dict]`` when ``as_dataframe=False``) with **one + row per settlement date** in ``[from_date, to_date]`` — a *daily* + summary, NOT hourly/sub-daily observations (issue #52). Each row's + ``obs_*`` columns are aggregates over that date's settlement window: + ``obs_high_f``/``obs_low_f`` are the window max/min and ``obs_mean_f`` + is the mean of the sub-daily METARs. ``research()`` does not return + raw hourly rows; sub-daily / ``raw_metar`` access is a Sprint 0.5+ + item (raw METARs are preserved internally for the planned re-parse + workflow). For an observation-only daily frame without CLI/forecast + columns, see :func:`mostlyright.weather.obs` (also daily). Columns: ``date`` (index when DataFrame), ``station``, ``cli_high_f``, ``cli_low_f``, ``cli_report_type``, ``obs_high_f``, ``obs_low_f``,