{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"id": "4da9684d-260e-49f4-a9ae-164738c17f3d",
"metadata": {
"id": "4da9684d-260e-49f4-a9ae-164738c17f3d"
},
"source": [
"# How to Access GES DISC Data Using Python\n",
"\n",
"### Overview\n",
"\n",
"There are multiple ways to work with GES DISC data resources using Python. For example, the data can accessed using [techniques that rely on a native Python code](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html). \n",
"\n",
"Still, there are several third-party libraries that can further simplify the access. In the sections below, we demonstrate downloading and streaming granules to the notebook using these libraries.\n",
"\n",
"The examples will use a sample MERRA-2 granule, from the [M2T1NXSLV.5.12.4 collection](https://doi.org/10.5067/VJAFPLI1CSIV), to demonstrate data access.\n",
"\n",
"### Prerequisites\n",
"\n",
"
\n",
" Warning: An Earthdata Login account with the \"NASA GES DISC DATA ARCHIVE\" and \"Hyrax in the Cloud\" applications enabled are required to access GES DISC data and store \"Earthdata prerequisite files\". To create an Earthdata Login account, and enable these applications, please visit this guide.\n",
"
\n",
"\n",
"\n",
"\n",
"
\n",
" Note: Please, be very judicious when working on long data time series residing on a remote data server. \n",
" It is very likely that attempts to apply similar approaches on remote data, such as hourly data, for more than a year of data at a time, will result in a heavy load on the remote data server. This may lead to negative consequences, ranging from very slow performance that will be experienced by hundreds of other users, up to denial of service.\n",
"
\n",
"\n",
"This notebook was written using Python 3.10, and requires these libraries and files:\n",
"\n",
"- `netrc` or `edl_token` file with valid Earthdata Login credentials\n",
" - [How to Generate Earthdata Prerequisite Files](https://disc.gsfc.nasa.gov/information/howto?title=How%20to%20Generate%20Earthdata%20Prerequisite%20Files)\n",
"- [pydap](https://github.com/pydap/pydap) (we recommend using version 3.5)\n",
"- [xarray](https://docs.xarray.dev/en/stable/) (must be >=2025.4.0)\n",
"- [netCDF4-python](https://github.com/Unidata/netcdf4-python) (we recommend using version 1.6.2)\n",
"- [earthaccess](https://earthaccess.readthedocs.io/en/latest/quick-start/)\n",
"- ***Optional:***\n",
" - [requests](https://pypi.org/project/requests/), when using a `.edl_token` for authentication\n",
"\n",
"### Optional Anaconda Environment YAML:\n",
"This notebook can be run using the ['nasa-gesdisc' YAML file](https://github.com/nasa/gesdisc-tutorials/tree/main/environments/nasa-gesdisc.yml) provided in the 'environments' subfolder. \n",
"Please follow the instructions [here](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file) to install and activate this environment.\n",
" \n",
"\n",
"### Contents\n",
"* [Search and Download Full Granule Data using `earthaccess`](#download_full_granules)\n",
"\n",
"* [Search and Stream Full Granule Data using `earthaccess`](#stream_full_granules)\n",
"\n",
"* [Search, Subset, and Stream Granule Data from OPeNDAP Servers](#opendap)\n",
" * [Option 1: Use `xarray` and `pydap`](#opendap_xarray)\n",
" * [Option 2: Use `netcdf4-python`](#opendap_netcdf4-python)\n",
"* [Search, Subset, and Stream Granule Data from THREDDS Servers Using Xarray](#thredds)\n",
"\n",
"* [Search, Subset, and Stream Data from the Level 3/4 Subsetter and Regridder API](#l34rs)"
]
},
{
"cell_type": "markdown",
"id": "6d3259b1",
"metadata": {},
"source": [
"### Links Used in this Notebook\n",
"\n",
"There are several example links that will be used to access data from the same granule. Each link can be searched for using several tools, including [Earthdata Search](https://search.earthdata.nasa.gov/search/granules/granule-details?p=C1276812863-GES_DISC&pg[0][v]=f&pg[0][qt]=1980-01-01%2C1981&pg[0][gsk]=-start_date&g=G1277898447-GES_DISC&q=M2T1NXSLV&tl=1723660883!3!!), the [Digital Object Identifier (DOI)](https://doi.org/10.5067/VJAFPLI1CSIV) for the particular collection, or through the [Common Metadata Repository](https://cmr.earthdata.nasa.gov/virtual-directory/collections/C1276812863-GES_DISC/temporal/1980/01/01). Links can be generated programmatically using the `earthaccess` library, the [python-cmr](https://github.com/nasa/python_cmr) library, or the [Web Services API](https://disc.gsfc.nasa.gov/information/howto?keywords=dataset%).\n",
"\n",
"Links used in this notebook:\n",
"- M2T1NXSLV.5.12.4 Dataset DOI: https://doi.org/10.5067/VJAFPLI1CSIV\n",
"- HTTPS: https://data.gesdisc.earthdata.nasa.gov/data/MERRA2/M2T1NXSLV.5.12.4/1980/01/MERRA2_100.tavg1_2d_slv_Nx.19800101.nc4\n",
"- OPeNDAP ([?](https://disc.gsfc.nasa.gov/information/documents?title=OPeNDAP%20In%20The%20Cloud)): \n",
" - OPeNDAP Subsetting Page: https://opendap.earthdata.nasa.gov/collections/C1276812863-GES_DISC/granules/M2T1NXSLV.5.12.4%3AMERRA2_100.tavg1_2d_slv_Nx.19800101.nc4.dmr.html\n",
" - Example OPeNDAP URL (No Subsetting): https://opendap.earthdata.nasa.gov/collections/C1276812863-GES_DISC/granules/M2T1NXSLV.5.12.4%3AMERRA2_100.tavg1_2d_slv_Nx.19800101.nc4 (Accessing this URL in a browser will cause an error)\n",
" - Example OPeNDAP URL (With variable subset): https://opendap.earthdata.nasa.gov/collections/C1276812863-GES_DISC/granules/M2T1NXSLV.5.12.4%3AMERRA2_100.tavg1_2d_slv_Nx.19800101.nc4?dap4.ce=/T2M%3B/lat%3B/lon%3B/time (this is an encoded URL, intended to be accessed using wget or curl)\n",
"- THREDDS ([?](https://docs.unidata.ucar.edu/tds/4.6/adminguide/#:~:text=Overview,other%20remote%20data%20access%20protocols.)): \n",
" - Example THREDDS URL Subsetting Page: https://goldsmr4.gesdisc.eosdis.nasa.gov/thredds/dodsC/MERRA2_aggregation/M2T1NXSLV.5.12.4/M2T1NXSLV.5.12.4_Aggregation_1980.ncml.html\n",
" - Example THREDDS URL (for `Xarray` access only): https://goldsmr4.gesdisc.eosdis.nasa.gov/thredds/dodsC/MERRA2_aggregation/M2T1NXSLV.5.12.4/M2T1NXSLV.5.12.4_Aggregation_1980.ncml\n",
"\n",
"\n",
"\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "00915c09",
"metadata": {},
"source": [
"### Search and Download Full Granule Data using `earthaccess` \n",
"\n",
"The `earthaccess` library can be used to search for granules and download them to your local machine, based on the collection shortname, longname, version, or DOI, gathered from the collection dataset landing page or the Content Metadata Repository. The `search_data` function will search for granules inside the specified temporal and bounding box ranges, and will return a list of URLs to be downloaded. Finally, it will download these URLs, assuming you have been authenticated using your previously-generated Earthdata prerequisite files. This method uses the `fsspec` Python library to download the granules, each of which are stored inside the `results` variable.\n",
"\n",
"Please note that `earthaccess` has the ability to query OPeNDAP URLs, but not handle and execute subsetting requests to OPeNDAP servers. The URLs `earthaccess` queries will need to be passed onto `Xarray` and `Pydap`."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "cb1f4694",
"metadata": {},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "900dadc2160e42a8b4b3ee0d61a64fd8",
"version_major": 2,
"version_minor": 0
},
"text/plain": [
"QUEUEING TASKS | : 0%| | 0/1 [00:00\n",
"Dimensions: (lon: 576, lat: 361, time: 24)\n",
"Coordinates:\n",
" * lon (lon) float64 -180.0 -179.4 -178.8 -178.1 ... 178.1 178.8 179.4\n",
" * lat (lat) float64 -90.0 -89.5 -89.0 -88.5 ... 88.5 89.0 89.5 90.0\n",
" * time (time) datetime64[ns] 1980-01-01T00:30:00 ... 1980-01-01T23:30:00\n",
"Data variables: (12/47)\n",
" CLDPRS (time, lat, lon) float32 dask.array\n",
" CLDTMP (time, lat, lon) float32 dask.array\n",
" DISPH (time, lat, lon) float32 dask.array\n",
" H1000 (time, lat, lon) float32 dask.array\n",
" H250 (time, lat, lon) float32 dask.array\n",
" H500 (time, lat, lon) float32 dask.array\n",
" ... ...\n",
" V250 (time, lat, lon) float32 dask.array\n",
" V2M (time, lat, lon) float32 dask.array\n",
" V500 (time, lat, lon) float32 dask.array\n",
" V50M (time, lat, lon) float32 dask.array\n",
" V850 (time, lat, lon) float32 dask.array\n",
" ZLCL (time, lat, lon) float32 dask.array\n",
"Attributes: (12/30)\n",
" History: Original file generated: Sat May 31 17...\n",
" Comment: GMAO filename: d5124_m2_jan79.tavg1_2d...\n",
" Filename: MERRA2_100.tavg1_2d_slv_Nx.19800101.nc4\n",
" Conventions: CF-1\n",
" Institution: NASA Global Modeling and Assimilation ...\n",
" References: http://gmao.gsfc.nasa.gov\n",
" ... ...\n",
" Contact: http://gmao.gsfc.nasa.gov\n",
" identifier_product_doi: 10.5067/VJAFPLI1CSIV\n",
" RangeBeginningDate: 1980-01-01\n",
" RangeBeginningTime: 00:00:00.000000\n",
" RangeEndingDate: 1980-01-01\n",
" RangeEndingTime: 23:59:59.000000\n"
]
}
],
"source": [
"import earthaccess\n",
"import xarray as xr\n",
"\n",
"# This will work if Earthdata prerequisite files have already been generated\n",
"auth = earthaccess.login()\n",
"\n",
"# To download multiple files, change the second temporal parameter\n",
"results = earthaccess.search_data(\n",
" short_name=\"M2T1NXSLV\",\n",
" version='5.12.4',\n",
" temporal=('1980-01-01', '1980-01-01'), # This will stream one granule, but can be edited for a longer temporal extent\n",
" bounding_box=(-180, 0, 180, 90)\n",
")\n",
"\n",
"# Download granules to local path\n",
"downloaded_files = earthaccess.download(\n",
" results,\n",
" local_path='.', # Change this string to download to a different path\n",
")\n",
"\n",
"# OPTIONAL: Open granules using Xarray\n",
"ds = xr.open_mfdataset(downloaded_files)\n",
"print(ds)"
]
},
{
"cell_type": "markdown",
"id": "302361d1",
"metadata": {},
"source": [
"### Search and Stream Granules Using `earthaccess` \n",
"\n",
"The `earthaccess` library has the ability to \"stream\" the full data of a granule, or multiple granules, to an Xarray dataset object, without having to download granule data before opening in your current notebook session.\n",
"\n",
"***Please note that this will stream the full granule data including every variable to this notebook, which may take extra time and computational resources***. To access one variable at a time or perform subsetting before the data is streamed to the notebook, please access data from an OPeNDAP server, by following the steps in the next section of this notebook."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "c9486fe9",
"metadata": {},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "2a0ed7581ee04204869491ba4e533826",
"version_major": 2,
"version_minor": 0
},
"text/plain": [
"QUEUEING TASKS | : 0%| | 0/1 [00:00\n",
"Dimensions: (lon: 576, lat: 361, time: 24)\n",
"Coordinates:\n",
" * lon (lon) float64 -180.0 -179.4 -178.8 -178.1 ... 178.1 178.8 179.4\n",
" * lat (lat) float64 -90.0 -89.5 -89.0 -88.5 ... 88.5 89.0 89.5 90.0\n",
" * time (time) datetime64[ns] 1980-01-01T00:30:00 ... 1980-01-01T23:30:00\n",
"Data variables: (12/47)\n",
" CLDPRS (time, lat, lon) float32 dask.array\n",
" CLDTMP (time, lat, lon) float32 dask.array\n",
" DISPH (time, lat, lon) float32 dask.array\n",
" H1000 (time, lat, lon) float32 dask.array\n",
" H250 (time, lat, lon) float32 dask.array\n",
" H500 (time, lat, lon) float32 dask.array\n",
" ... ...\n",
" V250 (time, lat, lon) float32 dask.array\n",
" V2M (time, lat, lon) float32 dask.array\n",
" V500 (time, lat, lon) float32 dask.array\n",
" V50M (time, lat, lon) float32 dask.array\n",
" V850 (time, lat, lon) float32 dask.array\n",
" ZLCL (time, lat, lon) float32 dask.array\n",
"Attributes: (12/30)\n",
" History: Original file generated: Sat May 31 17...\n",
" Comment: GMAO filename: d5124_m2_jan79.tavg1_2d...\n",
" Filename: MERRA2_100.tavg1_2d_slv_Nx.19800101.nc4\n",
" Conventions: CF-1\n",
" Institution: NASA Global Modeling and Assimilation ...\n",
" References: http://gmao.gsfc.nasa.gov\n",
" ... ...\n",
" Contact: http://gmao.gsfc.nasa.gov\n",
" identifier_product_doi: 10.5067/VJAFPLI1CSIV\n",
" RangeBeginningDate: 1980-01-01\n",
" RangeBeginningTime: 00:00:00.000000\n",
" RangeEndingDate: 1980-01-01\n",
" RangeEndingTime: 23:59:59.000000\n"
]
}
],
"source": [
"import earthaccess\n",
"import xarray as xr\n",
"\n",
"# This will work if Earthdata prerequisite files have already been generated\n",
"auth = earthaccess.login()\n",
"\n",
"# We recommend only streaming a few granules at a time, as some collections can be quite large\n",
"results = earthaccess.search_data(\n",
" short_name=\"M2T1NXSLV\",\n",
" version='5.12.4',\n",
" temporal=('1980-01-01', '1980-01-01'), # This will stream one granule, but can be edited for a longer temporal extent\n",
" bounding_box=(-180, 0, 180, 90)\n",
")\n",
"\n",
"fs = earthaccess.open(results) # Extracts URLs from the results variable\n",
"\n",
"# The open_mfdataset() function must be used when opening one or multiple granules with earthaccess\n",
"ds = xr.open_mfdataset(fs) # Opens the granules and concatenates them along the time dimension\n",
"print(ds)\n"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "oRj2te56DwTr",
"metadata": {
"id": "oRj2te56DwTr"
},
"source": [
"### Search, Subset, and Stream Granule Data From OPeNDAP Servers \n",
"\n",
"Rather than having to download or stream an entire granule, you can access data from an OPeNDAP server, which will allow you to view dataset metadata and subset single or multiple varibles before its data is streamed to the current notebook session."
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "185538db",
"metadata": {},
"source": [
"#### Option 1: Subset URLs Using `xarray` and `pydap` \n",
"\n",
"The `xarray` library offers a suite of various data computation, subsetting, and plotting capabilities, and can perform subsetting operations on OPeNDAP-enabled granules, as long as the user has either a `.edl_token` or a valid Earthdata username and password. This method utilizes the `pydap` engine to handle newer DAP4-protocol Cloud OPeNDAP URLs, and authenticate using either a token, or prompting for a username and password. For more information and NASA Earthdata OPeNDAP data access guides, please visit the `pydap` documentation [here](https://pydap.github.io/pydap/en/intro.html).\n",
"\n",
"In the code snippet below, OPeNDAP URLs are queried and parsed from the CMR using the `earthaccess` library. Next, a DAP4 constraint expression will be appended to each URL if you wish to only access a few variables at a time. Variables and their group syntax for each OPeNDAP-enabled collection can be found by following [this guide](https://disc.gsfc.nasa.gov/information/documents?keywords=opendap&title=OPeNDAP%20In%20The%20Cloud). After, you can choose between two authentication methods: being prompted for your Earthdata username and password, or by using a `.edl_token` file. Finally, the granules are opened in `Xarray` using the `pydap` engine, and a latitude/longitude subset is made using `xarray`, further demonstrating the subsetting capabilities of OPeNDAP URLs.\n",
"\n",
"**Warning:** When accessing data from OPeNDAP servers using a `.netrc` file, rather than the authentication methods demonstrated below, you will experience errors if your `.dodsrc` prerequisite file is not generated and properly stored in addition to your `.netrc` file. Finally, the `session` parameter will need to be removed from the `open_mfdataset` command.\n",
"\n",
"If you wish to save the subsetted granule locally, please use the `to_dataset` function, documented here: https://docs.xarray.dev/en/latest/generated/xarray.Dataset.to_netcdf.html\n"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "983bf113",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "iVBORw0KGgoAAAANSUhEUgAAAjIAAAHHCAYAAACle7JuAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjAsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvlHJYcgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAo1lJREFUeJzsnXd4FdX2978zp+WkJ5BCCQEsFGkCikF/gFJFKZarIgoqilcBKYLKRUVUBCtgo4mAvmCHq3K9KCpdRERQUUBAFJAEkJCeU2e/f+TmkL1myGkhITnr8zznedgze3abPcPK7P1dSxFCCDAMwzAMw9RC1JpuAMMwDMMwTKiwIcMwDMMwTK2FDRmGYRiGYWotbMgwDMMwDFNrYUOGYRiGYZhaCxsyDMMwDMPUWtiQYRiGYRim1sKGDMMwDMMwtRY2ZBiGYRiGqbWwIcOERNOmTXHHHXfUdDMYhmGYCIcNGeaMfPPNN3jiiSeQl5dX002pVoqKijB16lT069cPycnJUBQFS5YsOWP+V199Fa1atYLNZkOjRo0wYcIEFBcX6/JlZ2dj5MiRaNasGex2O8477zxMmDABJ0+e1OXdvXs3+vXrh9jYWCQnJ+P222/HiRMnAu6D0+nEww8/jIYNG8Jut6NLly5Ys2aNLt8XX3yBESNGoE2bNjCZTGjatGnAdZyNupo2bQpFUfz+Kt6PTz75BB07dkRUVBSaNGmCqVOnwuPx6MrOy8vDyJEjkZKSgpiYGFx55ZX44YcfAurj0aNHcdttt6FFixaIi4tDYmIiLr30UixduhRGUV7++usv3HTTTUhMTER8fDwGDRqE33//PaC6gMDHFCh7Tq+44gpER0cjPT0dDzzwAIqKigKui2FqPYJhzsDzzz8vAIiDBw/qzjkcDuFyuaq/UdXAwYMHBQDRpEkT0aNHDwFALF682DDvQw89JACIG2+8UcydO1eMGTNGmM1m0adPHylfYWGhyMzMFPXr1xePP/64WLhwoRg9erSwWCyiQ4cOwuv1+vIePnxY1K9fX5x33nlizpw5Yvr06SIpKUm0b99eOJ3OgPpwyy23CLPZLCZOnCjmz58vsrKyhNlsFhs3bpTyDR8+XERFRYmuXbuKxo0bi8zMzKDGqqrrWrlypXj77bd9vyFDhggAYtasWdLxAwcOCCGE+Oyzz4SiKOLKK68UCxYsEGPGjBGqqop//vOfUrler1d07dpVxMTEiCeeeEK8+uqronXr1iIuLk789ttvfvv4448/iu7du4t//etfYt68eeKVV14RAwcOFADE5MmTpbyFhYXiggsuEKmpqeLZZ58VL730ksjIyBCNGzcWf//9d5WO6Y4dO0RUVJS4+OKLxdy5c8WUKVOEzWYT/fr1C6gehqkLsCHDnJHKDJm6jMPhENnZ2UIIIbZt23ZGQ+bo0aPCbDaL22+/XTr+yiuvCADik08+8R1btmyZACBWrVol5X388ccFAPHDDz/4jt13333CbreLP//803dszZo1AoCYP3++3/Zv3bpVABDPP/+871hpaak477zzRFZWlpT3r7/+8hmk11xzTdCGzNmuy98cbN26tWjfvr1wu92+Y1OmTBGKoojdu3f7jr333nsCgPjggw98x44fPy4SExPFkCFDAumqIddee62IiYkRHo/Hd+zZZ58VAMR3333nO7Z7925hMpl0Ro8RwYzp1VdfLRo0aCDy8/N9xxYuXCgAiM8//zzkfjFMbYKXlhhDnnjiCUyaNAkA0KxZM98n/T/++AOAfo/MkiVLoCgKNm3ahAceeAApKSlITEzEvffeC5fLhby8PAwbNgxJSUlISkrCQw89pPskr2kaZs+ejYsuughRUVFIS0vDvffei1OnTlVXtwEANpsN6enpfvNt2bIFHo8Ht9xyi3S8PP3uu+/6jhUUFAAA0tLSpLwNGjQAANjtdt+xjz76CNdeey2aNGniO9arVy9ceOGFeP/99/2268MPP4TJZMLIkSN9x6KiojBixAhs2bIFhw8f9h1v2LAhLBaL3zLPhboov/76K3799VeMHDkSZrPZd/z++++HEAIffvih1M60tDRcf/31vmMpKSm46aab8PHHH8PpdPqOZ2dnY8+ePXC73X7b0LRpU5SUlMDlckl1XXLJJbjkkkt8x1q2bImePXvq7t+hQ4ewZ88e6VigY1pQUIA1a9bgtttuQ3x8vC/vsGHDEBsbG9BcYZi6ABsyjCHXX389hgwZAgCYNWsW3n77bbz99ttISUmp9LoxY8Zg3759mDZtGgYOHIgFCxbgsccew4ABA+D1evHMM8/giiuuwPPPP4+3335buvbee+/FpEmTcPnll2POnDm48847sWzZMvTt29fvfypOpxN///13QL+qovw/v4pGCABER0cDALZv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SNiQYRiGYRim1sKGDMMwDMMwtRY2ZBiGYRiGqbWwIcMwDMMwTK2FDRmGYRiGYWotbMgwDMMwDFNrYUOGqRX06NED48aNq1P13nHHHRg8eHBYZTRt2tQXaC8vL++M+ZYsWYLExMSw6mLOzB133OG7D//+979rujkME1GwIcMwlbBixQo89dRTvnTTpk0xe/bsmmuQAU8++SSys7ORkJBQ002p86xbt87QaJwzZ06diEzNMLURDhrJMJWQnJxc003wS1xc3DkT6bdi8L5IIiEhgQ1Jhqkh+IsMUys5deoUhg0bhqSkJERHR+Pqq6/Gvn37fOfLl1I+//xztGrVCrGxsejXr5/0V7PH48EDDzyAxMRE1KtXDw8//DCGDx8uLfdUXFrq0aMH/vzzT4wfP963jAAATzzxBDp06CC1b/bs2WjatKkv7fV6MWHCBF9dDz30EGh0EE3TMGPGDDRr1gx2ux3t27fHhx9+GNL4LFmyBE2aNEF0dDSuu+46nDx5Upfn448/RseOHREVFYXmzZtj2rRp8Hg8vvN79uzBFVdcgaioKLRu3RpffvmltHTyxx9/QFEUvPfee+jevTuioqKwbNkyAMAbb7yBVq1aISoqCi1btsTrr78u1X348GHcdNNNSExMRHJyMgYNGoQ//vjDd37dunW49NJLERMTg8TERFx++eX4888/A+q7v3699NJLaNu2LWJiYpCRkYH7778fRUVFvvN//vknBgwYgKSkJMTExOCiiy7CZ599hj/++ANXXnklACApKQmKouCOO+4IqE0Mw5w92JBhaiV33HEHvv/+e3zyySfYsmULhBDo378/3G63L09JSQleeOEFvP3229iwYQMOHTqEiRMn+s4/++yzWLZsGRYvXozNmzejoKCg0v0NK1asQOPGjX1LOcEsJbz44otYsmQJ3nzzTWzatAm5ublYuXKllGfGjBl46623MG/ePPzyyy8YP348brvtNqxfvz7wgQGwdetWjBgxAqNHj8bOnTtx5ZVX4umnn5bybNy4EcOGDcPYsWPx66+/Yv78+ViyZAmmT58OoMzwGjx4MKKjo7F161YsWLAAU6ZMMazvkUcewdixY7F792707dsXy5Ytw+OPP47p06dj9+7deOaZZ/DYY49h6dKlAMq+2vTt2xdxcXHYuHEjNm/e7DM0XS4XPB4PBg8ejO7du+Onn37Cli1bMHLkSJ/hWBn++gUAqqri5Zdfxi+//IKlS5fi66+/xkMPPeQ7P2rUKDidTmzYsAE///wznn32WcTGxiIjIwMfffQRAGDv3r3Izs7GnDlzgro3DMOcBWo2ZiXDBEb37t3F2LFjhRBC/PbbbwKA2Lx5s+/833//Lex2u3j//feFEEIsXrxYABD79+/35XnttddEWlqaL52Wliaef/55X9rj8YgmTZqIQYMGGdYrhBCZmZli1qxZUtumTp0q2rdvLx2bNWuWFMm8QYMG4rnnnvOl3W63aNy4sa8uh8MhoqOjxTfffCOVM2LECDFkyJAzjotRe4YMGSL69+8vHbv55ptFQkKCL92zZ0/xzDPPSHnefvtt0aBBAyGEEP/973+F2WwW2dnZvvNr1qwRAMTKlSuFEEIcPHhQABCzZ8+WyjnvvPPE8uXLpWNPPfWUyMrK8tXTokULoWma77zT6RR2u118/vnn4uTJkwKAWLdu3Rn7fSb89cuIDz74QNSrV8+Xbtu2rXjiiScM865du1YAEKdOnTI8X3F8GIapHniPDFPr2L17N8xmM7p06eI7Vq9ePbRo0QK7d+/2HYuOjsZ5553nSzdo0ADHjx8HAOTn5+PYsWO49NJLfedNJhM6deoETdOqtL35+fnIzs6W2ms2m9G5c2ff8tL+/ftRUlKC3r17S9e6XC5cfPHFQdW3e/duXHfdddKxrKwsrF692pf+8ccfsXnzZulLhdfrhcPhQElJCfbu3YuMjAxp703FsapI586dff8uLi7GgQMHMGLECNxzzz2+4x6Px7eH5Mcff8T+/fsRFxcnleNwOHDgwAH06dMHd9xxB/r27YvevXujV69euOmmm9CgQQO/fffXr+joaHz55ZeYMWMG9uzZg4KCAng8Hun8Aw88gPvuuw9ffPEFevXqhRtuuAHt2rXzWzfDMDUDGzJMnYVuOlUURbcvpSpQVVVXbsUlrkAo36Pxn//8B40aNZLO2Wy28Bp4hvqmTZuG66+/XncuKioqqLJiYmKkcgFg4cKFkuEGlBmK5Xk6derk209TkZSUFADA4sWL8cADD2D16tV477338Oijj2LNmjW47LLLwurXH3/8gWuvvRb33Xcfpk+fjuTkZGzatAkjRoyAy+VCdHQ07r77bvTt2xf/+c9/8MUXX2DGjBl48cUXMWbMmKDGhWGY6oENGabW0apVK3g8HmzduhVdu3YFAJw8eRJ79+5F69atAyojISEBaWlp2LZtG7p16wag7C/3H374QbdxtyJWqxVer1c6lpKSgpycHAghfPs4du7cKdXVoEEDbN261VeXx+PB9u3b0bFjRwBA69atYbPZcOjQIXTv3j2gPpyJVq1aYevWrdKxb7/9Vkp37NgRe/fuxfnnn29YRosWLXD48GEcO3YMaWlpAIBt27b5rTstLQ0NGzbE77//jqFDhxrm6dixI9577z2kpqYiPj7+jGVdfPHFuPjiizF58mRkZWVh+fLlfg0Zf/3avn07NE3Diy++CFUt2yL4/vvv6/JlZGTgn//8J/75z39i8uTJWLhwIcaMGQOr1QoAujnAMEzNwYYMU+u44IILMGjQINxzzz2YP38+4uLi8Mgjj6BRo0YYNGhQwOWMGTMGM2bMwPnnn4+WLVvilVdewalTpyrdVNq0aVNs2LABt9xyC2w2G+rXr48ePXrgxIkTeO6553DjjTdi9erV+O9//yv9Jz127FjMnDkTF1xwAVq2bImXXnpJ8kUSFxeHiRMnYvz48dA0DVdccQXy8/OxefNmxMfHY/jw4QH364EHHsDll1+OF154AYMGDcLnn38uLSsBwOOPP45rr70WTZo0wY033ghVVfHjjz9i165dePrpp9G7d2+cd955GD58OJ577jkUFhbi0UcfBQC/m26nTZuGBx54AAkJCejXrx+cTie+//57nDp1ChMmTMDQoUPx/PPPY9CgQXjyySfRuHFj/Pnnn1ixYgUeeughuN1uLFiwAAMHDkTDhg2xd+9e7Nu3D8OGDfPbd3/9Ov/88+F2u/HKK69gwIAB2Lx5M+bNmyeVMW7cOFx99dW48MILcerUKaxduxatWrUCAGRmZkJRFKxatQr9+/eH3W5HbGxswPeGYZizQM1u0WGYwKCbbnNzc8Xtt98uEhIShN1uF3379hW//fab7/zixYulza1CCLFy5UpRccq73W4xevRoER8fL5KSksTDDz8s/vGPf4hbbrnljPVu2bJFtGvXTthsNqmsuXPnioyMDBETEyOGDRsmpk+fLm32dbvdYuzYsSI+Pl4kJiaKCRMmiGHDhkkbizVNE7NnzxYtWrQQFotFpKSkiL59+4r169efcVyMNvsKIcSiRYtE48aNhd1uFwMGDBAvvPCCbjxWr14tunbtKux2u4iPjxeXXnqpWLBgge/87t27xeWXXy6sVqto2bKl+PTTTwUAsXr1aiHE6c2+O3bs0NW/bNky0aFDB2G1WkVSUpLo1q2bWLFihe98dna2GDZs2P9v7/51DQnjMI7/pqHRIajIqIQ7oHQBKhGJqAiJQqdTiOI09KKbG3ABtK6ASiT+NSKa0fPbYhN77K5kZTln3z3fTz/zzkymeDLzvO+rgUBAvV6v2ratlUpFXdfV/X6vuVxOI5GIejwejUaj2m639Xw+330Oj9xXv9/XSCRyfW8cx7kp8DYaDY3H4+r1ejUYDGqpVNLj8Xg9vtPpaDgcVsuytFwu34wtlH2BD2epvqA0ABjocrlIIpGQfD5/s5rvvywWi0mz2fyQ7Rum06lkMhlZLpc3JWr8YFmWjEajv956AsCfYx0ZfFmbzUaGw6EsFguZzWZSr9dltVpJsVj87Et7SKvVEp/PJ67rPvW8o9FIxuOxrNdrmUwmUq1WJZ1OE2J+o1ar8YsJ+CR8kcGXtdvtpFAoyHw+F1WVVColb29v10KuCTabzXWGlG3b1wLrMziOI91uV7bbrQQCAclms9Lr9cTv9z9tjEclk8m7K/wOBoO7BeNXOxwOcjqdROT7NP/3M7kAvBZBBoAx3ge3n4VCoV/WpgHw/yPIAAAAY9GRAQAAxiLIAAAAYxFkAACAsQgyAADAWAQZAABgLIIMAAAwFkEGAAAYiyADAACM9Q17D4o3M4TsPQAAAABJRU5ErkJggg==",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"import xarray as xr\n",
"import os\n",
"import earthaccess\n",
"import getpass\n",
"import requests\n",
"from pydap.net import create_session\n",
"%matplotlib inline\n",
"\n",
"# Create search query for 1980-01-01 Cloud OPeNDAP URL\n",
"results = earthaccess.search_data(\n",
" short_name=\"M2T1NXSLV\",\n",
" version='5.12.4',\n",
" temporal=('1980-01-01', '1980-01-01'), # This will stream one granule, but can be edited for a longer temporal extent\n",
" bounding_box=(-180, 0, 180, 90)\n",
")\n",
"\n",
"# Parse out URL from request, add to OPeNDAP URLs list for querying multiple granules with constraint expressions\n",
"opendap_urls = []\n",
"for item in results:\n",
" for urls in item['umm']['RelatedUrls']: # Iterate over RelatedUrls in each request step\n",
" if 'OPENDAP' in urls.get('Description', '').upper(): # Check if 'OPENDAP' is in the Description\n",
" # Extract OPeNDAP URL, replace \n",
" url = urls['URL'].replace('https', 'dap4')\n",
"\n",
" # Subset T2M, lat, lon, and time\n",
" # To view all variables, comment out these two lines\n",
" ce = \"?dap4.ce=/{}%3B/{}%3B/{}%3B/{}\".format(\"T2M\", \"lat\", \"lon\", \"time\")\n",
" url = url + ce\n",
"\n",
" # Add URL to list\n",
" opendap_urls.append(url)\n",
"\n",
"# Use netrc file to authenticate\n",
"my_session = create_session()\n",
"\n",
"# Uncomment the following block to use the .edl_token method instead of a netrc file\n",
"'''\n",
"# Set file path to root\n",
"token_file_path = os.path.join(os.path.expanduser(\"~\"), \".edl_token\")\n",
"\n",
"# Read the token from the .edl_token file\n",
"with open(token_file_path, 'r') as token_file:\n",
" token = token_file.read().strip() # Ensure to strip any newlines or extra spaces\n",
" my_session = create_session(session_kwargs={\"token\": token})\n",
"'''\n",
"\n",
"try:\n",
" # Load dataset object and metadata, but don't open the values yet\n",
" # NOTE: When opening HDF files, the group to be accessed must be specified with the \"group=\" parameter. \n",
" # E.g., for GPM IMERG, group=\"Grid\" must be entered or an error will occur\n",
" # Remove the session parameter if you are just using a .netrc file to authenticate\n",
" ds = xr.open_mfdataset(opendap_urls, engine=\"pydap\", session=my_session)\n",
"except OSError as e:\n",
" print('Error', e)\n",
" print('Please check that your .edl_token file exists and is valid, or that your username/password were entered correctly.')\n",
" raise\n",
"\n",
"# Define latitude and longitude bounds for CONUS\n",
"lat_min, lat_max = 25, 50 # Latitude bounds\n",
"lon_min, lon_max = -125, -66 # Longitude bounds\n",
"\n",
"# Subset the dataset based on lat/lon bounds, which is performed server-side\n",
"ds_conus = ds.sel(lat=slice(lat_min, lat_max), lon=slice(lon_min, lon_max))\n",
"\n",
"# Plot the first timestep of the 2-meter temperature variable from the subsetted dataset\n",
"ds_conus['T2M'].isel(time=0).plot(cmap='coolwarm')"
]
},
{
"cell_type": "markdown",
"id": "8c39cf00",
"metadata": {},
"source": [
"#### Option 2: Search, Subset, and Stream Using `netcdf4-python` \n",
"\n",
"`netCDF4-python` is a Python library that uses the [netCDF-c](https://github.com/Unidata/netcdf-c) library to open and read netCDF4 files. It can be used to remotely access OPeNDAP-enabled netCDF4 granules. Similar to the above examples, this code block will query a MERRA-2 1980-01-01 granule, create a constraint expression subsetting `T2M`, `lat`, and `lon`, before opening with the `netcdf4-python` library.\n",
"\n",
"**Warning:** When accessing data from OPeNDAP servers using `netcdf4-python`, you will experience errors if your `.dodsrc` prerequisite file is not generated and properly stored in addition to your `.netrc` file."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "62af191c",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[[244.07703 244.07703 244.07703 ... 244.07703 244.07703 244.07703]\n",
" [244.01453 244.02234 244.03015 ... 243.99109 243.9989 244.00671]\n",
" [244.55359 244.5614 244.57703 ... 244.52234 244.53015 244.54578]\n",
" ...\n",
" [253.21375 253.22156 253.22937 ... 253.19226 253.20007 253.20789]\n",
" [253.93445 253.9364 253.9403 ... 253.92468 253.92859 253.93054]\n",
" [254.40125 254.40125 254.40125 ... 254.40125 254.40125 254.40125]]\n",
"\n",
" [[243.79819 243.79819 243.79819 ... 243.79819 243.79819 243.79819]\n",
" [243.88412 243.89194 243.89975 ... 243.85287 243.86069 243.87631]\n",
" [244.56381 244.57944 244.58725 ... 244.54037 244.54819 244.556 ]\n",
" ...\n",
" [252.97006 252.97787 252.9896 ... 252.94272 252.95053 252.96225]\n",
" [253.75717 253.75912 253.76303 ... 253.7474 253.75131 253.75327]\n",
" [254.31381 254.31381 254.31381 ... 254.31381 254.31381 254.31381]]\n",
"\n",
" [[243.5383 243.5383 243.5383 ... 243.5383 243.5383 243.5383 ]\n",
" [243.75705 243.76486 243.77267 ... 243.73361 243.74142 243.74924]\n",
" [244.61642 244.62424 244.63205 ... 244.59299 244.6008 244.60861]\n",
" ...\n",
" [252.69064 252.70236 252.71408 ... 252.65549 252.6672 252.67892]\n",
" [253.55392 253.55783 253.56174 ... 253.54611 253.55002 253.55392]\n",
" [254.21408 254.21408 254.21408 ... 254.21408 254.21408 254.21408]]\n",
"\n",
" ...\n",
"\n",
" [[243.48914 243.48914 243.48914 ... 243.48914 243.48914 243.48914]\n",
" [243.7157 243.72351 243.73132 ... 243.68445 243.69226 243.70007]\n",
" [244.4657 244.48132 244.50476 ... 244.4032 244.41882 244.44226]\n",
" ...\n",
" [247.75085 247.75085 247.74695 ... 247.76257 247.75867 247.75476]\n",
" [248.72742 248.72351 248.7196 ... 248.73523 248.73132 248.72742]\n",
" [249.1571 249.1571 249.1571 ... 249.1571 249.1571 249.1571 ]]\n",
"\n",
" [[243.43158 243.43158 243.43158 ... 243.43158 243.43158 243.43158]\n",
" [243.68939 243.70502 243.71283 ... 243.65814 243.67377 243.68158]\n",
" [244.46283 244.48627 244.50189 ... 244.40814 244.43158 244.4472 ]\n",
" ...\n",
" [247.65424 247.65033 247.65033 ... 247.65814 247.65814 247.65424]\n",
" [248.72455 248.72064 248.71674 ... 248.73236 248.72845 248.72455]\n",
" [249.17377 249.17377 249.17377 ... 249.17377 249.17377 249.17377]]\n",
"\n",
" [[243.38226 243.38226 243.38226 ... 243.38226 243.38226 243.38226]\n",
" [243.6557 243.66351 243.67133 ... 243.62445 243.64008 243.64789]\n",
" [244.45258 244.4682 244.48383 ... 244.39789 244.41351 244.42914]\n",
" ...\n",
" [247.49554 247.49554 247.49554 ... 247.49554 247.49554 247.49554]\n",
" [248.66351 248.6596 248.6596 ... 248.66742 248.66742 248.66351]\n",
" [249.14398 249.14398 249.14398 ... 249.14398 249.14398 249.14398]]]\n"
]
}
],
"source": [
"import netCDF4 as nc4\n",
"import earthaccess\n",
"\n",
"# Create search query for 1980-01-01 Cloud OPeNDAP URL\n",
"results = earthaccess.search_data(\n",
" short_name=\"M2T1NXSLV\",\n",
" version='5.12.4',\n",
" temporal=('1980-01-01', '1980-01-01'), # This will stream one granule, but can be edited for a longer temporal extent\n",
" bounding_box=(-180, 0, 180, 90)\n",
")\n",
"\n",
"# Authenticate with earthaccess\n",
"auth = earthaccess.login()\n",
"\n",
"# Parse out URL from request, add to OPeNDAP URLs list for querying multiple granules\n",
"opendap_urls = []\n",
"for item in results:\n",
" for urls in item['umm']['RelatedUrls']: # Iterate over RelatedUrls in each request step\n",
" if 'OPENDAP' in urls.get('Description', '').upper(): # Check if 'OPENDAP' is in the Description\n",
" # Extract OPeNDAP URL\n",
" url = urls['URL']\n",
" # Add URL to list\n",
" opendap_urls.append(url)\n",
"\n",
"try:\n",
" # Open the dataset (be sure to specify the correct dimension for aggregation)\n",
" nc = nc4.MFDataset(opendap_urls, aggdim=\"time\")\n",
" # Stream the 2-meter temperature variable\n",
" print(nc['T2M'][:])\n",
"except OSError as e:\n",
" print('Error', e)\n",
" print('Please check that your .dodsrc files are in their correct locations, or that your .netrc file has the correct username and password.')\n",
" raise"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "c938f838",
"metadata": {},
"source": [
"### Search, Subset, and Stream Granule Data from THREDDS Servers Using Xarray \n",
"\n",
"Datasets that include .ncml aggregation, like some provided through THREDDS, may be useful for quickly subsetting multiple granules into a single data array.\n",
"\n",
"This operation requires a .dodsrc file in your root and working directories, and a .netrc file in your root directory. Running `auth = earthaccess.login()` will create both of these files, and can be removed after the first run, or can be removed entirely if these files are already present.\n",
"\n",
"To find the THREDDS URLs, please visit the dataset landing page for your desired collection, and from the \"Web Services\" dropdown, select \"THREDDS Data\". The dataset landing page for the collection below can be found [here](https://disc.gsfc.nasa.gov/datasets/M2T1NXSLV_5.12.4/summary?keywords=M2T1NXSLV_5.12.4).\n",
"\n",
"**Warning:** Please use a reasonable spatiotemporal subset when calling from THREDDS servers. Subsets that are too large will cause data access errors, or rate limiting on your IP address.\n",
"\n",
"We recommend using the `xarray` library when interacting with THREDDS URLs, due to its built-in authentication and subsetting capabilities."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "89f27aa7",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"[1080 values with dtype=float32]\n",
"Coordinates:\n",
" * lon (lon) float64 -88.75 -88.12 -87.5\n",
" * lat (lat) float64 41.0 41.5 42.0 42.5 43.0\n",
" * time (time) datetime64[ns] 1980-01-01T00:30:00 ... 1980-01-03T23:30:00\n",
"Attributes:\n",
" long_name: 2-meter_air_temperature\n",
" units: K\n",
" fmissing_value: 1000000000000000.0\n",
" standard_name: 2-meter_air_temperature\n",
" vmax: 1000000000000000.0\n",
" vmin: -1000000000000000.0\n",
" valid_range: [-1.e+15 1.e+15]\n",
" _ChunkSizes: [ 1 91 144]\n"
]
}
],
"source": [
"import xarray as xr\n",
"import earthaccess\n",
"\n",
"# This will work if Earthdata prerequisite files have already been generated\n",
"auth = earthaccess.login()\n",
"\n",
"# Subsetting a .ncml file URL:\n",
"URL = 'https://goldsmr4.gesdisc.eosdis.nasa.gov/thredds/dodsC/MERRA2_aggregation/M2T1NXSLV.5.12.4/M2T1NXSLV.5.12.4_Aggregation_1980.ncml'\n",
"\n",
"lat_slice = slice(41, 43)\n",
"lon_slice = slice(-89, -87)\n",
"time_slice = slice('1980-01-01', '1980-01-03') # Create a 3-day subset\n",
"\n",
"try:\n",
" # Access the THREDDS server ncml file, which will handle subset requests\n",
" ds = xr.open_dataset(URL)\n",
" # Send the subset request and stream data to the notebook using the bounding box and time slice\n",
" ds_subset = ds.sel(lat=lat_slice,lon=lon_slice,time=time_slice)\n",
" # Open the 2-meter temperature variable\n",
" print(ds_subset['T2M'])\n",
"except OSError as e:\n",
" print('Error', e)\n",
" print('Please check that your .dodsrc files are in their correct locations, or that your .netrc file has the correct username and password.')\n",
" raise"
]
},
{
"cell_type": "markdown",
"id": "4a840465",
"metadata": {},
"source": [
"### Search, Subset, and Stream Granule Data from the Level 3/4 Subsetter and Regridder API \n",
"\n",
"The Level 3/4 Subsetter and Regridder is a service offered by GES DISC that can subset and regrid various Level 3 and 4 collections. It has an API that can be accessed programmatically to accept the subset request, and its results will be returned to the notebook for downloading.\n",
"\n",
"#### Please visit [this how-to](https://disc.gsfc.nasa.gov/information/howto?keywords=level%203&title=How%20to%20Use%20the%20Web%20Services%20API%20for%20Subsetting%20MERRA-2%20Data) for more information."
]
},
{
"cell_type": "markdown",
"id": "d68e1bb8",
"metadata": {},
"source": []
}
],
"metadata": {
"colab": {
"collapsed_sections": [],
"name": "Data_Access_Using_Python_Draft",
"provenance": []
},
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.18"
}
},
"nbformat": 4,
"nbformat_minor": 5
}