Metadata-Version: 2.4
Name: Alaea
Version: 2.6.9
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.

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

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

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

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