From 898e25a7d678e7da9b762fbcc75af92b6169d288 Mon Sep 17 00:00:00 2001 From: Baudouin Raoult Date: Thu, 3 Sep 2020 13:10:43 +0100 Subject: [PATCH] Documentation --- climetlab/core/metadata.py | 46 ++++++ climetlab/datasets/hurricane_database.py | 13 +- climetlab/plotting/drivers/magics.py | 7 + docs/_static/irma.svg | 181 +++++++++++++++++++++++ docs/firststeps.rst | 25 ++++ 5 files changed, 270 insertions(+), 2 deletions(-) create mode 100644 climetlab/core/metadata.py create mode 100644 docs/_static/irma.svg diff --git a/climetlab/core/metadata.py b/climetlab/core/metadata.py new file mode 100644 index 00000000..3dd36c5e --- /dev/null +++ b/climetlab/core/metadata.py @@ -0,0 +1,46 @@ +# (C) Copyright 2020 ECMWF. +# +# This software is licensed under the terms of the Apache Licence Version 2.0 +# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. +# In applying this licence, ECMWF does not waive the privileges and immunities +# granted to it by virtue of its status as an intergovernmental organisation +# nor does it submit to any jurisdiction. +# + +import json + + +class Annotation: + def __init__(self, **kwargs): + self._kwargs = kwargs + + def get(self, name): + return self._kwargs.get(name) + + +def annotate(pd, **kargs): + + kargs["climetlab"] = "annotation" + + for i, a in enumerate(pd._metadata): + try: + a = json.loads(a) + if a["climetlab"] == "annotation": + pd._metadata[i] = json.dumps(kargs) + return pd + except Exception: + pass + + pd._metadata.append(json.dumps(kargs)) + return pd + + +def annotation(pd): + for a in pd._metadata: + try: + a = json.loads(a) + if a["climetlab"] == "annotation": + return Annotation(**a) + except Exception: + pass + return Annotation() diff --git a/climetlab/datasets/hurricane_database.py b/climetlab/datasets/hurricane_database.py index 4b686c9c..4c4e1f2e 100644 --- a/climetlab/datasets/hurricane_database.py +++ b/climetlab/datasets/hurricane_database.py @@ -1,3 +1,12 @@ +# (C) Copyright 2020 ECMWF. +# +# This software is licensed under the terms of the Apache Licence Version 2.0 +# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. +# In applying this licence, ECMWF does not waive the privileges and immunities +# granted to it by virtue of its status as an intergovernmental organisation +# nor does it submit to any jurisdiction. +# + # See https://www.aoml.noaa.gov/hrd/hurdat/Data_Storm.html import pandas as pd @@ -5,7 +14,7 @@ from . import Dataset from climetlab.utils import download_and_cache from climetlab.utils.datetime import parse_date - +from climetlab.core.metadata import annotate SIGN = {"N": 1, "W": -1, "E": 1, "S": -1} @@ -112,7 +121,7 @@ def __init__(self, bassin="atlantic", url=None): ) ) - self.cyclones = pd.DataFrame(p) + self.cyclones = annotate(pd.DataFrame(p), style="cyclone-track") def to_pandas(self): return self.cyclones diff --git a/climetlab/plotting/drivers/magics.py b/climetlab/plotting/drivers/magics.py index a7da941e..9c25033f 100644 --- a/climetlab/plotting/drivers/magics.py +++ b/climetlab/plotting/drivers/magics.py @@ -22,6 +22,7 @@ from climetlab.core.caching import temp_file from climetlab.core.ipython import SVG, Image from climetlab.core.data import get_data_entry +from climetlab.core.metadata import annotation LOG = logging.getLogger(__name__) @@ -321,6 +322,12 @@ def plot_pandas(self, frame, latitude: str, longitude: str, variable: str): frame[[latitude, longitude, variable]].to_csv(tmp, header=False, index=False) self.plot_csv(tmp, variable) + print(frame._metadata) + + style = annotation(frame).get("style") + if style is not None: + self.style(style) + def _apply(self, collection, value, action): if value is None: diff --git a/docs/_static/irma.svg b/docs/_static/irma.svg new file mode 100644 index 00000000..9dfd343a --- /dev/null +++ b/docs/_static/irma.svg @@ -0,0 +1,181 @@ + + +Magics plot + + + image/svg+xml + Magics plot + baudouin on Baudouins-iMac-3.local + Thu Sep 3 13:01:24 2020 + en-GB + + Magics 4.4.3 (64 bit) + + Plot of meteorological data + + + + +Coastline + + + + + +Coastline + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +no_name + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Coastline + + + + + + + + + + + + + + + + + +Coastline + + + + + + + + + + + + + diff --git a/docs/firststeps.rst b/docs/firststeps.rst index f96dcd5f..0ca80028 100644 --- a/docs/firststeps.rst +++ b/docs/firststeps.rst @@ -31,6 +31,7 @@ to the severe tropical cyclone Uma_ are extracted and plotted (more on plotting below). +.. _data source example: .. code-block:: python @@ -77,12 +78,36 @@ on plotting below). Datasets ^^^^^^^^ +The following Python code: + .. code-block:: python import climetlab as cml + data = cml.load_dataset("hurricane-database", "atlantic") + print(data.home_page) + +will print: + +.. code-block:: bash + + https://www.aoml.noaa.gov/hrd/hurdat/Data_Storm.html + +then, + +.. code-block:: python + + df = data.to_pandas() + irma = df[(df.name=='irma') & (df.year==2017)] + cml.plot_map(irma) + +will plot: + +.. image:: _static/irma.svg + :width: 100% +Compare that with the `data source example`_. Simple plotting ---------------