phenodata 0.13.1

致谢

感谢许多德国气象局（DWD）的观测者、全球物候监测计划（GPM）以及幕后工作的人们对记录观测数据并将优秀的 datasets 供社区使用的承诺。你们知道你们是谁。

注释

请注意，phenodata 是 beta 级别的软件，仍在开发中。欢迎各种贡献，以便使其更加稳固。

在 1.0 版本发布之前，可能会出现重大更改，因此建议进行版本锁定，尤其是在将 phenodata 作为库使用时。

输出示例

phenodata 可以以不同的格式生成输出。这是一个reStructuredText 格式的表格。

简介

对于大多数获取任务，您必须选择 DWD 的两种不同数据集之一，即 年度报告 或 即时报告。此外，必须选择数据分区，它可以是 recent 或 historical。

截至 2023 年，目前的“历史”数据集从过去延伸到 2021 年。所有后续观测数据都存储在 recent 数据集分区中。

DWD 以按物种分开的文件发布数据，这意味着每种植物的数据将存储在不同的文件中。默认情况下，phenodata 将获取所有物种（植物）的数据，以便能够对整个数据集进行所有类型的查询。

如果您只对有限种类的物种（植物）感兴趣，可以通过使用filename选项仅选择特定文件进行检索，从而提高数据获取性能。

例如，当使用--filename=Hasel,Schneegloeckchen时，仅检索包含Hasel或Schneegloeckchen的文件名，从而最小化获取所有文件所需的工作量。

安装

要从PyPI安装软件，请调用

pip install 'phenodata[sql]' --upgrade

库的使用

本段代码示例演示了如何在独立程序中将phenodata用作库。有关可立即运行的代码示例，请查阅示例目录。

>>> import pandas as pd
>>> from phenodata.ftp import FTPSession
>>> from phenodata.dwd.cdc import DwdCdcClient
>>> from phenodata.dwd.pheno import DwdPhenoData

>>> cdc_client = DwdCdcClient(ftp=FTPSession())
>>> client = DwdPhenoData(cdc=cdc_client, humanizer=None, dataset="immediate")
>>> options = {
...     # Select data partition.
...     "partition": "recent",
...
...     # Filter by file names and years.
...     "filename": ["Hasel", "Raps", "Mais"],
...     "year": [2018, 2019, 2020],
...
...     # Filter by station identifier.
...     "station-id": [13346]
... }

>>> observations: pd.DataFrame = client.get_observations(options, humanize=False)
>>> observations.info()
[...]
>>> observations
[...]

命令行使用

本节为您介绍如何在命令行中使用phenodata程序。

$ phenodata --help

Usage:
  phenodata info
  phenodata list-species --source=dwd [--format=csv]
  phenodata list-phases --source=dwd [--format=csv]
  phenodata list-stations --source=dwd --dataset=immediate [--all] [--filter=berlin] [--sort=Stationsname] [--format=csv]
  phenodata nearest-station --source=dwd --dataset=immediate --latitude=52.520007 --longitude=13.404954 [--format=csv]
  phenodata nearest-stations --source=dwd --dataset=immediate --latitude=52.520007 --longitude=13.404954 [--all] [--limit=10] [--format=csv]
  phenodata list-quality-levels --source=dwd [--format=csv]
  phenodata list-quality-bytes --source=dwd [--format=csv]
  phenodata list-filenames --source=dwd --dataset=immediate --partition=recent [--filename=Hasel,Schneegloeckchen] [--year=2017]
  phenodata list-urls --source=dwd --dataset=immediate --partition=recent [--filename=Hasel,Schneegloeckchen] [--year=2017]
  phenodata (observations|forecast) --source=dwd --dataset=immediate --partition=recent [--filename=Hasel,Schneegloeckchen] [--station-id=164,717] [--species-id=113,127] [--phase-id=5] [--quality-level=10] [--quality-byte=1,2,3] [--station=berlin,brandenburg] [--species=hazel,snowdrop] [--species-preset=mellifera-de-primary] [--phase=flowering] [--quality=ROUTKLI] [--year=2017] [--forecast-year=2021] [--humanize] [--show-ids] [--language=german] [--long-station] [--sort=Datum] [--sql=sql] [--format=csv] [--verbose]
  phenodata drop-cache --source=dwd
  phenodata --version
  phenodata (-h | --help)

Data acquisition options:
  --source=<source>         Data source. Currently, only "dwd" is a valid identifier.
  --dataset=<dataset>       Data set. Use "immediate" or "annual" for "--source=dwd".
  --partition=<dataset>     Partition. Use "recent" or "historical" for "--source=dwd".
  --filename=<file>         Filter by file names (comma-separated list)

Direct filtering options:
  --year=<year>             Filter by year (comma-separated list)
  --station-id=<station-id> Filter by station identifiers (comma-separated list)
  --species-id=<species-id> Filter by species identifiers (comma-separated list)
  --phase-id=<phase-id>     Filter by phase identifiers (comma-separated list)

Humanized filtering options:
  --station=<station>       Filter by strings from "stations" data (comma-separated list)
  --species=<species>       Filter by strings from "species" data (comma-separated list)
  --phase=<phase>           Filter by strings from "phases" data (comma-separated list)
  --species-preset=<preset> Filter by strings from "species" data (comma-separated list)
                            The preset will get loaded from the "presets.json" file.

Forecasting options:
  --forecast-year=<year>    Use as designated forecast year.

Postprocess filtering options:
  --sql=<sql>               Apply given SQL query before output.

