mirror of
https://github.com/lynchaos/ashvale-station.git
synced 2026-09-12 12:47:49 +00:00
kemal
49c0aee2e1
The Live tab now carries the observed-and-forecast chart (a superset of the old rolling window, which plotted the same observed series without the prediction) and the precipitation panel. Estimator internals moves to Models, beside the calibration input that sets the coefficient it reports. The seven day outlook moves to History. Verified in Chromium at 1600x900: all four tabs scrollHeight 900 against innerHeight 900, zero clipped elements outside internal scrollers, zero console errors. CONTRIBUTING.md now states plainly that this is a solo project: bug reports welcome, pull requests unlikely to be merged, fork it instead. No other developer was ever named anywhere in the repository.
108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
# Contributing to Ashvale Station
|
|
|
|
Read this first, so nobody wastes an afternoon.
|
|
|
|
**This is a solo project.** It is written and maintained by one person, for one
|
|
weather station, and it is published because the methods may be useful to
|
|
someone else, not because it is looking for a team.
|
|
|
|
**Bug reports are genuinely welcome.** If something crashes, forecasts badly, or
|
|
the documentation is wrong, open an issue. That is useful and I will read it.
|
|
|
|
**Pull requests are unlikely to be merged.** Not from lack of gratitude: this
|
|
codebase carries a lot of hard-won reasoning in its comments and docstrings, and
|
|
reviewing changes to it properly costs more time than I have. If you want it to
|
|
do something different, fork it. Apache 2.0 exists precisely so you can.
|
|
|
|
The rest of this file documents how the project holds itself to a standard. It
|
|
is written for anyone reading the code, including future me.
|
|
|
|
## Ground rules that actually matter
|
|
|
|
**No heavy dependencies.** The whole point is that this runs on a Raspberry Pi
|
|
Zero 2 W with 512 MB of RAM. Pull requests adding PyTorch, TensorFlow, pandas or
|
|
scikit-learn to the core will be declined, however elegant. If a model genuinely
|
|
needs one, make it an optional extra with a numpy fallback.
|
|
|
|
**Claims need numbers.** If you say a change improves forecasting, show the
|
|
output of `scripts/evaluate.py` before and after, on the same data. Skill against
|
|
persistence is the metric that counts. "It looks better" is not evidence.
|
|
|
|
"The same data" means bit-identical, which takes two flags, not one. `--seed`
|
|
alone is not enough: the synthetic history is anchored to wall clock, so the OU
|
|
realisation repeats while the timestamps shift, and that moves solar elevation,
|
|
day of year and the seasonal harmonic. Those feed the temperature and humidity
|
|
models directly, so two same-seed runs give you different data and an
|
|
uninterpretable comparison. Pin both:
|
|
|
|
```bash
|
|
python scripts/simulate.py --days 21 --wipe --seed 11 --end 1767225600
|
|
python scripts/evaluate.py --train-frac 0.6 --hours 100000
|
|
```
|
|
|
|
The wide `--hours` matters: `evaluate.py` looks back from now, and its default
|
|
window is 60 days, so a history pinned to a timestamp further in the past than
|
|
that falls outside it and the script reports "Not enough history".
|
|
|
|
**Uncertainty must stay calibrated.** If you touch the forecasting path, check
|
|
that coverage on the scorecard still sits near the target. A model that gets more
|
|
accurate while its intervals start lying is a regression, not an improvement.
|
|
|
|
**Document how it fails.** Every model module carries a docstring explaining not
|
|
just what the technique is but how it breaks in the field. Keep that up. It is
|
|
the most useful part of this codebase.
|
|
|
|
## Getting set up
|
|
|
|
```bash
|
|
git clone https://github.com/lynchaos/ashvale-station.git
|
|
cd ashvale-station
|
|
python3 -m venv .venv && source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
python scripts/simulate.py --days 21 --wipe # synthetic history
|
|
python scripts/evaluate.py # baseline numbers
|
|
python run.py --no-led # dashboard on :8000
|
|
```
|
|
|
|
No Sense HAT needed. The simulator kicks in automatically and exercises every
|
|
code path.
|
|
|
|
## The bar any change has to clear
|
|
|
|
Whether it is my own commit or a fork of yours, a change to the forecasting
|
|
path is not finished until it can show:
|
|
|
|
- [ ] `python scripts/evaluate.py` runs clean, and you have posted before/after numbers
|
|
- [ ] Those numbers came from a backfill with `--seed` and `--end` both pinned
|
|
- [ ] Coverage on the scorecard is still near target for anything you touched
|
|
- [ ] No new required dependencies
|
|
- [ ] New model code explains its failure mode in the docstring
|
|
- [ ] The dashboard still fits one viewport at 1280x800 if you changed the UI
|
|
|
|
## Roadmap
|
|
|
|
Where this is going, in rough order of value. Listed so a forker knows what is
|
|
already planned rather than as an invitation.
|
|
|
|
- **DS18B20 or BME280 support.** An outdoor sensor removes the single biggest
|
|
limitation in the project. High impact, self-contained.
|
|
- **Tipping-bucket rain gauge on GPIO.** Real precipitation labels would
|
|
transform the precipitation model.
|
|
- **METAR ingestion** from a nearby airfield as a calibration reference.
|
|
- **Tests.** There is a walk-forward backtest but no unit test suite. A pytest
|
|
suite over `physics.py`, `estimation.py` and `models/rls.py` is the main gap.
|
|
|
|
## Reporting bugs
|
|
|
|
Open an issue with your `config.yaml` (redact coordinates if you like), the
|
|
output of `GET /api/status`, and what you expected instead. If it is a
|
|
forecasting problem rather than a crash, the output of `scripts/evaluate.py`
|
|
helps enormously.
|
|
|
|
## Licensing
|
|
|
|
The project is Apache 2.0. Fork it, modify it, ship it, subject to the licence
|
|
terms. In the unlikely event a patch is accepted, it is taken under the same
|
|
terms and you keep the copyright in your own work.
|