aisky 0.1.2

aisky 系列子模型的云端预报数据读取与缓存工具

aisky

English | 中文

aisky is a Python package for downloading, caching, and reading cloud-hosted forecast data for the aisky submodel family. Each submodel can have its own cycle times, step rules, variable set, and URL conventions, so aisky exposes a model-client interface.

Submodel Technical References

aisky-aerosol

Paper

Gui, K., Zhang, X., Che, H. et al. Advancing operational global aerosol forecasting with machine learning. Nature 651, 658–665 (2026).

• Link: https://www.nature.com/articles/s41586-026-10234-y

Architecture

aisky-sds (TBD)

Paper

• TBD

Architecture

• TBD

Install

pip install aisky

Quick Start (aisky-aerosol)

from aisky import aisky

client = aisky(model="aisky-aerosol")
print(client.info().to_dict())

da = client.get_forecast(
    init_time="20260101_0130",
    step_hours=3,
    count=8,
    variable="TOTEXTTAU",
)
print(da)

Fetch multiple variables at once (returns an xarray.Dataset):

from aisky import aisky

client = aisky("aisky-aerosol")
ds = client.get_forecast(
    "20260101_0130",
    step_hours=3,
    count=8,
    variable=["TOTEXTTAU", "DUEXTTAU"],
)
print(ds)

List available models

import aisky

print(aisky.available_models())

Inspect model metadata (cycle/variables/rules)

from aisky import aisky

client = aisky("aisky-aerosol")
info = client.info()

print(info.cycle_times)
print(info.variables)

Fetch forecasts

from aisky import aisky

client = aisky("aisky-aerosol")
da = client.get_forecast("20260101_0130", step_hours=3, count=8, variable="TOTEXTTAU")

Cache to a local folder

store_dir creates a subfolder named by init_time (e.g., ./data/20260101_0130/):

from aisky import aisky

client = aisky("aisky-aerosol")
da = client.get_forecast(
    "20260101_0130",
    count=8,
    variable="TOTEXTTAU",
    store_dir="./data",
)

API

aisky(model=...)

Returns a model client with:

• client.info(): submodel metadata (cycle times, variables, rules, defaults)
• client.get_forecast(...): download/cache/read forecast data

client.get_forecast(...)

• init_time: init time ("YYYYMMDD_HHMM", datetime, or pandas.Timestamp)
• step_hours: step size (hours), constrained by the submodel rules (aisky-aerosol: multiple of 3)
• count: number of forecast targets (>= 1; 1 means a single valid time)
• store_dir: optional; if set, files are stored under store_dir/init_time/
• cache_dir: optional; default uses the OS cache directory (Windows: %LOCALAPPDATA%\\aisky\\cache)
• variable: optional; a variable name or a list of variables (aisky-aerosol: must be in client.info().variables)
• engine: xarray.open_dataset engine (default: netcdf4)
• timeout: download timeout (seconds)
• retries: retry attempts
• overwrite: overwrite existing cached files
• return_dataset: return xarray.Dataset directly

More examples: docs/usage.md.

Data Source & URL Template

URL template (the path naming is historical and does not affect the product name):

https://obs.cstcloud.cn/s/ai-gamfs/AI-GAMFS/forecast_data/{init}/AI_GAMFS.{init}+{valid}.V01.nc

Both init and valid use YYYYMMDD_HHMM.

License

MIT License. See LICENSE.