Alaea

Installation

pip3 install Alaea

KML 转 Shapefile 是可选功能，需要 GDAL：

pip3 install 'Alaea[gdal]'

Release

Direct execution cleans old artifacts, builds the package, uploads it with Twine, and cleans the artifacts after a successful upload:

./run_twine.py

Use --repository NAME to select a configured Twine repository. A failed build does not attempt upload; a failed upload retains the new archives for diagnosis and retry. Directly rerunning the script skips files already present on PyPI and continues uploading the remaining archives.

Coastline boundary filling (2.6.8)

Alaea.baysalt.erosion_coastline.erosion_fill_dataarray fills persistent missing boundaries in a floating-point xarray DataArray. The last two axes must be latitude and longitude with finite, unique 1-D coordinates; a 3-D array uses its first axis as time. Dimension names may vary.

from Alaea.baysalt.erosion_coastline import erosion_fill_dataarray

filled = erosion_fill_dataarray(wave, _times=1, k=16, judge_num=3)
direction = erosion_fill_dataarray(wave_direction, _times=1, k=16, judge_num=3, is_direction=True)

Only cells missing throughout the supplied time series are candidates. Existing values and transient gaps are preserved, and each frame must meet judge_num valid neighbors. k includes the target itself; _times=0 disables filling. Directions use circular averaging and remain missing when the mean direction is undefined. Distances use the existing planar longitude/latitude metric, without periodic seam wrapping; this is numerical boundary extrapolation, not a physical erosion model.

Dask inputs retain time chunks and fill lazily after the 2-D validity mask is computed; each spatial grid is rechunked as a whole. Callers can share weight_cache={} within one batch of variables. Cache keys include the coordinates, mask and parameters, and the caller releases the cache at the end of the batch. No global cache or new dependency is added.

To apply one set of significant-wave-height boundary indices to wind sea, swell, directions and periods, pass the same 2-D reference and batch cache:

import numpy as np
import xarray as xr

reference = xr.where(np.isfinite(swh).any("time"), 1.0, np.nan).compute()
weights = {}
filled_height = erosion_fill_dataarray(swh, 1, 16, 3, reference=reference, weight_cache=weights)
filled_swell = erosion_fill_dataarray(swell, 1, 16, 3, reference=reference, weight_cache=weights)

The reference must have exactly the same spatial dimensions and coordinates. Its finite cells define the existing domain; only its missing boundary cells can become targets. Component-only holes within the valid reference domain are preserved. Every field keeps existing valid values, checks its own donor count and uses its own donor values; directions still require circular means. Providing a reference does not replace missing component values with total wave-height values. Omitting it preserves the field-specific default above.

For NumPy or masked arrays, erosion_via_id(weights, values, is_direction=True, min_valid=3) exposes the same circular mean and per-frame threshold. Omitting the new options preserves existing behavior.

These APIs require Alaea 2.6.8 or newer. Earlier versions do not include erosion_fill_dataarray or the new optional direction/threshold arguments. Update downstream dependency constraints and lock files when upgrading.

Standard atmosphere datasets

xr_atmos_dataset builds any supported combination of wind, 2 metre air temperature, per-period precipitation, mean sea-level pressure, visibility, entire-atmosphere total cloud cover, hourly sunshine duration, 2 metre relative humidity, surface wind gust, 2 metre dew point temperature, and 2 metre apparent temperature. The single-element xr_wind_dataset, xr_air_temperature_dataset, xr_precipitation_dataset, and xr_slp_dataset interfaces use the same metadata and encoding path. Integer packing is enabled by default and can be disabled with _COMPRESS=False when a caller needs to apply it after merging. _TIME_type="str" writes a NetCDF string variable, while "char" writes a fixed character matrix with a DateStr dimension. write_netcdf uses zlib by default; write_netcdf(ds, path, compression="zstd") selects standard HDF5 Zstd filter 32015 with byte shuffle and fails clearly when its reader/writer plugin is unavailable.

