diff --git a/docs/examples/ads.ipynb b/docs/examples/ads.ipynb index 3196ed93..d6d74761 100644 --- a/docs/examples/ads.ipynb +++ b/docs/examples/ads.ipynb @@ -3,24 +3,43 @@ { "cell_type": "markdown", "id": "7ec282fb-fdf9-45ba-b3f7-3d46ef212e98", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retrieving CAMS data from the ADS" ] }, { - "cell_type": "markdown", - "id": "52ed2e76-9c54-4a85-b932-6604efc7ae85", - "metadata": {}, + "cell_type": "raw", + "id": "fdb1ce5a-2f75-44e4-85fb-6bd47084cadd", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The \"ads\" data source provides access to the [Copernicus Atmosphere Data Store (ADS)](https://ads.atmosphere.copernicus.eu)." + "The :ref:`ads ` data source provides access to the `Copernicus Atmosphere Data Store (ADS) `_." ] }, { "cell_type": "code", "execution_count": 1, "id": "f24509e0-dd8c-4032-9a3c-5a963ad544d9", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data" @@ -29,7 +48,13 @@ { "cell_type": "markdown", "id": "9f4ce2c9-aaa3-4b76-aacb-1f597df3e338", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Getting GRIB data" ] @@ -55,7 +80,13 @@ "cell_type": "code", "execution_count": 3, "id": "09210614-fad6-46cf-915d-aae4a592d2d5", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -211,7 +242,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/bufr_synop.ipynb b/docs/examples/bufr_synop.ipynb index 07476aa1..5037695c 100644 --- a/docs/examples/bufr_synop.ipynb +++ b/docs/examples/bufr_synop.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "102b1cf9-33a5-4310-af4d-bcd17d598d29", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using BUFR SYNOP data" ] @@ -60,18 +66,31 @@ ] }, { - "cell_type": "markdown", - "id": "06d99f09-8d9d-4677-8aec-275787162a27", - "metadata": {}, + "cell_type": "raw", + "id": "a1f9fd95-d020-4941-b616-f01da9177b4e", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We use ls() to see metadata from the header section of the BUFR messages: " + "We use :py:meth:`~data.readers.bufr.bufr.BUFRList.ls` to see metadata from the header section of the BUFR messages: " ] }, { "cell_type": "code", "execution_count": 4, "id": "30e7749a-ea8b-43d2-90d2-31907f228513", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -318,11 +337,18 @@ ] }, { - "cell_type": "markdown", - "id": "07ca0ea4-cad9-4973-ac79-681f9140c116", - "metadata": {}, + "cell_type": "raw", + "id": "ab0308f1-a43d-4713-844d-49cbfe03453a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "BUFR data can be extracted into a Pandas dataframe using [to_pandas()](https://earthkit-data.readthedocs.io/en/latest/guide/data_format/bufr.html), which passes all the arguments to the [read_bufr()](https://pdbufr.readthedocs.io/en/latest/read_bufr.html) method from [pdbufr](\"https://github.com/ecmwf/pdbufr\").\n", + "BUFR data can be extracted into a Pandas dataframe using :py:meth:`~data.readers.bufr.bufr.BUFRList.to_pandas`, which passes all the arguments to the `read_bufr() `_ method from :xref:`pdbufr`.\n", "\n", "SYNOP data can be encoded into BUFR in many different ways. For the data we have the location and the 2m temperature can be extracted in the following way into a Pandas dataframe:" ] @@ -331,7 +357,13 @@ "cell_type": "code", "execution_count": 5, "id": "53ac87d6-09b9-46c3-bc54-07fd2a175b05", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -826,9 +858,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -840,7 +872,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/bufr_temp.ipynb b/docs/examples/bufr_temp.ipynb index b1a0f5f3..19b286ca 100644 --- a/docs/examples/bufr_temp.ipynb +++ b/docs/examples/bufr_temp.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "102b1cf9-33a5-4310-af4d-bcd17d598d29", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using BUFR TEMP data" ] @@ -88,18 +94,31 @@ ] }, { - "cell_type": "markdown", - "id": "06d99f09-8d9d-4677-8aec-275787162a27", - "metadata": {}, + "cell_type": "raw", + "id": "a05776c0-b71d-42eb-93d9-443b83342b93", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can call *head()*, *tail()* and *ls()* to see metadata from the header section of the BUFR messages: " + "We can call :py:meth:`~data.readers.bufr.bufr.BUFRList.head`, :py:meth:`~data.readers.bufr.bufr.BUFRList.tail` and :py:meth:`~data.readers.bufr.bufr.BUFRList.ls` to see metadata from the header section of the BUFR messages: " ] }, { "cell_type": "code", "execution_count": 5, "id": "30e7749a-ea8b-43d2-90d2-31907f228513", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -256,18 +275,31 @@ ] }, { - "cell_type": "markdown", - "id": "7331e275-a157-407f-a9a0-5070db261d1d", - "metadata": {}, + "cell_type": "raw", + "id": "2edde77d-4e8e-4fb4-8569-700392310fa7", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can **dump** the contents of each message into a tree view. The dump below tells us that the message represents a given station and contains vertical profiles on a set of pressure levels (see the **data section**)." + "We can :py:meth:`~data.readers.bufr.bufr.BUFRMessage.dump` the contents of each message into a tree view. The dump below tells us that the message represents a given station and contains vertical profiles on a set of pressure levels (see the **data section**)." ] }, { "cell_type": "code", "execution_count": 6, "id": "613f01a9-8d0b-4dba-b74d-643aa40083ad", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -965,11 +997,18 @@ ] }, { - "cell_type": "markdown", - "id": "07ca0ea4-cad9-4973-ac79-681f9140c116", - "metadata": {}, + "cell_type": "raw", + "id": "324fa8d6-4a80-4a3c-98eb-7185c66734e4", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "BUFR data can be extracted into a Pandas dataframe using [to_pandas()](https://earthkit-data.readthedocs.io/en/latest/guide/data_format/bufr.html), which passes all the arguments to the [read_bufr()](https://pdbufr.readthedocs.io/en/latest/read_bufr.html) method from [pdbufr](\"https://github.com/ecmwf/pdbufr\").\n", + "BUFR data can be extracted into a Pandas dataframe using :py:meth:`~data.readers.bufr.bufr.BUFRList.to_pandas`, which passes all the arguments to the `read_bufr() `_ method from :xref:`pdbufr`.\n", "\n", "The following example shows how the get the temperature profile for a given station. Please note that \"WMO_station_id\" and \"data_datetime\" are generated keys and not present in the BUFR messages themselves." ] @@ -978,7 +1017,13 @@ "cell_type": "code", "execution_count": 7, "id": "53ac87d6-09b9-46c3-bc54-07fd2a175b05", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1129,9 +1174,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -1143,7 +1188,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.17" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/cache.ipynb b/docs/examples/cache.ipynb index d6d7aa75..06a0e84b 100644 --- a/docs/examples/cache.ipynb +++ b/docs/examples/cache.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "65c27cc6-55b9-4d36-af83-c35cbd00caf3", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Cache policies" ] @@ -21,19 +27,32 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "17b90c39-c493-4d9a-95ec-fa13740a04ad", - "metadata": {}, + "cell_type": "raw", + "id": "232699ed-fd27-426c-8b6b-93091b72d68d", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "earthkit-data uses a dedicated **directory** to store the results of remote data access and some GRIB/BUFR indexing information. By default this directory is **unmanaged** (its size is not checked/limited) and **no caching** is provided for the files in it, i.e. repeated calls to *from_source()* for remote services and URLSs will download the data again!\n", + "earthkit-data uses a dedicated **directory** to store the results of remote data access and some GRIB/BUFR indexing information. By default this directory is **unmanaged** (its size is not checked/limited) and **no caching** is provided for the files in it, i.e. repeated calls to :func:`from_source` for remote services and URLSs will download the data again!\n", "\n", - "When **caching is enabled** this directory will also serve as a **cache**. It means if we run *from_source()* again with the same arguments it will load the data from the cache instead of downloading it again. Additionally, caching offers **monitoring and disk space management**. When the cache is full, cached data is deleted according to the settings (i.e. oldest data is deleted first). " + "When :ref:`caching ` is **enabled** this directory will also serve as a :ref:`cache `. It means if we run :func:`from_source` again with the same arguments it will load the data from the cache instead of downloading it again. Additionally, caching offers **monitoring and disk space management**. When the cache is full, cached data is deleted according to the settings (i.e. oldest data is deleted first). " ] }, { "cell_type": "markdown", "id": "3d93c85a-3c9b-4496-990d-8612fcb82fcf", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "In the examples below we will change the settings multiple times. First we ensure all the changes are temporary and no settings are saved into the configuration file. We also reset the settings to the defaults." ] @@ -58,19 +77,32 @@ ] }, { - "cell_type": "markdown", - "id": "13d73db7-0943-437e-92fc-a8d26a78b527", - "metadata": {}, + "cell_type": "raw", + "id": "6ff49243-d394-41a9-8351-7575d0574134", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The primary key to control the cache in the settings is **\"cache-policy\"**. The default value is **\"off\"**, which means that no caching is available. \n", + "The primary key to control the cache in the settings is :ref:`cache-policy `. The default value is :ref:`\"off\" `, which means that no caching is available. \n", "\n", - "In this case all files are downloaded into an **unmanaged** temporary directory created by *tempfile.TemporaryDirectory*. Since caching is disabled all calls to *from_source()* for remote services and URLSs will download the data again! This temporary directory will be unique for each earthkit-data session. When the directory object goes out of scope (at the latest on exit) the directory will be **cleaned up**. " + "In this case all files are downloaded into an **unmanaged** temporary directory created by *tempfile.TemporaryDirectory*. Since caching is disabled all calls to :func:`from_source` for remote services and URLSs will download the data again! This temporary directory will be unique for each earthkit-data session. When the directory object goes out of scope (at the latest on exit) the directory will be **cleaned up**. " ] }, { "cell_type": "markdown", "id": "1f070e17-a100-4555-b497-c7439e500822", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "The settings tells us the current cache policy:" ] @@ -97,23 +129,36 @@ ] }, { - "cell_type": "markdown", - "id": "698e893e-3c87-4c84-9183-978192600d59", - "metadata": {}, + "cell_type": "raw", + "id": "2920126e-eab7-407f-a1a7-8c99c0702943", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The path to the temporary directory has to be queried through the cache object:" + "The path to the temporary directory has to be queried through the :ref:`cache object `:" ] }, { "cell_type": "code", "execution_count": 4, "id": "047f85f3-9000-4795-904c-42b88658570c", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { "text/plain": [ - "'/var/folders/ng/g0zkhc2s42xbslpsywwp_26m0000gn/T/tmp28qfqpv7'" + "'/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/tmpuc3s5y8r'" ] }, "execution_count": 4, @@ -126,23 +171,36 @@ ] }, { - "cell_type": "markdown", - "id": "7c550796-ea58-4054-a5a4-737e27568370", - "metadata": {}, + "cell_type": "raw", + "id": "4302a441-afbe-4493-b0c4-2bd605c7fde1", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can specify the parent directory for the temporary directory by using the **\"temporary-directory-root\"** settings. By default it is set to None (no parent directory specified)." + "We can specify the parent directory for the temporary directory by using the :ref:`temporary-directory-root ` settings. By default it is set to None (no parent directory specified)." ] }, { "cell_type": "code", "execution_count": 5, "id": "3ccbf119-b641-4d38-bf3c-79bc35151744", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { "text/plain": [ - "'/var/folders/ng/g0zkhc2s42xbslpsywwp_26m0000gn/T/tmp32lwx5gi'" + "'/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/tmpnjz5cnc_'" ] }, "execution_count": 5, @@ -167,18 +225,31 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "49e4e9a1-6f11-497e-9cd8-ac2a46b42374", - "metadata": {}, + "cell_type": "raw", + "id": "943e6bcc-6110-4930-a346-194a28731123", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When the **cache-policy** is **\"temporary\"** the **cache will be active and located in a managed** temporary directory created by *tempfile.TemporaryDirectory*. This directory will be **unique** for each earthkit-data session. When the directory object goes out of scope (at the latest on exit) the cache is **cleaned up**." + "When the :ref:`cache-policy ` is :ref:`\"temporary\" ` the **cache will be active and located in a managed** temporary directory created by *tempfile.TemporaryDirectory*. This directory will be **unique** for each earthkit-data session. When the directory object goes out of scope (at the latest on exit) the cache is **cleaned up**." ] }, { "cell_type": "code", "execution_count": 6, "id": "36aa1fad-2594-4a43-b115-60ac0e602a9a", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -194,23 +265,36 @@ ] }, { - "cell_type": "markdown", - "id": "f6c9bc20-4d71-469f-a25d-79bbc10f53f6", - "metadata": {}, + "cell_type": "raw", + "id": "808e10da-a8ff-4757-88ce-b408e423cd50", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The path to the cache directory has to be queried through the cache object:" + "The path to the cache directory has to be queried through the :ref:`cache object `:" ] }, { "cell_type": "code", "execution_count": 7, "id": "df3dd753-7f61-40c9-986f-5cfca5e4713e", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { "text/plain": [ - "'/var/folders/ng/g0zkhc2s42xbslpsywwp_26m0000gn/T/tmpvfvcstov'" + "'/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/tmp43s9c97m'" ] }, "execution_count": 7, @@ -224,23 +308,36 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "1c0adeae-ab1f-4c6b-a4ca-ee513410fc62", - "metadata": {}, + "cell_type": "raw", + "id": "cd723cc6-204e-4114-9567-f7f5dd4d169e", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can specify the parent directory for the the temporary cache by using the **\"temporary-cache-directory-root\"** settings. By default it is set to None (no parent directory specified)." + "We can specify the parent directory for the the temporary cache by using the :ref:`temporary-cache-directory-root ` settings. By default it is set to None (no parent directory specified)." ] }, { "cell_type": "code", "execution_count": 8, "id": "7b057350-7fed-4204-b825-e782f93883b6", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { "text/plain": [ - "'~/my_demo_cache/tmp18leb6xd'" + "'~/my_demo_cache/tmp2jeqp8ig'" ] }, "execution_count": 8, @@ -265,11 +362,18 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "adc31ffe-78a7-4f67-b82a-aa3df81a7e1e", - "metadata": {}, + "cell_type": "raw", + "id": "8c9988a4-5760-456b-9b72-d3eecb955d7d", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When the **cache-policy** is **\"user\"** the **cache will be active** and created in a **managed directory** defined by the **user-cache-directory** settings. \n", + "When the :ref:`cache-policy ` is :ref:`\"user\" ` the **cache will be active** and created in a **managed directory** defined by the :ref:`user-cache-directory ` settings. \n", "\n", "The user cache directory is **not cleaned up on exit**. So next time you start earthkit-data it will be there again unless it is deleted manually or it is set in way that on each startup a different path is assigned to it. Also, when you run multiple sessions of earthkit-data under the same user they will share the same cache. " ] @@ -278,7 +382,13 @@ "attachments": {}, "cell_type": "markdown", "id": "da6e1e1c-c248-4301-ab89-fea50b73bf57", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "The settings tells us all the details about the cache policy and location:" ] @@ -287,14 +397,20 @@ "cell_type": "code", "execution_count": 9, "id": "4c2afb82-c630-451f-88e5-f80c8aa404ac", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "user\n", - "/var/folders/ng/g0zkhc2s42xbslpsywwp_26m0000gn/T/earthkit-data-cgr\n" + "/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/earthkit-data-cgr\n" ] } ], @@ -305,23 +421,36 @@ ] }, { - "cell_type": "markdown", - "id": "68e82597-7ef4-40d4-abcb-c3d260a0425e", - "metadata": {}, + "cell_type": "raw", + "id": "743bb32a-f1bf-4b1d-94e9-f8a17516b19a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The path to the current cache directory can also be queried through the **cache** object:" + "The path to the current cache directory can also be queried through the :ref:`cache object `:" ] }, { "cell_type": "code", "execution_count": 10, "id": "44583d41-f1d3-4c28-8af5-90d659cdae31", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { "text/plain": [ - "'/var/folders/ng/g0zkhc2s42xbslpsywwp_26m0000gn/T/earthkit-data-cgr'" + "'/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/earthkit-data-cgr'" ] }, "execution_count": 10, @@ -336,7 +465,13 @@ { "cell_type": "markdown", "id": "f6665b3b-5176-4161-9671-b20eb3bcc483", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "We are free to change the user cache directory to another path:" ] @@ -367,7 +502,13 @@ "cell_type": "code", "execution_count": null, "id": "de64b61b-ba84-4c6d-8801-b6fbd8d782ff", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [] } @@ -388,7 +529,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/cds.ipynb b/docs/examples/cds.ipynb index 2b82c0e1..9966389a 100644 --- a/docs/examples/cds.ipynb +++ b/docs/examples/cds.ipynb @@ -3,24 +3,43 @@ { "cell_type": "markdown", "id": "7ec282fb-fdf9-45ba-b3f7-3d46ef212e98", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retrieving ERA5 data from the CDS" ] }, { - "cell_type": "markdown", - "id": "52ed2e76-9c54-4a85-b932-6604efc7ae85", - "metadata": {}, + "cell_type": "raw", + "id": "589c568f-19c3-4a23-9e7a-37b0220bebfb", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The \"cds\" data source provides access to the [Copernicus Climate Data Store (CDS)](https://cds.climate.copernicus.eu)." + "The :ref:`cds ` data source provides access to the `Copernicus Climate Data Store (CDS) `_." ] }, { "cell_type": "code", "execution_count": 1, "id": "f24509e0-dd8c-4032-9a3c-5a963ad544d9", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data" @@ -197,9 +216,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -211,7 +230,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.18" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/demo_sources_plugin.ipynb b/docs/examples/demo_sources_plugin.ipynb index da3e9ae3..6a01ae1a 100644 --- a/docs/examples/demo_sources_plugin.ipynb +++ b/docs/examples/demo_sources_plugin.ipynb @@ -3,17 +3,30 @@ { "cell_type": "markdown", "id": "845dd7c8-cad8-4920-8e80-4ccb45cc7e3d", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Demo sources plugin" ] }, { - "cell_type": "markdown", - "id": "6567170f-2a48-4e22-81ac-9eacdaf8f8d8", - "metadata": {}, + "cell_type": "raw", + "id": "945e7f45-f523-4f54-983c-14faeb220f5e", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "This example demonstrates the usage of [sources plugins](../plugins/sources_plugin.rst) in earthkit-data.\n", + "This example demonstrates the usage of :ref:`sources plugins ` in earthkit-data.\n", "\n", "We will use the **earthkit-data-demo-source** plugin, which allows accessing data from a SQL database. It has to be installed to make the exercise work. " ] @@ -22,7 +35,13 @@ "cell_type": "code", "execution_count": 1, "id": "648d19f6-5777-4530-b562-d480c7c2f51f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "# !pip install --quiet git+https://github.com/ecmwf/earthkit-data-demo-source" @@ -75,18 +94,31 @@ ] }, { - "cell_type": "markdown", - "id": "a1f125bb-e6b7-4aa7-9d20-1d56561e697f", - "metadata": {}, + "cell_type": "raw", + "id": "a4654539-dc5e-4d0f-a5c6-d74a9408edb3", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The plugin implements a new earthkit-data source called \"demo-source\". We can simply use *earthkit.data.from_source()* to read our database." + "The plugin implements a new earthkit-data source called \"demo-source\". We can simply use :func:`from_source` to read our database." ] }, { "cell_type": "code", "execution_count": 3, "id": "3e6b039f-26d9-4430-b3cb-3ddb0023b2eb", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { diff --git a/docs/examples/ecmwf_open_data.ipynb b/docs/examples/ecmwf_open_data.ipynb index e6fc45c8..01a3ab24 100644 --- a/docs/examples/ecmwf_open_data.ipynb +++ b/docs/examples/ecmwf_open_data.ipynb @@ -3,16 +3,43 @@ { "cell_type": "markdown", "id": "4b884925-f9c8-4f12-a0f5-c5c674437302", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retrieving ECMWF open data" ] }, + { + "cell_type": "raw", + "id": "e32794dd-b06c-4274-8125-e1b00e01245e", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "The :ref:`ecmwf-open-data ` source provides access to the `ECMWF open data `_ ." + ] + }, { "cell_type": "code", "execution_count": 1, "id": "f6e081da-e88b-41d5-a914-8f782d50c44f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data" @@ -205,7 +232,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.9" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/fdb.ipynb b/docs/examples/fdb.ipynb index acda9ae8..0b71df89 100644 --- a/docs/examples/fdb.ipynb +++ b/docs/examples/fdb.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "hourly-multimedia", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retrieving data from FDB" ] @@ -69,34 +75,61 @@ ] }, { - "cell_type": "markdown", - "id": "driving-delivery", - "metadata": {}, + "cell_type": "raw", + "id": "a4ceed12-9fa3-4766-a72c-28b32a1660c1", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can retrieve data from FDB as a stream." + "By default we retrieve data from FDB with :ref:`from_source() ` as a stream." ] }, { "cell_type": "markdown", - "id": "bizarre-threshold", - "metadata": {}, + "id": "a8431339-1814-4f56-a071-84175ddf5775", + "metadata": { + "editable": true, + "raw_mimetype": "", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "#### Stream: iteration with one field at a time in memory" ] }, { - "cell_type": "markdown", - "id": "considered-excellence", - "metadata": {}, + "cell_type": "raw", + "id": "eccee7c9-7769-436a-b764-18045c04d86b", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When we use the default arguments the resulting object can only be used for iteration and only one field is kept in memory at a time. Fields created in the iteration get deleted when going out of scope." + "When we use the default arguments in :ref:`from_source() ` the resulting object can only be used for iteration and only one field is kept in memory at a time. Fields created in the iteration get deleted when going out of scope." ] }, { "cell_type": "code", "execution_count": 3, "id": "signal-rocket", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -157,18 +190,31 @@ ] }, { - "cell_type": "markdown", - "id": "c2c8809e-9d53-4c69-af57-e3617e1df8b8", - "metadata": {}, + "cell_type": "raw", + "id": "1f3f2802-7af9-48da-a964-7769c951ce48", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When we use the [group_by](../guide/sources.rst#fdb) option [from_source()](../guide/sources.rst#fdb) gives us a stream iterator object. Each iteration step results in a Fieldlist object, which is built by consuming GRIB messages from the stream until the values of the metadata keys specified in [group_by](../guide/sources.rst#fdb) change. The generated Fieldlist keeps GRIB messages in memory then gets deleted when going out of scope." + "When we use the :ref:`group_by ` option :ref:`from_source() ` gives us a stream iterator object. Each iteration step results in a Fieldlist object, which is built by consuming GRIB messages from the stream until the values of the metadata keys specified in :ref:`group_by ` change. The generated Fieldlist keeps GRIB messages in memory then gets deleted when going out of scope." ] }, { "cell_type": "code", "execution_count": 5, "id": "574757de-cc05-4d73-b71c-cd49af36f655", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -202,18 +248,31 @@ ] }, { - "cell_type": "markdown", - "id": "standard-soviet", - "metadata": {}, + "cell_type": "raw", + "id": "731f4f11-d050-4754-8862-5ca5b2837934", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can read multiple fields into memory from the stream at a time by using [batch_size](../guide/sources.rst#fdb) in [from_source()](../guide/sources.rst#fdb), Please note that *batch_size* cannot be used together with [group_by](../guide/sources.rst#fdb)." + "We can read multiple fields into memory from the stream at a time by using :ref:`batch_size ` in :ref:`from_source `, Please note that :ref:`batch_size ` cannot be used together with :ref:`group_by `." ] }, { "cell_type": "code", "execution_count": 6, "id": "precise-guyana", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -248,18 +307,31 @@ ] }, { - "cell_type": "markdown", - "id": "personal-sense", - "metadata": {}, + "cell_type": "raw", + "id": "1391881c-3484-405a-ab6f-4ee9d032bc35", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When we use [batch_size](../guide/sources.rst#fdb)=0 all the fields are loaded into memory and the resulting object iswill behave like a FieldList:" + "When we use :ref:`batch_size `\\=0 all the fields are loaded into memory and the resulting object iswill behave like a FieldList:" ] }, { "cell_type": "code", "execution_count": 7, "id": "bizarre-basket", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "ds = earthkit.data.from_source(\"fdb\", request, batch_size=0)" @@ -1017,18 +1089,31 @@ ] }, { - "cell_type": "markdown", - "id": "exact-interstate", - "metadata": {}, + "cell_type": "raw", + "id": "c7d8304a-5103-43a2-84f9-87311c051b12", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can retrieve data from FDB into a file, which is located in the cache: " + "We can retrieve data from FDB into a file, which is located in the :ref:`cache `: " ] }, { "cell_type": "code", "execution_count": 14, "id": "passing-georgia", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "ds = earthkit.data.from_source(\"fdb\", request, stream=False)" @@ -1184,18 +1269,31 @@ ] }, { - "cell_type": "markdown", - "id": "successful-collins", - "metadata": {}, + "cell_type": "raw", + "id": "72daa46e-7aa3-4612-bd46-beb7dc6e0375", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The data is now cached. Subsequent retrievals will used the cached file directly." + "The data is now :ref:`cached `. Subsequent retrievals will used the cached file directly." ] }, { "cell_type": "code", "execution_count": null, "id": "outer-accommodation", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [] } diff --git a/docs/examples/from_object.ipynb b/docs/examples/from_object.ipynb index a9fbe7fa..9f4493ca 100644 --- a/docs/examples/from_object.ipynb +++ b/docs/examples/from_object.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Reading data from objects" ] @@ -753,7 +759,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_fdb_write.ipynb b/docs/examples/grib_fdb_write.ipynb index 5a51b663..b199ed1d 100644 --- a/docs/examples/grib_fdb_write.ipynb +++ b/docs/examples/grib_fdb_write.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "hourly-multimedia", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Writing GRIB data into FDB" ] @@ -259,13 +265,18 @@ ] }, { - "cell_type": "markdown", - "id": "e5c176a1-6dc6-4962-aab7-c6f7f8bbe1c2", + "cell_type": "raw", + "id": "7a0c52e4-7f30-4ce5-9b6c-2106e31e61f7", "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, "tags": [] }, "source": [ - "We test our FDB by retrieving some fields from it." + "We test our FDB by retrieving some fields from it using :ref:`from_source() `." ] }, { @@ -273,6 +284,10 @@ "execution_count": 5, "id": "d9e52ef7-1673-4a04-8ad7-f2fd5d65dbd7", "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, "tags": [] }, "outputs": [ diff --git a/docs/examples/grib_file_pattern.ipynb b/docs/examples/grib_file_pattern.ipynb index d4ec7b16..53249dab 100644 --- a/docs/examples/grib_file_pattern.ipynb +++ b/docs/examples/grib_file_pattern.ipynb @@ -3,24 +3,43 @@ { "cell_type": "markdown", "id": "38237d70-0971-44a3-9cac-fd08071c8af9", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Using file patterns" ] }, { - "cell_type": "markdown", - "id": "23ec7068-19e3-4671-98b9-d9ab45e0413a", - "metadata": {}, + "cell_type": "raw", + "id": "c19279fc-c892-43e8-8022-991c5a1e1a39", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The \"file\" source can also be specified by using patterns. In the example below when pattern \"id\" is substituted it will match two files: test4.grib and test6.grib:" + "The :ref:`file ` source can also be specified by using :ref:`patterns `. In the example below when pattern \"id\" is substituted it will match two files: test4.grib and test6.grib:" ] }, { "cell_type": "code", "execution_count": 1, "id": "d52872d1-8ff8-4f52-9ffc-9b72621a9a67", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -233,16 +252,22 @@ "cell_type": "code", "execution_count": null, "id": "e87ac225-94b1-4d7e-8ed9-b71b301d711c", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -254,7 +279,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_from_stream.ipynb b/docs/examples/grib_from_stream.ipynb index 8543fc31..0d617af1 100644 --- a/docs/examples/grib_from_stream.ipynb +++ b/docs/examples/grib_from_stream.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "recovered-organizer", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Reading GRIB from a stream" ] @@ -20,11 +26,18 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "german-simulation", - "metadata": {}, + "cell_type": "raw", + "id": "2da4f1e8-e4ac-489f-9695-72683c779496", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "earthkit-data can load GRIB data from a **stream**, which can be an FDB stream, a standard Python IO stream or any object implementing the necessary stream methods. \n", + "earthkit-data can :ref:`load GRIB data from a stream `, which can be an FDB stream, a standard Python IO stream or any object implementing the necessary stream methods. \n", "\n", "For simplicity, in this notebook we will use a **file stream** to demonstrate the usage of streams. First, we ensure the example file containing 6 messages is available." ] @@ -33,7 +46,13 @@ "cell_type": "code", "execution_count": 2, "id": "939a3b56-a434-457c-966f-f5b8bb6d74dc", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "earthkit.data.download_example_file(\"test6.grib\")" @@ -66,36 +85,62 @@ ] }, { - "cell_type": "markdown", - "id": "covered-greensboro", - "metadata": {}, + "cell_type": "raw", + "id": "86a95676-ed76-4d6f-a9bd-8ef8c2c9607c", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We load it into earthkit-data by using the default settings ([batch_size](../guide/sources.rst#stream)=1). With this when we iterate through *ds* it will consume one message from the stream at a time:" + "We load it into earthkit-data by using the default settings :ref:`batch_size `\\=1). With this when we iterate through *ds* it will consume one message from the stream at a time:" ] }, { "cell_type": "code", "execution_count": 4, "id": "durable-helicopter", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "ds = earthkit.data.from_source(\"stream\", stream)" ] }, { - "cell_type": "markdown", - "id": "resident-guard", - "metadata": {}, + "cell_type": "raw", + "id": "694df8fb-23a8-46dd-87c4-f9234e14d854", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "At this point nothing is read from the stream. As we progressing with the iteration GribField objects are created then get deleted when going out of scope. As a result, only one GRIB message is kept in memory at a time." + "At this point nothing is read from the stream. As we progressing with the iteration :py:class:`~data.readers.grib.codes.GribField` objects are created then get deleted when going out of scope. As a result, only one GRIB message is kept in memory at a time." ] }, { "cell_type": "code", "execution_count": 5, "id": "animated-prayer", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -143,18 +188,31 @@ ] }, { - "cell_type": "markdown", - "id": "3b7e9e3c-df32-44c6-aa4a-fcd2ff72b3b2", - "metadata": {}, + "cell_type": "raw", + "id": "d970d832-7203-498f-81d6-99434ce42b88", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When we use the [group_by](../guide/sources.rst#stream) option [from_source()](../guide/sources.rst#stream) gives us a stream iterator object. Each iteration step results in a Fieldlist object, which is built by consuming GRIB messages from the stream until the values of the metadata keys specified in [group_by](../guide/sources.rst#stream) change. The generated Fieldlist keeps GRIB messages in memory then gets deleted when going out of scope." + "When we use the :ref:`group_by ` option :ref:`from_source() ` gives us a stream iterator object. Each iteration step results in a :py:class:`FieldList ` object, which is built by consuming GRIB messages from the stream until the values of the metadata keys specified in :ref:`group_by ` change. The generated :py:class:`FieldList ` keeps GRIB messages in memory then gets deleted when going out of scope." ] }, { "cell_type": "code", "execution_count": 7, "id": "8e1be478-6eb6-4732-bb96-9d6fa942c20d", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "stream = open(\"test6.grib\", \"rb\")\n", @@ -217,18 +275,31 @@ ] }, { - "cell_type": "markdown", - "id": "planned-weekly", - "metadata": {}, + "cell_type": "raw", + "id": "fb4528e4-f649-4a5b-92b4-e92e9391851b", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The [batch_size](../guide/sources.rst#stream) option controls how many fields we read from the stream in one go. Please note that [batch_size](../guide/sources.rst#stream) cannot be used together with *group_by*. In this example we create a stream and read 2 fields from it at a time by using [batch_size](../guide/sources.rst#stream)=2 in [from_source()](../guide/sources.rst#stream):" + "The :ref:`batch_size ` option controls how many fields we read from the stream in one go. Please note that :ref:`batch_size ` cannot be used together with *group_by*. In this example we create a stream and read 2 fields from it at a time by using :ref:`batch_size `\\=2 in :ref:`from_source() `:" ] }, { "cell_type": "code", "execution_count": 10, "id": "placed-blues", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "stream = open(\"test6.grib\", \"rb\")\n", @@ -284,18 +355,31 @@ ] }, { - "cell_type": "markdown", - "id": "33798584-845d-4db8-9692-9fb0d5b24eec", - "metadata": {}, + "cell_type": "raw", + "id": "ed0b0e9c-1016-474b-8ea0-c65d864d2427", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "It is possible to set a batch size that is not a factor of the total number fields in the stream. In this case the last batch will simply contain less fields than prescribed by [batch_size](../guide/sources.rst#stream)." + "It is possible to set a batch size that is not a factor of the total number fields in the stream. In this case the last batch will simply contain less fields than prescribed by :ref:`batch_size `." ] }, { "cell_type": "code", "execution_count": 13, "id": "bf94a190-ec0e-4172-8e75-6518e48f50a4", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -332,18 +416,31 @@ ] }, { - "cell_type": "markdown", - "id": "blessed-paintball", - "metadata": {}, + "cell_type": "raw", + "id": "0b9b01c1-b528-42a2-9f1b-ccae28eb65b5", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can also set [batch_size](../guide/sources.rst#stream)=0 in [from_source()](../guide/sources.rst#stream)." + "We can also set :ref:`batch_size `\\=0 in :ref:`from_source() `." ] }, { "cell_type": "code", "execution_count": 14, "id": "simple-london", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "stream = open(\"test6.grib\", \"rb\")\n", diff --git a/docs/examples/grib_indexing.ipynb b/docs/examples/grib_indexing.ipynb index e589e386..cc56ea35 100644 --- a/docs/examples/grib_indexing.ipynb +++ b/docs/examples/grib_indexing.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using GRIB indexing " ] @@ -43,29 +49,55 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Indexing" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can perform indexing on the input GRIB data by using the **indexing** option in *load_source()*. The indexing is performed on first data access using the MARS ecCodes keys. The index-data is stored in a sqlite database, which is located in the earthkit-data cache. Subsequent loading of the same data is very fast because it will use the cached index-data." + "We can perform indexing on the input GRIB data by using the **indexing** option in :ref:`from_source() `. The indexing is performed on first data access using the MARS ecCodes keys. The index-data is stored in a sqlite database, which is located in the earthkit-data cache. Subsequent loading of the same data is very fast because it will use the cached index-data." ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Indexing only works when caching is enabled. We ensure a user cache is used for this example and no settings are saved into the configuration file. " + "Indexing only works when :ref:`caching ` is enabled. We ensure a :ref:`user cache ` is used for this example and no settings are saved into the configuration file. " ] }, { "cell_type": "code", "execution_count": 4, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "from earthkit.data import settings\n", @@ -140,22 +172,41 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Methods using the SQL database" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When calling *sel()*, *isel()* or *order_by()* the metadata is directly read from the index database, so there is no need to load/open any of the GRIB messages." + "When calling :py:meth:`~data.readers.grib.index.GribFieldList.sel`, :py:meth:`~data.readers.grib.index.GribFieldList.isel` or :py:meth:`~data.readers.grib.index.GribFieldList.order_by` the metadata is directly read from the index database, so there is no need to load/open any of the GRIB messages." ] }, { "cell_type": "code", "execution_count": 9, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -236,22 +287,41 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Methods not using the SQL database" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Most of the other methods still need to load/open the GRIB messages to extract the required metadata. Ideally they should all use the index database. " + "Most of the other methods still need to load/open the GRIB messages to extract the required :py:meth:`~data.readers.grib.index.GribFieldList.metadata`. Ideally they should all use the index database. " ] }, { "cell_type": "code", "execution_count": 13, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -293,16 +363,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Selection and sorting arguments can be directly passed to *from_souce()*:" + "Selection and sorting arguments can be directly passed to :ref:`from_source() `:" ] }, { "cell_type": "code", "execution_count": 15, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -556,9 +639,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -570,7 +653,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.18" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_lat_lon_value.ipynb b/docs/examples/grib_lat_lon_value.ipynb index eb79d523..c38ae4a9 100644 --- a/docs/examples/grib_lat_lon_value.ipynb +++ b/docs/examples/grib_lat_lon_value.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "d383b3fe-52c1-4fca-8c02-16dc017d0a6d", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Getting latitudes, longitudes and values from GRIB" ] @@ -28,18 +34,31 @@ ] }, { - "cell_type": "markdown", - "id": "ae4ff8c4-d87c-4d57-83a5-38e1e2545556", - "metadata": {}, + "cell_type": "raw", + "id": "a419d6c2-79e4-48e2-b8e2-bcaf957b30cd", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We will only use the temperature fields, so we extract them from the data." + "We will only use the temperature fields, so we :ref:`read ` the file and extract them with :py:meth:`~data.readers.grib.index.GribFieldList.sel`." ] }, { "cell_type": "code", "execution_count": 2, "id": "8a3afa0b-8701-497e-920c-0d44933679c3", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -194,34 +213,60 @@ ] }, { - "cell_type": "markdown", - "id": "c7ec94f3-4e68-4380-a88d-128b2fb46cd8", - "metadata": {}, + "cell_type": "raw", + "id": "f28bb8e9-3ec9-40a7-b42f-f6b4e6930da8", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The simplest way to access the latitudes, longitudes and values is using the *data()* method. It works both on fields and fieldlists." + "The simplest way to access the latitudes, longitudes and values is using the :py:meth:`~data.core.fieldlist.FieldList.data` method. It works both on :py:meth:`fields ` and :py:meth:`fieldlists `." ] }, { "cell_type": "markdown", "id": "c8c67310-78c7-4dea-be92-2bf51860b2a4", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "#### Fields" ] }, { - "cell_type": "markdown", - "id": "443922d8-a8b4-45b4-8139-2c5fd27370e0", - "metadata": {}, + "cell_type": "raw", + "id": "ca4c158d-bda5-449a-a812-3f598444b222", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*data()* returns the latitude, longitude and values arrays from a field as an ndarray. By default the field's shape is kept." + ":py:meth:`~data.core.fieldlist.Field.data` returns the latitude, longitude and values arrays from a field as an ndarray. By default the field's shape is kept." ] }, { "cell_type": "code", "execution_count": 3, "id": "fbe608e7-1a94-44a1-b0f5-d84adabc370a", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -307,18 +352,31 @@ ] }, { - "cell_type": "markdown", - "id": "a21f46b4-6c79-4306-a005-390ef2a02173", - "metadata": {}, + "cell_type": "raw", + "id": "c6c5f3fe-c602-405c-8eb4-d09c3da44c2b", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*data()* only works on a fieldlist if all the fields have the same grid. The first two elements of the resulting ndarray are the latitude and longitude arrays (shared between fields), while the rest of the elements are the value arrays per field. Since we have six fields in our data the size of the first axis of the resulting ndarray is 2+6=8." + ":py:meth:`~data.core.fieldlist.FieldList.data` only works on a fieldlist if all the fields have the same grid. The first two elements of the resulting ndarray are the latitude and longitude arrays (shared between fields), while the rest of the elements are the value arrays per field. Since we have six fields in our data the size of the first axis of the resulting ndarray is 2+6=8." ] }, { "cell_type": "code", "execution_count": 6, "id": "03c4a09d-ec99-442c-91e3-292d0541c1dd", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -339,7 +397,13 @@ { "cell_type": "markdown", "id": "28912fa6-4471-412c-bcf1-c186212bf092", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "We can get the first latitude as:" ] @@ -463,34 +527,60 @@ ] }, { - "cell_type": "markdown", - "id": "fc4f152e-460e-410c-bbbe-d14f6615325a", - "metadata": {}, + "cell_type": "raw", + "id": "bc08ca27-52e7-46e3-9780-7d2389956b81", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can also get the latitudes, longitudes and values by using the *to_latlon()* and *to_numpy()* methods." + "We can also get the latitudes, longitudes and values by using the :py:meth:`~data.core.fieldlist.FieldList.to_latlon` and :py:meth:`~data.core.fieldlist.FieldList.to_to_numpy()` methods." ] }, { "cell_type": "markdown", "id": "20e7aa47-5882-42de-974a-f20a129c34e5", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "#### Fields" ] }, { - "cell_type": "markdown", - "id": "328bcaae-d50c-4a53-b6f4-1b0f1a92cf9a", - "metadata": {}, + "cell_type": "raw", + "id": "5f169944-0ec0-4206-b572-1b76d304bbe2", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*to_latlon()* returns a dict:" + ":py:meth:`~data.core.fieldlist.Field.to_latlon` returns a dict:" ] }, { "cell_type": "code", "execution_count": 11, "id": "b9af7f2c-f120-4437-b59f-b804ce15e84b", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -508,18 +598,31 @@ ] }, { - "cell_type": "markdown", - "id": "d57d5fd5-2b1c-4d1c-a973-e8aee9d7ee7c", - "metadata": {}, + "cell_type": "raw", + "id": "9c5d0956-cb63-4756-be81-1219ff097ac9", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The field values can be accessed with *to_numpy()*." + "The field values can be accessed with :py:meth:`~data.core.fieldlist.Field.to_numpy`." ] }, { "cell_type": "code", "execution_count": 12, "id": "c0926aa8-7fa4-4bb6-adba-11711bc7e463", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -578,18 +681,31 @@ ] }, { - "cell_type": "markdown", - "id": "392bdc90-0e15-415f-892b-7ebbf86cbc8c", - "metadata": {}, + "cell_type": "raw", + "id": "84f0e9f3-ae1c-4f32-8375-459de36a241f", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*to_latlon()* only works on a fieldlist if all the fields have the same grid. In this case it returns the same dict that we would get for any of the fields:" + ":py:meth:`~data.core.fieldlist.FieldList.to_latlon` only works on a fieldlist if all the fields have the same grid. In this case it returns the same dict that we would get for any of the fields:" ] }, { "cell_type": "code", "execution_count": 14, "id": "dda20d91-1f1b-4ec5-991e-e50b841312ea", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -607,18 +723,31 @@ ] }, { - "cell_type": "markdown", - "id": "1b6b1ab0-c0dc-4ba1-803e-ffc93ffd7879", - "metadata": {}, + "cell_type": "raw", + "id": "6e2f64b5-97f4-45a3-9655-786fb73106bb", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*to_numpy()* only works on a fieldlist if all the fields has the same grid. It returns the array of the field value arrays." + ":py:meth:`~data.core.fieldlist.FieldList.to_numpy` only works on a fieldlist if all the fields has the same grid. It returns the array of the field value arrays." ] }, { "cell_type": "code", "execution_count": 15, "id": "e21d501a-22ef-4e82-a996-261baa2594de", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -755,7 +884,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_metadata.ipynb b/docs/examples/grib_metadata.ipynb index 0fd912c4..9c995dfc 100644 --- a/docs/examples/grib_metadata.ipynb +++ b/docs/examples/grib_metadata.ipynb @@ -2,22 +2,39 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Inspecting GRIB contents" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We load a GRIB file containing 6 messages. First we ensure the example file is avialable." + "We will work with a GRIB file containing 6 messages. First we ensure the example file is available, then read the file with :ref:`from_source() `." ] }, { "cell_type": "code", "execution_count": 1, "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, "tags": [] }, "outputs": [], @@ -29,7 +46,13 @@ { "cell_type": "code", "execution_count": 2, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "fs = earthkit.data.from_source(\"file\", \"test6.grib\")" @@ -37,40 +60,71 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "### Using head, tail and ls()" + "### Using head(), tail() and ls()" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "These functions can take the same set of keyword arguments:\n", + "All these methods (:py:meth:`~data.readers.grib.index.GribFieldList.head`, :py:meth:`~data.readers.grib.index.GribFieldList.tail` and :py:meth:`~data.readers.grib.index.GribFieldList.ls`) take the same set of keyword arguments:\n", + "\n", "- n: number of messages to list\n", "- keys: the metadata keys to dump\n", "- extra_keys: extra keys of top of the default set of keys\n", - "- namespace: the ecCodes GRIB namespace to use" + "- namespace: the :xref:`eccodes_namespace` to use" ] }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "#### head()" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*head()* displays the first 5 messages by default:" + ":py:meth:`~data.readers.grib.index.GribFieldList.head` displays the first 5 messages by default:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, "tags": [] }, "outputs": [ @@ -823,16 +877,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*tail()* displays the last 5 messages by default:" + ":py:meth:`~data.readers.grib.index.GribFieldList.tail` displays the last 5 messages by default:" ] }, { "cell_type": "code", "execution_count": 10, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -970,16 +1037,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "By default *ls()* lists all the fields:" + "By default :py:meth:`~data.readers.grib.index.GribFieldList.ls` lists all the fields:" ] }, { "cell_type": "code", "execution_count": 11, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1315,16 +1395,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can describe the whole object:" + "We can :py:meth:`~data.readers.grib.index.GribFieldList.describe` the whole object:" ] }, { "cell_type": "code", "execution_count": 14, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1423,16 +1516,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can also describe a given parameter (defined by shortName or paramId):" + "We can also :py:meth:`~data.readers.grib.index.GribFieldList.describe` a given parameter (defined by shortName or paramId):" ] }, { "cell_type": "code", "execution_count": 15, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1597,16 +1703,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*metadata()* with positional arguments works for both single and multiple fields. Key type qualifiers are allowed to be used." + ":py:meth:`~data.readers.grib.index.GribFieldList.metadata` with positional arguments works for both for a :py:meth:`field ` and a :py:meth:`fieldlist `. Key type qualifiers are allowed to be used." ] }, { "cell_type": "code", "execution_count": 17, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1714,16 +1833,27 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*dump()* gives a tabbed interface to inspect the various namespaces:" + ":py:meth:`~data.readers.grib.codes.GribField.dump` gives a tabbed interface to inspect the various namespaces:" ] }, { "cell_type": "code", "execution_count": 21, "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, "tags": [] }, "outputs": [ @@ -2238,9 +2368,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy10", + "display_name": "dev_ecc", "language": "python", - "name": "mpy10" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -2252,7 +2382,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_missing.ipynb b/docs/examples/grib_missing.ipynb index 67cb180d..2fe502c1 100644 --- a/docs/examples/grib_missing.ipynb +++ b/docs/examples/grib_missing.ipynb @@ -2,23 +2,42 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## GRIB missing values" ] }, { "attachments": {}, - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We read a GRIB file containing 2 messages with missing values. First we ensure the example file is available." + "We :ref:`read ` a GRIB file containing 2 messages with missing values. First we ensure the example file is available." ] }, { "cell_type": "code", "execution_count": 1, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import numpy as np\n", @@ -200,9 +219,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -214,7 +233,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.17" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_multi.ipynb b/docs/examples/grib_multi.ipynb index 6cb1f3a6..d4ae844f 100644 --- a/docs/examples/grib_multi.ipynb +++ b/docs/examples/grib_multi.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Handling multiple GRIB files" ] @@ -34,15 +40,28 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Multiple GRIB files can be read in various ways:" + "Multiple GRIB files can be :ref:`read ` in various ways:" ] }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Option 1: using wildcards" ] @@ -625,9 +644,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -639,7 +658,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_nearest_gridpoint.ipynb b/docs/examples/grib_nearest_gridpoint.ipynb index 0379caf0..a3140c93 100644 --- a/docs/examples/grib_nearest_gridpoint.ipynb +++ b/docs/examples/grib_nearest_gridpoint.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "570a34d8-7958-4de7-b4b1-76d369ce4146", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### GRIB nearest gridpoint" ] @@ -48,7 +54,13 @@ { "cell_type": "markdown", "id": "159cd5bd-6d6f-4d59-aeb6-c5faaf985cfe", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "We define a reference point and get the index of the nearest gridpoint from the first field." ] @@ -84,7 +96,13 @@ { "cell_type": "markdown", "id": "7c5ee441-7439-42d2-849b-6825d69d36e2", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "With the resulting index we can get the value at the nearest gridpoint." ] @@ -439,7 +457,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_overview.ipynb b/docs/examples/grib_overview.ipynb index e32f6943..c08440ab 100644 --- a/docs/examples/grib_overview.ipynb +++ b/docs/examples/grib_overview.ipynb @@ -2,23 +2,42 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using GRIB data overview" ] }, { "attachments": {}, - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We load a GRIB file containing 6 messages from disk. First we ensure the example file is available." + "We will work with a GRIB file containing 6 messages. First we ensure the example file is available, then read the file with :ref:`from_source() `." ] }, { "cell_type": "code", "execution_count": 1, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data\n", @@ -28,7 +47,13 @@ { "cell_type": "code", "execution_count": 2, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "ds = earthkit.data.from_source(\"file\", \"test6.grib\")" @@ -49,16 +74,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "A GRIB data object consists of GribFields. When used in iteration these are automatically created and released when going out of scope. As a result, during the iteration only one GRIB message at a time is kept in memory:" + "A :ref:`GRIB ` data object is represented by a :py:class:`~data.readers.grib.index.GribFieldList` consisting of :py:class:`~data.readers.grib.codes.GribField`\\s. When used in iteration these are automatically created and released when going out of scope. As a result, during the iteration only one GRIB message at a time is kept in memory:" ] }, { "cell_type": "code", "execution_count": 3, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -80,15 +118,42 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Inspecting the contents" ] }, + { + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "We can use :py:meth:`~data.readers.grib.index.GribFieldList.ls` or :py:meth:`~data.readers.grib.index.GribFieldList.describe`." + ] + }, { "cell_type": "code", "execution_count": 4, - "metadata": {}, + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -262,27 +327,27 @@ "data": { "text/html": [ "\n", - "\n", + "
\n", " \n", " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", " \n", @@ -300,49 +365,49 @@ " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", "
  leveldatetimestepparamIdclassstreamtypeexperimentVersionNumberleveldatetimestepparamIdclassstreamtypeexperimentVersionNumber
shortName
tisobaricInhPa1000,8502018080112000130odoperan0001tisobaricInhPa1000,8502018080112000130odoperan0001
uisobaricInhPa1000,8502018080112000131odoperan0001uisobaricInhPa1000,8502018080112000131odoperan0001
visobaricInhPa1000,8502018080112000132odoperan0001visobaricInhPa1000,8502018080112000132odoperan0001
\n" ], "text/plain": [ - "" + "" ] }, "execution_count": 6, @@ -514,16 +579,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The *values* property always returns a flat array per field:" + "The :py:attr:`~data.readers.grib.codes.GribField.values` property always returns a flat array per field:" ] }, { "cell_type": "code", "execution_count": 10, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -562,16 +640,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When called on the whole fieldlist *values* returns a 2D array:" + "When called on the whole fieldlist :py:attr:`~data.readers.grib.index.GribFieldList.values` returns a 2D array:" ] }, { "cell_type": "code", "execution_count": 12, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -597,16 +688,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "With *to_numpy()* the field shape is set on the array: " + "With :py:meth:`~data.readers.grib.codes.GribField.to_numpy` the field shape is set on the array: " ] }, { "cell_type": "code", "execution_count": 13, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -623,10 +727,30 @@ "print(ds[0].shape)" ] }, + { + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + ":py:meth:`~data.readers.grib.index.GribFieldList.to_numpy` behaves in the same way when called on a fieldlist:" + ] + }, { "cell_type": "code", "execution_count": 14, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -646,16 +770,29 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Metadata" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Metadata access works both on individual fields and slices:" + ":py:meth:`~data.readers.grib.codes.GribField.metadata` access works both on individual fields and slices:" ] }, { @@ -699,16 +836,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "and on all the fields:" + "We can also call :py:meth:`~data.readers.grib.index.GribFieldList.metadata` on a fieldlist:" ] }, { "cell_type": "code", "execution_count": 17, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -735,7 +885,13 @@ { "cell_type": "code", "execution_count": 18, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -753,21 +909,34 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "For each filed we can get the metadata as an object:" + "For each filed we can get the metadata as an :py:class:`object `:" ] }, { "cell_type": "code", "execution_count": 19, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": 19, @@ -808,16 +977,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Selection by metadata is always creating a \"view\", no copying of GRIB data is involved." + ":py:meth:`~data.readers.grib.index.GribFieldList.sel` offers metadata-based selection and always creates a \"view\", so no copying of GRIB data is involved." ] }, { "cell_type": "code", "execution_count": 21, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1000,16 +1182,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Xarray conversion does not involve disk writing. Under the hood it uses cfgrib." + "Xarray conversion with :py:meth:`~data.readers.grib.index.GribFieldList.to_xarray` does not involve disk writing. Under the hood it uses cfgrib." ] }, { "cell_type": "code", "execution_count": 23, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1399,9 +1594,9 @@ " GRIB_subCentre: 0\n", " Conventions: CF-1.7\n", " institution: European Centre for Medium-Range Weather Forecasts\n", - " history: 2023-08-11T15:58 GRIB to CDM+CF via cfgrib-0.9.1...
  • GRIB_edition :
    1
    GRIB_centre :
    ecmf
    GRIB_centreDescription :
    European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre :
    0
    Conventions :
    CF-1.7
    institution :
    European Centre for Medium-Range Weather Forecasts
    history :
    2024-02-05T12:07 GRIB to CDM+CF via cfgrib-0.9.10.4/ecCodes-2.32.1 with {"source": "N/A", "filter_by_keys": {}, "encode_cf": ["parameter", "time", "geography", "vertical"]}
    • " ], "text/plain": [ "\n", @@ -1426,7 +1621,7 @@ " GRIB_subCentre: 0\n", " Conventions: CF-1.7\n", " institution: European Centre for Medium-Range Weather Forecasts\n", - " history: 2023-08-11T15:58 GRIB to CDM+CF via cfgrib-0.9.1..." + " history: 2024-02-05T12:07 GRIB to CDM+CF via cfgrib-0.9.1..." ] }, "execution_count": 23, @@ -1440,16 +1635,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can pass all the kwargs arguments cfgrib accepts. On top of that earthkit-data provides the **ignore_keys** option to omit keys from the default set of keys used by cfgrib:" + "We can pass all the kwargs arguments cfgrib accepts. On top of that earthkit-data provides the :py:meth:`ignore_keys ` option to omit keys from the default set of keys used by cfgrib:" ] }, { "cell_type": "code", "execution_count": 24, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1838,9 +2046,9 @@ " GRIB_subCentre: 0\n", " Conventions: CF-1.7\n", " institution: European Centre for Medium-Range Weather Forecasts\n", - " history: 2023-08-11T15:58 GRIB to CDM+CF via cfgrib-0.9.1...
  • GRIB_edition :
    1
    GRIB_centre :
    ecmf
    GRIB_centreDescription :
    European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre :
    0
    Conventions :
    CF-1.7
    institution :
    European Centre for Medium-Range Weather Forecasts
    history :
    2024-02-05T12:07 GRIB to CDM+CF via cfgrib-0.9.10.4/ecCodes-2.32.1 with {"source": "N/A", "filter_by_keys": {}, "encode_cf": ["parameter", "time", "geography", "vertical"]}
    • " ], "text/plain": [ "\n", @@ -1864,7 +2072,7 @@ " GRIB_subCentre: 0\n", " Conventions: CF-1.7\n", " institution: European Centre for Medium-Range Weather Forecasts\n", - " history: 2023-08-11T15:58 GRIB to CDM+CF via cfgrib-0.9.1..." + " history: 2024-02-05T12:07 GRIB to CDM+CF via cfgrib-0.9.1..." ] }, "execution_count": 24, @@ -1880,16 +2088,22 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -1901,7 +2115,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.17" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_selection.ipynb b/docs/examples/grib_selection.ipynb index 3359f10d..647a4792 100644 --- a/docs/examples/grib_selection.ipynb +++ b/docs/examples/grib_selection.ipynb @@ -3,6 +3,10 @@ { "cell_type": "markdown", "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, "tags": [] }, "source": [ @@ -11,16 +15,29 @@ }, { "attachments": {}, - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We read a GRIB file containing 18 messages. First we ensure the example file is available." + "We :ref:`read ` a GRIB file containing 18 messages. First we ensure the example file is available." ] }, { "cell_type": "code", "execution_count": 1, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data\n", @@ -64,16 +81,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Calling sel() provides a \"view\":" + "Calling :py:meth:`~data.readers.grib.index.GribFieldList.sel` provides a \"view\":" ] }, { "cell_type": "code", "execution_count": 4, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -550,16 +580,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "isel() works similarly to sel() but takes indices instead of values. Please note that the index values are sorted for isel()." + ":py:meth:`~data.readers.grib.index.GribFieldList.isel` works similarly to :py:meth:`~data.readers.grib.index.GribFieldList.sel` but takes indices instead of values. Please note that the index values are sorted for :py:meth:`~data.readers.grib.index.GribFieldList.sel`." ] }, { "cell_type": "code", "execution_count": 9, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -942,16 +985,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Calling order_by() provides a \"view\":" + "Calling :py:meth:`~data.readers.grib.index.GribFieldList.order_by` provides a \"view\":" ] }, { "cell_type": "code", "execution_count": 13, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1458,16 +1514,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "To get the unique values for predefined set of metadata keys (the MARS ecCodes keys) we can call *indices()*. By default it returns all the keys having valid values:" + "To get the unique values for predefined set of metadata keys (the MARS ecCodes keys) we can call :py:meth:`~data.readers.grib.index.GribFieldList.indices`. By default it returns all the keys having valid values:" ] }, { "cell_type": "code", "execution_count": 18, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1525,16 +1594,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can get the unique values for a given key:" + "We can get the unique values for a given key with :py:meth:`~data.readers.grib.index.GribFieldList.index` :" ] }, { "cell_type": "code", "execution_count": 20, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1652,7 +1734,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_tar.ipynb b/docs/examples/grib_tar.ipynb index 00faaa32..282edd87 100644 --- a/docs/examples/grib_tar.ipynb +++ b/docs/examples/grib_tar.ipynb @@ -2,23 +2,42 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Reading GRIB in tar or zip archive" ] }, { "attachments": {}, - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We read a tar file containing 2 GRIB files. First we ensure the example file is available." + "We :ref:`read ` a tar file containing 2 GRIB files. First we ensure the example file is available." ] }, { "cell_type": "code", "execution_count": 1, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data\n", @@ -50,16 +69,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The files are extracted and stored in the earthkit-data cache:" + "The files are extracted and stored in the earthkit-data :ref:`cache `:" ] }, { "cell_type": "code", "execution_count": 3, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -80,16 +112,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The resulting object behaves like any standard GRIB object:" + "The resulting object behaves like any standard :ref:`GRIB object `:" ] }, { "cell_type": "code", "execution_count": 4, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -326,9 +371,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -340,7 +385,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.18" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_time_series.ipynb b/docs/examples/grib_time_series.ipynb index d38bb9d8..7cf8b4cf 100644 --- a/docs/examples/grib_time_series.ipynb +++ b/docs/examples/grib_time_series.ipynb @@ -3,24 +3,43 @@ { "cell_type": "markdown", "id": "570a34d8-7958-4de7-b4b1-76d369ce4146", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Generating time series from GRIB" ] }, { - "cell_type": "markdown", - "id": "ddb547b2-1d39-4c50-9777-19591bd0f6fa", - "metadata": {}, + "cell_type": "raw", + "id": "5eb4fabf-b21e-4e10-b572-8095daaacd70", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We will read temperature data from a GRIB file containing forecast steps. First we ensure the example file is available." + "We will read temperature data from a GRIB file containing forecast steps. First, we ensure the example file is available, then read it with :ref:`from_source() `." ] }, { "cell_type": "code", "execution_count": 1, "id": "87e4f240-b145-4c4d-9906-38db9a7b3a99", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "from earthkit.data import download_example_file, from_source\n", @@ -207,7 +226,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_to_netcdf.ipynb b/docs/examples/grib_to_netcdf.ipynb index 9c23265d..f43fc769 100644 --- a/docs/examples/grib_to_netcdf.ipynb +++ b/docs/examples/grib_to_netcdf.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "9c53d7c8-7f38-4a5f-93d0-e05919408b6e", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Converting GRIB to NetCDF" ] @@ -73,9 +79,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -87,7 +93,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/grib_url.ipynb b/docs/examples/grib_url.ipynb index 4da393f5..fb2187a5 100644 --- a/docs/examples/grib_url.ipynb +++ b/docs/examples/grib_url.ipynb @@ -4,6 +4,10 @@ "cell_type": "markdown", "id": "d02b3258-df28-41cb-921d-f365b1dd96f7", "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, "tags": [] }, "source": [ @@ -19,18 +23,31 @@ ] }, { - "cell_type": "markdown", - "id": "b06ec35d-d28c-4ce4-8d83-d8e348221dda", - "metadata": {}, + "cell_type": "raw", + "id": "965e6efa-56cd-43b7-8501-a384f7baf38c", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can load individual files from URLs:" + "We can read individual files from URLs with :ref:`from_source() `:" ] }, { "cell_type": "code", "execution_count": 1, "id": "9e07cfc0-6a41-4865-aefc-1d352d70fe4a", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data\n", @@ -533,18 +550,31 @@ ] }, { - "cell_type": "markdown", - "id": "406956cd-9a09-42f1-a6f0-e8fea0af0d13", - "metadata": {}, + "cell_type": "raw", + "id": "a5bde9a5-c859-4615-b73d-0fe16609de5a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "URLs can also be specified by using patterns. In the example below when pattern \"id\" is substituted it will match two files: test4.grib and test6.grib:" + "URLs can also be specified by using :ref:`url-patterns `. In the example below when pattern \"id\" is substituted it will match two files: test4.grib and test6.grib:" ] }, { "cell_type": "code", "execution_count": 6, "id": "246e985b-f16e-4012-a0b5-fced45044017", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { diff --git a/docs/examples/grib_url_stream.ipynb b/docs/examples/grib_url_stream.ipynb index 02b1bd7c..2eeb5eca 100644 --- a/docs/examples/grib_url_stream.ipynb +++ b/docs/examples/grib_url_stream.ipynb @@ -2,8 +2,15 @@ "cells": [ { "cell_type": "markdown", - "id": "ca9aa5f2-705a-4d80-b400-6acf7ff86786", - "metadata": {}, + "id": "d3575125-5f56-43e9-8080-4094cf309c31", + "metadata": { + "editable": true, + "raw_mimetype": "", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Reading GRIB from an URL as a stream" ] @@ -12,25 +19,44 @@ "cell_type": "code", "execution_count": 1, "id": "c23ffb07-747c-4535-b608-66b080d6d4e5", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data" ] }, { - "cell_type": "markdown", - "id": "0a58377e-7be5-4951-8a76-0d5c24444898", - "metadata": {}, + "cell_type": "raw", + "id": "e55b54da-4011-442e-99e8-9d1c82773d31", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "earthkit-data can read GRIB data from a URL as a stream without writing anything to disk. This can be activated with the **stream=True** kwarg when calling [from_source()](../guide/sources.rst#url) with a \"url\" source.\n" + "earthkit-data can read GRIB data from a URL as a stream without writing anything to disk. This can be activated with the **stream=True** kwarg when calling :ref:`from_source() `." ] }, { "cell_type": "code", "execution_count": 2, "id": "1d2b07e3-1820-45ec-88d5-c78765533735", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "ds = earthkit.data.from_source(\"url\", \n", @@ -59,18 +85,31 @@ ] }, { - "cell_type": "markdown", - "id": "994802cc-2e74-4af4-8e20-031f5937df62", - "metadata": {}, + "cell_type": "raw", + "id": "328b1d7b-500d-4014-8346-b6d47c40ee86", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "To control how the stream is read use [batch_size](../guide/sources.rst#url) and [group_by](../guide/sources.rst#url). E.g. the following code reads the GRIB data in messages of 2." + "To control how the stream is read use :ref:`batch_size ` and :ref:`group_by `. E.g. the following code reads the GRIB data in messages of 2." ] }, { "cell_type": "code", "execution_count": 4, "id": "b7c9a685-6b38-4236-ae74-a14445e8bb95", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -100,7 +139,13 @@ { "cell_type": "markdown", "id": "cb7d74b5-73e0-4e57-9d80-e45a9dc725d8", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Multiple URLs" ] @@ -108,7 +153,13 @@ { "cell_type": "markdown", "id": "6d5efce5-c9d0-4edf-a2cf-312ced9339b5", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "The stream option works even when the input is a list of URLs." ] diff --git a/docs/examples/list_of_dict.ipynb b/docs/examples/list_of_dict.ipynb index 823eadf6..c74b31df 100644 --- a/docs/examples/list_of_dict.ipynb +++ b/docs/examples/list_of_dict.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using list of dictionaries as input" ] @@ -777,9 +783,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -791,7 +797,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/mars.ipynb b/docs/examples/mars.ipynb index d20b0d02..df981b6c 100644 --- a/docs/examples/mars.ipynb +++ b/docs/examples/mars.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "f7049550-e9a9-4706-82e6-f0fe7892c88b", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retrieving data from the ECMWF MARS archive" ] @@ -133,9 +139,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -147,7 +153,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/metadata.ipynb b/docs/examples/metadata.ipynb index 92f5aa79..45eada07 100644 --- a/docs/examples/metadata.ipynb +++ b/docs/examples/metadata.ipynb @@ -2,8 +2,15 @@ "cells": [ { "cell_type": "markdown", - "id": "fe3cd62d-cd92-4c1d-886f-6f98e687de8f", - "metadata": {}, + "id": "d1a669e9-8daf-4596-ab77-05bb0a732326", + "metadata": { + "editable": true, + "raw_mimetype": "", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "# Metadata" ] @@ -12,18 +19,31 @@ "cell_type": "code", "execution_count": 1, "id": "94327151-7afc-46f1-84b1-07c080d65e9f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data" ] }, { - "cell_type": "markdown", - "id": "2b26dbc9-7808-47f4-bfe8-e8815f7a613d", - "metadata": {}, + "cell_type": "raw", + "id": "d53140b9-a2f7-4226-a650-de61ce6762ad", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Metadata of the various data formats are represented by **Metadata** objects, which are:\n", + "Metadata of the various data formats are represented by :py:class:`~data.core.metadata.Metadata` objects, which are:\n", "\n", "- immutable\n", "- behave like a dict\n", @@ -34,24 +54,43 @@ { "cell_type": "markdown", "id": "42b48cb8-7bc5-4471-83e6-a32d924ca7ff", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## RawMetadata" ] }, { - "cell_type": "markdown", - "id": "eafb3ca4-e432-4177-86a4-09732a4fce49", - "metadata": {}, + "cell_type": "raw", + "id": "0d96ce25-7b3d-4571-b91d-d63be0f62a8a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The simplest metadata type is **RawMetadata**, which we can create in the same way as a dict:" + "The simplest metadata type is :py:class:`~data.core.metadata.RawMetadata`, which we can create in the same way as a dict:" ] }, { "cell_type": "code", "execution_count": 2, "id": "c0b8a49f-e181-414b-870c-748efa81f711", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "from earthkit.data.core.metadata import RawMetadata\n", @@ -96,18 +135,31 @@ ] }, { - "cell_type": "markdown", - "id": "a26fd902-4a6e-4463-b3c2-21805096b26b", - "metadata": {}, + "cell_type": "raw", + "id": "d10d7315-5eb7-4e03-8c46-e10447389d5a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can get the value for a key using *[]* and *get()* just like for a dict:" + "We can get the value for a key using *[]* and :py:meth:`~data.core.metadata.RawMetadata.get` just like for a dict:" ] }, { "cell_type": "code", "execution_count": 4, "id": "fbc16f06-af69-4c6d-91e0-a6c6f9250d09", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -153,18 +205,31 @@ ] }, { - "cell_type": "markdown", - "id": "8f06b8a7-b25d-4dd4-8293-65d66d7e5600", - "metadata": {}, + "cell_type": "raw", + "id": "7d322f02-34ef-47ab-bf67-77503ebf3d5a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "*get()* can take a default value as a second argument. When the key is not available the default value is returned. If default is not given, it defaults to None, so that this method never raises a KeyError." + ":py:meth:`~data.core.metadata.RawMetadata.get` can take a default value as a second argument. When the key is not available the default value is returned. If default is not given, it defaults to None, so that this method never raises a KeyError." ] }, { "cell_type": "code", "execution_count": 6, "id": "a1d2c43f-0b90-4f01-a6c8-f81f5c9d9dea", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -238,18 +303,31 @@ ] }, { - "cell_type": "markdown", - "id": "b7dab67d-4e2a-408a-8c9a-e317d6d08b93", - "metadata": {}, + "cell_type": "raw", + "id": "67ef7d14-131a-4de4-ba38-b630e9e9dd82", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The metadata object is immutable but we can use *override()* to create a new object with a modified content:" + "The metadata object is immutable but we can use :py:meth:`~data.core.metadata.RawMetadata.override` to create a new object with a modified content:" ] }, { "cell_type": "code", "execution_count": 9, "id": "5cd1240f-e3e0-420a-babc-b2233c7d0c55", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "md1 = md.override({\"shortName\": \"2d\", \"step\": 6})" @@ -443,36 +521,62 @@ ] }, { - "cell_type": "markdown", - "id": "99735c25-dc9c-4da5-aff2-644b35725321", - "metadata": {}, + "cell_type": "raw", + "id": "9c3850ea-1ac6-4d0f-8c3d-5c1b6375208b", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We cannot create GRIB metadata object from a dict or RawMetadata, but can get it from a GRIB field. The resulting **GribMetadata** instance will store a reference to the ecCodes handle of its parent field." + "We cannot create GRIB metadata object from a dict or :py:class:`~data.core.metadata.RawMetadata`, but can get it from a GRIB field. The resulting :py:class:`~data.readers.grib.metadata.GribMetadata` instance will store a reference to the ecCodes handle of its parent field." ] }, { "cell_type": "code", "execution_count": 13, "id": "d9e78ce1-a8af-4635-8fb3-8b8c3d486710", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "md = ds[0].metadata()" ] }, { - "cell_type": "markdown", - "id": "b5e56227-05b2-44eb-9678-208aba092c9f", - "metadata": {}, + "cell_type": "raw", + "id": "9b98cfb0-a283-4ab3-9471-d805ed01eb70", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "GribMetadata works like a dict:" + ":py:class:`~data.readers.grib.metadata.GribMetadata` works like a dict:" ] }, { "cell_type": "code", "execution_count": 14, "id": "05a8b857-e3d5-40a6-8201-adafe0239c74", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -493,18 +597,31 @@ ] }, { - "cell_type": "markdown", - "id": "b3b30f67-c018-4f9a-8d5a-63154858c482", - "metadata": {}, + "cell_type": "raw", + "id": "8bd7cd30-9c59-44e3-a845-a6f41dff9236", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "However, it is also aware of the ecCodes GRIB namespaces:" + "However, it is also aware of the :xref:`eccodes_namespace`\\s, when we use :py:meth:`~data.readers.grib.metadata.GribMetadata.as_namespace` or :py:meth:`~data.readers.grib.metadata.GribMetadata.dump`. " ] }, { "cell_type": "code", "execution_count": 15, "id": "f3c0c9da-0c41-4c39-8094-b2b8a50f1680", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1029,18 +1146,31 @@ ] }, { - "cell_type": "markdown", - "id": "eb486396-584f-4b4b-a3f6-67d74085b4e5", - "metadata": {}, + "cell_type": "raw", + "id": "07b127e2-3401-44a7-9e83-5feb2e116b79", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When we call *override()* the new ecCodes handle is cloned and updated then added to the resulting object. The original metadata will not change." + "When we call :py:meth:`~data.readers.grib.metadata.GribMetadata.override` the new ecCodes handle is cloned and updated then added to the resulting object. The original metadata will not change." ] }, { "cell_type": "code", "execution_count": 17, "id": "ac4195c6-9473-4db2-8747-38ddc5205a34", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -1088,18 +1218,31 @@ ] }, { - "cell_type": "markdown", - "id": "3627609c-4d99-4ec4-9a0f-73a209823cb9", - "metadata": {}, + "cell_type": "raw", + "id": "dc74c7bc-e6c7-4fad-970c-9471e03c1a39", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - " *override()* also works with other Metadata objects:" + ":py:meth:`~data.readers.grib.metadata.GribMetadata.override` also works with other Metadata objects:" ] }, { "cell_type": "code", "execution_count": 19, "id": "3ea5c463-e17e-4cce-9bd8-a10df6b58589", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -1142,7 +1285,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/netcdf.ipynb b/docs/examples/netcdf.ipynb index 5e8baba3..40368bdc 100644 --- a/docs/examples/netcdf.ipynb +++ b/docs/examples/netcdf.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using NetCDF data" ] @@ -650,9 +656,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -664,7 +670,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.17" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/netcdf_fieldlist.ipynb b/docs/examples/netcdf_fieldlist.ipynb index 573f7ee9..90a3030b 100644 --- a/docs/examples/netcdf_fieldlist.ipynb +++ b/docs/examples/netcdf_fieldlist.ipynb @@ -2,23 +2,42 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## NetCDF fieldlists" ] }, { "attachments": {}, - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We load a NetCDF file containing 3 variables on pressure levels on a 2D latitude-longitude grid. First we ensure the example file is available." + "We :ref:`read ` a NetCDF file containing 3 variables on pressure levels on a 2D latitude-longitude grid. First we ensure the example file is available." ] }, { "cell_type": "code", "execution_count": 1, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data\n", @@ -35,15 +54,28 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "Our NetCDF data is represented as a FieldList consisting of NetCDFFields. Field in this context means a 2D geographical coverage (horizontal slices). " + "Our NetCDF data is represented as a :py:class:`~data.core.fieldlist.FieldList` consisting of NetCDFFields. :py:class:`~data.core.fieldlist.Field` in this context means a 2D geographical coverage (horizontal slices). " ] }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "### Iteration" ] @@ -434,16 +466,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The *values* property always returns a flat array per field:" + "The :py:attr:`~data.core.fieldlist.Field.values` property always returns a flat array per field:" ] }, { "cell_type": "code", "execution_count": 9, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -482,16 +527,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When called on the whole fieldlist *values* returns a 2D array:" + "When called on the whole fieldlist :py:attr:`~data.core.fieldlist.FieldList.values` returns a 2D array:" ] }, { "cell_type": "code", "execution_count": 11, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -517,16 +575,29 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "With to_numpy() the field shape is set on the array: " + "With :py:meth:`~data.core.fieldlist.Field.to_numpy` the field shape is set on the array: " ] }, { "cell_type": "code", "execution_count": 12, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -1612,9 +1683,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -1626,7 +1697,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.17" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/numpy_fieldlist.ipynb b/docs/examples/numpy_fieldlist.ipynb index 99c3256a..7cd65b01 100644 --- a/docs/examples/numpy_fieldlist.ipynb +++ b/docs/examples/numpy_fieldlist.ipynb @@ -3,26 +3,45 @@ { "cell_type": "markdown", "id": "8f1994c5-bb2a-4c52-8405-fd240cf965ba", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## FieldList from numpy array and metadata" ] }, { - "cell_type": "markdown", - "id": "960d1169-8e29-4b2b-81ca-6bcb34d14469", - "metadata": {}, + "cell_type": "raw", + "id": "a8eca176-b7fc-41d8-a1ac-e243c5f8070b", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "In this notebook we will show how to do some computations with GRIB data and generate a NumpyFieldList from the results.\n", + "In this notebook we will show how to do some computations with GRIB data and generate a :py:class:`~data.sources.numpy_list.NumpyFieldList` from the results.\n", "\n", - "First we read some GRIB data containing pressure level fields." + "First we :ref:`read ` some GRIB data containing pressure level fields." ] }, { "cell_type": "code", "execution_count": 1, "id": "348564d3-1e60-455f-9081-499ce083d27c", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import earthkit.data\n", @@ -180,18 +199,31 @@ ] }, { - "cell_type": "markdown", - "id": "651cffc5-5824-47cc-8bd5-654ef2ffb95b", - "metadata": {}, + "cell_type": "raw", + "id": "07e29bb2-1410-4d4d-8feb-e6aa1af0215a", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We create a new metadata object for the results from the source field's metadata." + "We create a new :py:class:`~data.readers.grib.metadata.GribMetadata` object from the source field's :py:meth:`~data.readers.grib.codes.GribField.metadata` using :py:meth:`~data.readers.grib.metadata.GribMetadata.override`." ] }, { "cell_type": "code", "execution_count": 7, "id": "f8dcc33c-6818-415d-8088-6a01666ca87f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -238,18 +270,31 @@ ] }, { - "cell_type": "markdown", - "id": "b2b88c83-8886-4029-ad8c-0b2fbd43f162", - "metadata": {}, + "cell_type": "raw", + "id": "058c2fd8-569b-4ddb-b8bb-217854e9ff73", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "A new FieldList (type of NumpyFieldList) can be created from the resulting ndarray and the modified metadata. It behaves as if it were a GribFieldList." + "A new FieldList (type of :py:class:`~data.sources.numpy_list.NumpyFieldList`) can be created from the resulting ndarray and the modified metadata. It behaves as if it were a :py:class:`~data.readers.grib.index.GribFieldList`." ] }, { "cell_type": "code", "execution_count": 9, "id": "5a2557a6-091c-4345-a792-d3bfa7876c77", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -386,18 +431,31 @@ ] }, { - "cell_type": "markdown", - "id": "648f86c8-e004-4500-bef6-e8fa296ba99e", - "metadata": {}, + "cell_type": "raw", + "id": "c7733bdd-1a47-4dba-aac4-b6ed43e15337", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can save the NumpyFieldList into a GRIB file:" + "We can save the :py:class:`~data.sources.numpy_list.NumpyFieldList` into a GRIB file:" ] }, { "cell_type": "code", "execution_count": 13, "id": "c22a23fc-fccd-45ef-887e-95ab61b0dee1", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -642,18 +700,31 @@ ] }, { - "cell_type": "markdown", - "id": "5c739883-5d27-42d8-ada7-eac63817f226", - "metadata": {}, + "cell_type": "raw", + "id": "8f2f7612-3ff9-4982-9cb0-a91a426f1b0f", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We create a NumpyFieldlist from the resulting ndarray and the modified metadata." + "We create a :py:class:`~data.sources.numpy_list.NumpyFieldList` from the resulting ndarray and the modified metadata." ] }, { "cell_type": "code", "execution_count": 17, "id": "ab0c805e-9e33-40f1-a816-501c2cff64a1", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -800,18 +871,31 @@ ] }, { - "cell_type": "markdown", - "id": "ca36db53-32fb-4ad0-a582-b5760dad6b36", - "metadata": {}, + "cell_type": "raw", + "id": "ca785b7b-d7a8-424b-99c5-19056a0b23b0", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can save the NumpyFieldList into a GRIB file:" + "We can save the :py:class:`~data.sources.numpy_list.NumpyFieldList` into a GRIB file:" ] }, { "cell_type": "code", "execution_count": 20, "id": "e8e1c8a2-87aa-4ec2-895e-8ea7bd83e101", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -923,18 +1007,31 @@ ] }, { - "cell_type": "markdown", - "id": "0963540f-3a6d-4f0d-a046-3806c5f65e30", - "metadata": {}, + "cell_type": "raw", + "id": "4fc8aa2f-c5ea-4310-841a-98c863a4acd7", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "In this example we create an **empty fieldlist** and add the results of the computations to it in a loop." + "In this example we create an **empty** :py:class:`~data.core.fieldlist.FieldList` and add the results of the computations to it in a loop." ] }, { "cell_type": "code", "execution_count": 21, "id": "6c6e8651-f5a3-4534-9227-812e8e69407d", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "fs = ds.sel(shortName=\"t\", level=[850, 700, 500])\n", @@ -1059,11 +1156,18 @@ ] }, { - "cell_type": "markdown", - "id": "b76eaf59-868c-4a59-8823-8d4bc53376f3", - "metadata": {}, + "cell_type": "raw", + "id": "b7635ff3-9610-415b-861d-de934591c960", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can save the NumpyFieldList into a GRIB file:" + "We can save the :py:class:`~data.sources.numpy_list.NumpyFieldList` into a GRIB file:" ] }, { @@ -1198,7 +1302,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/odb.ipynb b/docs/examples/odb.ipynb index 1a1e5b35..944123b8 100644 --- a/docs/examples/odb.ipynb +++ b/docs/examples/odb.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "4cf9f31e-4b58-43bd-842e-142f0affb4a8", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Using ODB data" ] @@ -20,18 +26,31 @@ ] }, { - "cell_type": "markdown", - "id": "08cd75b9-6685-4a49-99a7-c5d8a7acc80b", - "metadata": {}, + "cell_type": "raw", + "id": "a9e6621e-5c32-4a0d-a992-209660f58f68", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "[ODB](https://odc.readthedocs.io/en/latest/content/introduction.html) is a bespoke format developed at ECMWF to store observations. The following code reads some ODB data from a file containing forecast and analysis departures:" + "`ODB `_ is a bespoke format developed at ECMWF to store observations. The following code reads some ODB data with :ref:`from_source() ` from a file containing forecast and analysis departures:" ] }, { "cell_type": "code", "execution_count": 2, "id": "d2f705e7-8336-4355-9b60-1fe05d8e23b3", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "ds = earthkit.data.from_source(\"file\", \"test.odb\")" @@ -40,7 +59,13 @@ { "cell_type": "markdown", "id": "6a0702a9-0b1a-46e6-bac3-71c78050f2e4", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "*to_pandas()* converts data into a Pandas dataframe (uses [pyodc](https://github.com/ecmwf/pyodc) under the hood):" ] @@ -49,7 +74,13 @@ "cell_type": "code", "execution_count": 3, "id": "2f252c91-3cc9-46ec-b262-3b2f399ce05d", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -338,9 +369,9 @@ ], "metadata": { "kernelspec": { - "display_name": "mpy38", + "display_name": "dev_ecc", "language": "python", - "name": "mpy38" + "name": "dev_ecc" }, "language_info": { "codemirror_mode": { @@ -352,7 +383,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/pandas.ipynb b/docs/examples/pandas.ipynb index 133b740a..6f1d4c19 100644 --- a/docs/examples/pandas.ipynb +++ b/docs/examples/pandas.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "# Using pandas and geopandas data" ] @@ -32,7 +38,13 @@ { "cell_type": "code", "execution_count": 5, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -451,16 +463,42 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "## Geopandas" + ] + }, + { + "cell_type": "raw", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "## Geopandas\n", - "Load a geojson object from `\"file\"` source. Default representation is a geopandas dataframe" + "Load a geojson object as a \"file\" source using :ref:`from_source() `. Default representation is a geopandas dataframe" ] }, { "cell_type": "code", "execution_count": 8, - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -1036,7 +1074,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -1050,10 +1088,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" - }, - "orig_nbformat": 4 + "version": "3.10.13" + } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 } diff --git a/docs/examples/polytope.ipynb b/docs/examples/polytope.ipynb index ad7c1002..8ee53fd9 100644 --- a/docs/examples/polytope.ipynb +++ b/docs/examples/polytope.ipynb @@ -3,29 +3,42 @@ { "cell_type": "markdown", "id": "efdd065e-e9fc-494d-9f73-9cb3d525dc4a", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retrieving data with polytope" ] }, { - "cell_type": "markdown", - "id": "3f96608d", - "metadata": {}, - "source": [] - }, - { - "cell_type": "markdown", - "id": "75079b34-78ba-4536-8498-4dc3d0c3e646", - "metadata": {}, + "cell_type": "raw", + "id": "9a779849-2eb3-4076-ac20-20a6fef63aed", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The “polytope” data source provides access to the [Polytope web services](https://polytope-client.readthedocs.io/en/latest/)." + "The :ref:`polytope ` source provides access to the `Polytope web services `_." ] }, { "cell_type": "markdown", "id": "621c0aa7-db93-441a-ab55-743fa6fbcd51", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "The following example retrieves data from the ECMWF MARS archive using polytope. The dataset was prepared for the OGC GeoDataCubes working group, see details [here](https://github.com/ecmwf/ogc-gdc-usecase/tree/main)." ] @@ -34,7 +47,13 @@ "cell_type": "code", "execution_count": 1, "id": "7910ac60-a503-4392-a719-0b780625346f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stderr", @@ -186,7 +205,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/projection.ipynb b/docs/examples/projection.ipynb index 4a300011..89352381 100644 --- a/docs/examples/projection.ipynb +++ b/docs/examples/projection.ipynb @@ -2,7 +2,13 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Projections" ] @@ -12187,7 +12193,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.16" + "version": "3.10.13" }, "vscode": { "interpreter": { diff --git a/docs/examples/settings.ipynb b/docs/examples/settings.ipynb index cde30274..2dac3c5b 100644 --- a/docs/examples/settings.ipynb +++ b/docs/examples/settings.ipynb @@ -3,7 +3,13 @@ { "cell_type": "markdown", "id": "53d7b7af-fc34-450c-9c39-493f3d881c49", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Settings" ] @@ -21,24 +27,43 @@ { "cell_type": "markdown", "id": "01b48692-a39d-4cfd-99dd-4047501edb54", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "#### Settings basics" ] }, { "attachments": {}, - "cell_type": "markdown", - "id": "9f4443e7-8e50-4583-830e-31fd4f2004f3", - "metadata": {}, + "cell_type": "raw", + "id": "492ab3b0-edf8-421f-8b77-c508447d391c", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The settings object is loaded from the **\"~/.earthkit-data/settings.yaml\"** file. Changes are immediately saved back into this file unless we explicitly disable it or use temporary settings (see below for details)." + "The :ref:`settings` object is loaded from the **\"~/.earthkit-data/settings.yaml\"** file. Changes are immediately saved back into this file unless we explicitly disable it or use :ref:`temporary settings `." ] }, { "cell_type": "markdown", "id": "bb06b2f7-5552-4247-843e-2e328beaabe9", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "For the rest of this notebook we disable the settings autosave so the changes will not be written into our configuration file." ] @@ -108,18 +133,31 @@ ] }, { - "cell_type": "markdown", - "id": "09612eaf-6cf1-4335-b288-86ac5b04ff25", - "metadata": {}, + "cell_type": "raw", + "id": "23b0893d-f6cd-42bc-b030-0917684b7786", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can use **get()** to access settings values." + "We can use :ref:`get() ` to access the settings values." ] }, { "cell_type": "code", "execution_count": 4, "id": "c477d8a3-eef8-4f73-86f1-64bdbabd13d5", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -137,18 +175,31 @@ ] }, { - "cell_type": "markdown", - "id": "c9a56a5a-87ef-445f-b052-43d820a9bcc3", - "metadata": {}, + "cell_type": "raw", + "id": "c61b5316-04cc-455a-a51a-66717af22bfd", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can use **set()** to change values." + "We can use :ref:`set() ` to change the values." ] }, { "cell_type": "code", "execution_count": 5, "id": "373e772d-52ac-4166-94a5-b7f501a4490f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -198,7 +249,13 @@ { "cell_type": "markdown", "id": "2b0e80b7-cc1d-47df-ac9c-8815581f2b87", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "Alternatively, we can use keyword arguments. However, because the \"-\" character is not allowed in variable names in Python we have to replace \"-\" with \"_\" in all the keyword arguments:" ] @@ -234,18 +291,31 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "4023ce0d-4fd8-435a-92c3-7b9261895649", - "metadata": {}, + "cell_type": "raw", + "id": "08bca9e3-65f3-4557-8be0-be2c79f98fb7", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can create a temporary settings (as a context manager) as a copy of the original settings. We will still refer to it as \"settings\", but it is completely independent from the original object and changes are not saved into the yaml file (even when *settings.auto_save_settings* is True)." + "We can create a :ref:`temporary settings ` (as a context manager) as a copy of the original settings. We will still refer to it as \"settings\", but it is completely independent from the original object and changes are not saved into the yaml file (even when *settings.auto_save_settings* is True)." ] }, { "cell_type": "code", "execution_count": 8, "id": "5f63aca8-b609-4436-91d8-5e9b0e56a7c0", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -332,18 +402,31 @@ }, { "attachments": {}, - "cell_type": "markdown", - "id": "f53e4a57-278d-46bb-b0bb-cde58d04ba48", - "metadata": {}, + "cell_type": "raw", + "id": "323f7e0b-9126-4af5-9197-be98c60e2e1c", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The **reset()** method resets the settings to the defaults. We demonstrate it on a temporary settings:" + "The :ref:`reset() ` method resets the settings to the defaults. We demonstrate it on a temporary settings:" ] }, { "cell_type": "code", "execution_count": 11, "id": "2cc244ba-e80f-4111-b309-6ea7bf1b8119", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "name": "stdout", @@ -388,7 +471,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/examples/wekeo.ipynb b/docs/examples/wekeo.ipynb index 3a4826ec..1c7e0d34 100644 --- a/docs/examples/wekeo.ipynb +++ b/docs/examples/wekeo.ipynb @@ -3,40 +3,72 @@ { "cell_type": "markdown", "id": "3599bcd8-a5ee-4911-96c9-976b849138fb", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Retieving data from WEkEO" ] }, { - "cell_type": "markdown", - "id": "1491dd53-2993-48c1-9118-72b1ffdd2b91", - "metadata": {}, + "cell_type": "raw", + "id": "e0756690-e59f-47b4-a5a6-daf7e30b92af", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "The “wekeo” and \"wekeocds\" data sources provide access to [WEkEO](https://www.wekeo.eu/)." + "The :ref:`wekeo ` and :ref:`wekeocds ` sources provide access to `WEkEO `_." ] }, { "cell_type": "markdown", "id": "e32b8f13-137a-436e-8523-fcee759dfb02", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "#### Using the WEkEO grammar" ] }, { - "cell_type": "markdown", - "id": "c9d0a291-c9b9-480d-a70a-8be0a4be423f", - "metadata": {}, + "cell_type": "raw", + "id": "e6a6d76d-6563-4e6b-8aa6-e4f5a6b7b3d5", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "When we want access data using the WEkEO grammar (see the [hda](https://hda.readthedocs.io/) documentation) we need to use the \"wekeo\" source. The following example retrieves Normalized Difference Vegetation Index data derived from EO satellite imagery in NetCDF format:" + "When we want access data using the WEkEO grammar (see the `hda `_ documentation) we need to use the :ref:`wekeo ` source. The following example retrieves Normalized Difference Vegetation Index data derived from EO satellite imagery in NetCDF format:" ] }, { "cell_type": "code", "execution_count": 1, "id": "15d5599f-1242-4238-8d5d-e459694bc296", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [ { "data": { @@ -562,17 +594,30 @@ ] }, { - "cell_type": "markdown", - "id": "e50860ec-4da6-4fdb-b65c-af876ad5c6df", - "metadata": {}, + "cell_type": "raw", + "id": "4673ee18-c3be-49dd-b704-2f5bacb56b42", + "metadata": { + "editable": true, + "raw_mimetype": "text/restructuredtext", + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can use the \"wekeocds\" source to access [Copernicus Climate Data Store (CDS)](https://cds.climate.copernicus.eu) datasets served on [WEkEO](https://www.wekeo.eu/) using the [cdsapi](https://pypi.org/project/cdsapi) standard grammar." + "We can use the :ref:`wekeocds ` source to access `Copernicus Climate Data Store (CDS) `_ datasets served on `WEkEO `_ using the `cdsapi `_ standard grammar." ] }, { "cell_type": "markdown", "id": "777ec204-fbff-41f3-8ae2-3f60c6acb39f", - "metadata": {}, + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "The following example retrieves ERA5 surface data in GRIB format:" ] @@ -703,7 +748,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.10.13" } }, "nbformat": 4, diff --git a/docs/guide/settings.rst b/docs/guide/settings.rst index 95c7fe1a..3d904de3 100644 --- a/docs/guide/settings.rst +++ b/docs/guide/settings.rst @@ -13,6 +13,7 @@ be accessed and modified from Python. See the :ref:`/examples/settings.ipynb` notebook for examples. +.. _settings_get: Accessing settings ------------------ @@ -22,6 +23,8 @@ earthkit-data settings can be accessed using the python API: .. literalinclude:: include/settings-get.py +.. _settings_set: + Changing settings ------------------ @@ -34,6 +37,7 @@ earthkit-data settings can be modified using the python API: .. literalinclude:: include/settings-set.py +.. _settings_temporary: Temporary settings ------------------ @@ -49,6 +53,8 @@ Output:: 11 +.. _settings_reset: + Resetting settings ------------------