xagg

一个用于使用像素和多边形之间相对面积重叠的区域加权，将xarray中的网格数据聚合到geopandas中多边形的包。

安装

安装最新版本的xagg最简单的方法是使用conda或mamba。

conda install -c conda-forge xagg==0.3.2.3

# or
mamba install -c conda-forge xagg==0.3.2.3

我们建议在可能的情况下，在新的环境中安装xagg，以确保所有（子）依赖项正确加载。

或者，您可以使用pip，尽管并非所有可选依赖项都可通过pip获得，这意味着某些功能可能不可用。

pip install xagg

文档

请参阅最新的文档：[https://xagg.readthedocs.io/en/latest/index.html](https://xagg.readthedocs.io/en/latest/index.html)

简介

科学通常发生在网格上 - 栅格化的天气产品、插值污染数据、夜间灯光、遥感等，都是由于数据分辨率、处理时间或计算方便的原因，对连续的实世界进行近似。

然而，生物体并不生活在网格上，也很少在网格上玩耍、行动或观察数据。相反，人类倾向于在县、州、镇、Bezirk或城市级别工作；鸟类倾向于沿着复杂的迁徙走廊飞翔；雨水和流域沿着山谷和山脉流动。

因此，当我们需要同时处理网格和地理数据产品时，我们需要使它们匹配的方法。例如，我们可能对某个县的平均温度或流域的平均降雨速率感兴趣。

这就是xagg的用武之地。

xagg 提供了一种易于使用的（仅需两行代码！）标准化方法，用于将栅格数据聚合到多边形中。您只需要将一些网格数据放在 xarray 数据集或数据数组中，以及一些多边形数据放在 geopandas 地理数据框架中。这两者都很容易在 xagg 的目的下使用 - 例如，要使用形状文件，只需打开它即可。

   import xarray as xr
   import geopandas as gpd
    
   # Gridded data file (netcdf/climate data)
   ds = xr.open_dataset('file.nc')

   # Shapefile
   gdf = gpd.open_dataset('file.shp')

xagg 将然后在 ds 中确定地理网格（纬度/经度），为每个像素创建多边形，然后生成形状文件中的每个多边形与每个像素之间的交集。对于形状文件中的每个多边形，计算每个覆盖像素的相对面积 - 例如，如果一个多边形（比如美国的县）的大小和形状与网格像素相同，但被两个像素平分，则每个像素的权重将为 0.5，而该多边形上栅格变量的值将是两者的平均值。

以下是使用上述加载的文件运行的示例代码

   import xagg as xa

   # Get overlap between pixels and polygons
   weightmap = xa.pixel_overlaps(ds,gdf)

   # Aggregate data in [ds] onto polygons
   aggregated = xa.aggregate(ds,weightmap)

   # aggregated can now be converted into an xarray dataset (using aggregated.to_dataset()), 
   # or a geopandas geodataframe (using aggregated.to_geodataframe() or aggregated.to_dataframe()
   # for a pure pandas result), or directly exported to netcdf, csv, or shp files using
   # aggregated.to_csv()/.to_netcdf()/.to_shp()

研究人员通常需要根据数据与多边形的相对面积重叠（例如，是否想根据人口或农业密度对像素进行加权）来加权数据。 xagg 在 xagg.pixel_overlaps() 中内置了对添加额外的权重网格（另一个 xarray 数据数组）的支持。

最后，xagg 允许直接将聚合数据导出为几种常用数据格式

• NetCDF
• CSV（用于 STATA、R）
• Shapefile（用于 QGIS，进一步的空间处理）

最好的是，xagg 是灵活的。您的数据集中有多个变量？ xagg 将聚合它们所有，只要它们至少有 lat/lon 维度。您想保留形状文件中的哪些字段？ xagg 会保留所有字段（例如，来自县数据集的 FIPS 代码），直到最终导出。奇怪的维度名称？ xagg 已经过训练，能够识别作者在多年的气候数据处理中遇到的“lat”、“Latitude”、“Y”、“nav_lat”、“Latitude_1”等所有版本的“纬度”；如果需要，这个列表可以很容易地作为一个关键字参数进行扩展。

用例

气候计量经济学

许多气候计量经济学研究在政治或行政级别（例如，县）使用社会数据（死亡率、作物产量等），但气候和天气数据在网格上。通常需要进一步根据人口或农业密度进行加权。

将像素按面积加权到多边形上，可以确保将天气和气候数据聚合到多边形中的稳健方式。考虑一个（有些牵强的）例子：一个行政区域位于相对平坦的低地，但稍微重叠该多边形的像素主要覆盖着完全不同的气候（山地、沙漠等）。使用简单的掩膜将对该像素进行相同的加权，尽管其信息不一定与该区域的气候相关。人口加权也不一定总是足够的；考虑洛杉矶，它有多个显著不同的气候，所有这些气候都具有高密度。

xagg 允许进行简单的人口 和 面积平均，此外还提供了将聚合数据转换为易于在 STATA 或 R 中进一步计算的输出格式的导出函数。

基于 cookiecutter 科学项目模板 的项目。