run_storage_fallback executes an explicit storage method or an ordered AUTO method list. Applications provide their own operations and recoverable error boundary, so input staging and output publication can share fallback policy without sharing incompatible lifecycle code.

open_netcdf_input adds a shared single-file NetCDF reader for direct, local SSD, memory, named-file, and Linux O_TMPFILE modes. For xarray.open_mfdataset, stage_netcdf_inputs preserves input order while copying through a bounded worker pool and removes only its own staged files when the context exits.

Unified spatial interpolation

s2s, g2s, s2g, and g2g use the same argument order. s means scattered points and g means a grid. Grid coordinates may be one-dimensional longitude/latitude axes or matching two-dimensional coordinate arrays.

import numpy as np
from Alaea.exutils import g2s, s2g

lon = np.array([120.0, 121.0])
lat = np.array([30.0, 31.0])
value = np.array([[1.0, 2.0], [3.0, 4.0]])

point_value = g2s(lon, lat, value, 120.5, 30.5)

station_lon = np.array([120.0, 121.0, 120.0, 121.0])
station_lat = np.array([30.0, 30.0, 31.0, 31.0])
station_value = np.array([1.0, 2.0, 3.0, 4.0])
grid_value = s2g(station_lon, station_lat, station_value, lon, lat)

All four functions accept method="linear", method="nearest", method="cubic", or method="idw". IDW also accepts neighbors (default 8) and power (default 2). Data may have leading dimensions such as (time, lat, lon) or (time, point); these dimensions are preserved in the result.

Coastline filling

from Alaea.baysalt.erosion_coastline import erosion_cal_id, erosion_via_id

weight = erosion_cal_id(lon, lat, value, k=4, judge_num=1, method='np.nan')
filled = erosion_via_id(weight, value)

method may be np.nan, nc.mask, or txt.mask. The input used to calculate weights must be two-dimensional; applying weights supports any data whose last two dimensions are latitude and longitude.

Legacy file-generation helpers remain available from their explicit modules, for example Alaea.exutils.Interp.Interp_g2s.Grid2Sca, but are no longer re-exported from Alaea.exutils; new interpolation code should use the four unified functions above.

天气原始输入 Dataset（2.6.7）

xr_atmos_dataset 可组合构造冻结降水比例、对流降水、降雪水当量、地表/最不稳定气块 CAPE、LI、CIN、边界层高度、冻雨标志和降水类型；没有输入的字段不生成。水当量单位 mm 与雪厚度 cm 明确区分，两个 CAPE 的语义分开命名。

add_atmos_accumulation_precision 复用调用方提供的 GRIB 消息核对单时效累计身份和误差界，不调用外部程序或读取数据文件。resample_atmos_accumulation 将起报累计水当量守恒分配到 UTC 目标区间，缺测不补零，超出误差的回退失败；resample_atmos_category 保持先前瞬时类别，不插值、不外推，只允许按已知源 packing 半步误差恢复整数。分类输出使用恒等整数 packing，避免压缩后产生小数类别。

以上能力只负责科学数组和元数据，不实现天气码算法，不获取在线气象数据。

详细变量属性

22种大气变量均附 description、units_description、temporal_kind、physical_range、missing_value_description 和 time_reference（内容全部为英文，不写入中文或 _zh 属性），保留原CF名称和单位。物理范围使用描述属性，不把物理值域错误写成整数packing空间的 valid_range。

precipitation_type 提供ECMWF/ecCodes码表4.201中0–14的 flag_values/flag_meanings 和英文逐码解释 flag_descriptions；15–191保留、192–254本地使用、255源缺测。0在此解释为无降水；部分其他中心表页将0列为保留，换来源需重新核查。此字段不是WMO天气现象码。

CIN的通用描述明确区分负浮力功与正能量幅度；来源适配器补充实际 sign_convention，不由通用构造器自动改变符号。LI是温差，不能按绝对温标减273.15；降雪水当量是mm，不等于新雪厚度或地面积雪深度。