Metadata-Version: 2.4
Name: Alaea
Version: 2.6.7
Summary: Some simple tools by Christmas
Author: Christmas
Author-email: 273519355@qq.com
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: netCDF4
Requires-Dist: cftime
Requires-Dist: xarray
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: colorlog
Requires-Dist: requests
Requires-Dist: scipy
Provides-Extra: gdal
Requires-Dist: GDAL; extra == "gdal"
Provides-Extra: zstd
Requires-Dist: zstandard; extra == "zstd"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: license-expression
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Alaea

## Installation

```shell
pip3 install Alaea
```

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

```shell
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:

```shell
./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.

## 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.

```python
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

```python
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，不等于新雪厚度或地面积雪深度。