Data output options:
  --format=<format>         Output data in designated format. Choose one of "tabular", "json",
                            "csv", or "string". Use "md" for Markdown output, or "rst" for
                            reStructuredText. With "tabular:foo", it is also possible to specify
                            other tabular output formats.  [default: tabular:psql]
  --sort=<sort>             Sort by given field names. (comma-separated list)
  --humanize                Resolve identifier-based fields to human-readable labels.
  --show-ids                Show identifiers alongside resolved labels, when using "--humanize".
  --language=<language>     Use labels in designated language, when using "--humanize"
                            [default: english].
  --long-station            Use long station name including "Naturraumgruppe" and "Naturraum".
  --limit=<limit>           Limit output of "nearest-stations" to designated number of entries.
                            [default: 10]
  --verbose                 Turn on verbose output.

元数据

显示物种列表，包括它们的德语、英语和拉丁名称

phenodata list-species --source=dwd

显示阶段列表，包括它们的德语和英语名称

phenodata list-phases --source=dwd

所有报告/监测站点的列表

phenodata list-stations --source=dwd --dataset=immediate

带有过滤的站点列表

phenodata list-stations --source=dwd --dataset=annual --filter="Fränkische Alb"

显示给定位置的最近站点

phenodata nearest-station --source=dwd --dataset=immediate \
    --latitude=52.520007 --longitude=13.404954

显示给定位置的20个最近站点

phenodata nearest-stations \
    --source=dwd --dataset=immediate \
    --latitude=52.520007 --longitude=13.404954 --limit=20

年度报告者的最近观测文件名列表

phenodata list-filenames \
    --source=dwd --dataset=annual --partition=recent

与上述相同，但按文件名过滤

phenodata list-filenames \
    --source=dwd --dataset=annual --partition=recent \
    --filename=Hasel,Kornelkirsche,Loewenzahn,Schneegloeckchen

列出完整URL而不是仅文件名

phenodata list-urls \
    --source=dwd --dataset=annual --partition=recent \
    --filename=Hasel,Kornelkirsche,Loewenzahn,Schneegloeckchen

观测

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --filename=Hasel,Schneegloeckchen

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --filename=Hasel,Schneegloeckchen --station-id=7521,7532

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --station-id=7521,7532 --year=2020,2021

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --station-id=7521,7532 --species-id=113,127

phenodata list-quality-bytes --source=dwd
phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --quality-byte=5,6,7,8

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --filename=Hasel,Schneegloeckchen,Apfel,Birne \
    --station-id=12132 \
    --humanize \
    --language=german

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --filename=Hasel,Schneegloeckchen \
    --station=berlin,brandenburg \
    --humanize --sort=Datum

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --station=münchen \
    --species=hazel,snowdrop \
    --year=2022 \
    --humanize --sort=Datum

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --station=münchen \
    --phase=flowering \
    --year=2022 \
    --humanize --sort=Datum

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --station=münchen \
    --phase=flowering \
    --quality="nicht beanstandet" \
    --year=2022 \
    --humanize --sort=Datum

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --station=münchen \
    --phase=flowering \
    --quality=korrigiert \
    --humanize --sort=Datum

Hasel, Schneeglöckchen, Sal-Weide, Löwenzahn, Süßkirsche, Apfel, Winterraps, Robinie, Winter-Linde, Heidekraut

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --phase="beginning of flowering" \
    --year=2021,2022,2023 \
    --station=köln \
    --species-preset=mellifera-de-primary \
    --humanize --language=german --sort=Spezies,Datum

phenodata observations \
    --source=dwd --dataset=annual --partition=recent \
    --year=2019,2020,2021,2022,2023 \
    --species-preset=mellifera-de-primary --phase="beginning of flowering" \
    --humanize --language=german \
    --sql="SELECT * FROM data WHERE Station LIKE '%Berlin%' ORDER BY Datum" \
    --format=md

资源

• 源代码

• 文档

• Python 包索引 (PyPI)

贡献

如果您想贡献，我们将非常欢迎。花些时间四处看看，找到错误、设计问题或拼写错误，然后向我们发送拉取请求或创建一个问题。提前感谢您的努力，作者们真的非常感激任何形式的帮助和反馈。

讨论

关于 phenodata 的开发和应用的讨论正在进行中 Hiveeyes 论坛。享受阅读它们，如果您认为您可以贡献一些东西或分享您用该程序所做的事情，不要犹豫，写一篇文章。

• https://community.hiveeyes.org/t/phanologischer-kalender-fur-trachtpflanzen/664

• https://community.hiveeyes.org/t/phenodata-ein-toolkit-zur-beschaffung-und-verarbeitung-von-open-access-phanologiedaten/2892

• https://community.hiveeyes.org/t/phanologischer-kalender-2020/2893

• https://community.hiveeyes.org/t/klimadatenkalender-zur-anzeige-der-phanologischen-daten-des-deutschen-wetterdienstes/948

• https://community.hiveeyes.org/t/phanologie-und-imkerliche-eingriffe-bei-den-bienen/705

• https://community.hiveeyes.org/t/phenological-calendar-for-france/800

开发

为了在您的工作站上设置开发环境，请参阅 开发沙盒 文档。当您看到软件测试成功时，您应该准备好开始开发了。

代码许可

本项目受 GNU AGPL 许可协议的约束，请参阅 LICENSE。

数据许可

DWD 在德语和英语中提供了有关其数据再利用政策的信息。请参阅相应的免责声明（de，en）和版权信息（de，en）。

免责声明

本项目及其作者与 DWD、GPM、USA-NPN 或任何其他组织没有任何关联。这是一个由社区构思的独立项目，旨在使数据更容易获取，以开放数据和开放科学数据的精神。作者们认为，如果公共数据可以轻松加载到 pandas 数据框和 Xarray 数据集中，世界将变得更好。