statistics-and-extension
Use Earth2Studio statistics, metrics, perturbations, and component protocols to build and validate safe custom inference extensions.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- statistics-and-extension
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Use Earth2Studio statistics, metrics, perturbations, and component protocols to build and validate safe custom inference extensions.
- disable-model-invocation
- true
02 资源文件 5
- 参考文档references/extension-reference.md8.9 KB
- 参考文档references/statistics-reference.md7.2 KB
- 参考文档references/testing-reference.md6.6 KB
- 参考文档references/troubleshooting.md6.7 KB
- 脚本scripts/contract_smoke.py1.7 KB
03 SKILL.md 正文
Statistics and extension
Use this sub-skill when a request needs a reduction or verification metric, a custom prognostic/diagnostic/data source/assimilation/perturbation component, or a small workflow that composes those contracts. It targets Earth2Studio 0.18.0a0 public APIs and Python 3.11–3.14. It does not enumerate every model, data source, backend, or optional extra.
Route the request
- Reduction: one input, named
reduction_dimensions; useStatistic. - Verification: forecast
xplus truthy; useMetricand validate the non-ensemble axes before arithmetic. - Derived physical field: use a diagnostic, not a statistic.
- Time stepping: implement a prognostic and its initial-condition-first iterator.
- Data access: implement the matching array or DataFrame source protocol; add a lexicon only when source keys need translation.
- Observation update: implement the DA protocol with explicit schemas.
- Ensemble initial-state change: implement a
Perturbation; it receives and returns a tensor/coordinate pair.
Read the focused contracts before editing:
- Statistics and metrics
- Component extension contracts
- Testing and validation
- Failure recovery
- Offline contract smoke check
Non-negotiable coordinate contract
Treat a CoordSystem as an ordered mapping whose values describe tensor axes in
exactly the same order. batch is the first dynamic model axis when using
batch_coords()/batch_func(). Common public model axes are time,
lead_time, variable, lat, and lon; a prognostic has lead_time, while a
single-step diagnostic normally does not. Do not silently reorder axes to make a
broadcast work.
For every custom component:
- Define
input_coords()with fresh arrays and explicit Earth2Studio variable names, physical units, and latitude/longitude conventions. - Validate required dimension positions with
handshake_dimand required values withhandshake_coords(or a deliberate equivalent for tabular schemas). - Build
output_coordsfrom a copy, removing only reduced dimensions or changing only the documented output fields. Every returned tensor axis needs a matching coordinate variable of the same length. - Keep data in physical units at component boundaries. Normalize only inside a component and undo that normalization before returning.
- Test both a valid tiny tensor and a malformed coordinate mapping. Coordinate shape equality alone is not enough when semantic axis order differs.
Minimal implementation loop
- Write the input/output contract, axis order, variable vocabulary, units, optional dependencies, device behavior, statefulness, and whether network or checkpoints are required. Keep network/download actions out of smoke checks.
- Select the smallest protocol. A statistic only removes dimensions; a
diagnostic may add or transform variables; a prognostic must advance
lead_time; a source must return xarray or DataFrame data with the required metadata; DA may return multiple state/observation outputs. - Implement the protocol and coordinate validation before the numerical method.
Use
@batch_coords()and@batch_func()for ordinary tensor model patterns, and use inference mode for inference-only perturbations/forwards. - Compose through the verified workflow signatures. Use
run.deterministic(time, nsteps, prognostic, data, io, output_coords=..., device=..., verbose=..., checkpoint=...),run.diagnostic(..., diagnostic, data, io, ...), orrun.ensemble(..., nensemble, ..., perturbation, batch_size=..., ...). - Validate output coordinates and tensor shapes at every boundary. For metrics, compare forecast and truth axes by name and coordinate values before calling a built-in reduction; an accidental same-shape subtraction can still be wrong.
- Run the offline smoke check, focused unit tests, then applicable native tests or examples. Report skipped optional-backend/network checks rather than claiming support for them.
Common statistical recipes
import torch
from earth2studio.statistics import lat_weight, mean, rmse
weights = lat_weight(torch.as_tensor(latitudes))
area_mean = mean(["lat"], weights=weights)
score = rmse(["lat", "lon"], weights=grid_weights,
ensemble_dimension="ensemble")
mean, variance, and std can maintain state with batch_update=True.
Metrics such as RMSE/MAE can reduce an ensemble mean when
ensemble_dimension is supplied. CRPS, rank histograms, and energy score expect
an ensemble axis in forecast x and no such axis in truth y. Use the exact
weight dimensionality and output-coordinate rules in the statistics reference.
Safe validation commands
From any directory, run the bundled checker by its installed skill path:
uv run python <skill-root>/scripts/contract_smoke.py --help
uv run python <skill-root>/scripts/contract_smoke.py --case all
When developing a custom component in your own project, run that project's focused tests in its managed environment after the bundled contract smoke. A missing optional Earth2Studio group is a limitation to report, not a reason to install an unbounded dependency set. See the testing reference for the local fixture expectations; the original repository's native test paths are review evidence, not runtime dependencies.
Scope boundaries and handoff
This sub-skill covers component implementation, statistics/metric axes and
weights, lexicon/time-tolerance conventions, focused tests, and safe local
validation. It intentionally excludes release/CI operations, package-wide
maintainer workflows, serving-client construction, exhaustive catalogues, and
remote data/model downloads. Preserve those limits in the downstream handoff.
Record native candidates and the two difficult synthetic cases: a diagnostic
whose returned coordinate mapping omits its output variable, and an ensemble
metric whose truth axes are reordered but retain a broadcastable shape.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).