Downloading and Reading NASA Precipitation Datasets

In this page we show how you can download data for a given NASAPrecipitation dataset.

Setup

using NASAPrecipitation
using CairoMakie
using DelimitedFiles

download("https://raw.githubusercontent.com/natgeo-wong/GeoPlottingData/main/coastline_resl.txt","coast.cst")
coast = readdlm("coast.cst",comments=true)
clon  = coast[:,1]
clat  = coast[:,2]
nothing

Required dependencies

Since we are downloading from NASA's EOSDIS OPeNDAP servers, you are required to perform the following:

1. You need to register an account with Earthdata and allow access to the NASA EOSDISC on it.
2. Create a .netrc file with the following information: machine urs.earthdata.nasa.gov login <your login> password <your password>
3. Create a .dodsrc file with the following lines: (1) HTTP.COOKIEJAR=/<home directory>/.urs_cookies and (2) HTTP.NETRC=/<home directory>/.netrc

If this sounds complicated however, fear not! You need only perform the first step yourself (i.e. create your own account), for NASAPrecipitation.jl will automatically set up the .dodsrc file (if you don't already have one), and once you have your <login> and <password>, you can use the function setup() to set up your .netrc file.

setup(
    login = <username>
    password = <password>
)

Downloading NASAPrecipitationDatasets

Downloading NASA Precipitation data is as simple as

npd = NASAPrecipitationDataset(args...)
geo = GeoRegion(args...)
download(npd,geo)

Let us download the IMERGMonthly Dataset for 2020 over the Caribbean (as defined by the AR6 IPCC), for example

npd = IMERGMonthly(start=Date(2020),stop=Date(2020))
geo = GeoRegion("AR6_CAR")
lsd = getLandSea(npd,geo)
download(npd,geo)

[ Info: 2024-02-17T00:56:24.978 - NASAPrecipitation.jl - Setting up data structure containing information on IMERG Monthly data to be downloaded
[ Info: 2024-02-17T00:56:25.147 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID AR6_CAR
[ Info: 2024-02-17T00:56:28.281 - NASAPrecipitation.jl - Checking to see if the specified GeoRegion "AR6_CAR" is within the "IMERG" GeoRegion
[ Info: 2024-02-17T00:56:28.281 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID IMERG
[ Info: 2024-02-17T00:56:28.355 - GeoRegions.jl - Performing a check to determine if the Caribbean GeoRegion (AR6_CAR) is inside the Global IMERG Dataset GeoRegion (IMERG)
[ Info: 2024-02-17T00:56:28.355 - GeoRegions.jl - The GeoRegion AR6_CAR (Caribbean) is indeed a subset of the GeoRegion IMERG (Global IMERG Dataset)
[ Info: 2024-02-17T00:56:28.356 - NASAPrecipitation.jl - The IMERG Land-Sea mask dataset for the "AR6_CAR" GeoRegion is not available, extracting from Global IMERG Land-Sea mask dataset ...
[ Info: 2024-02-17T00:56:28.356 - NASAPrecipitation.jl - The Global IMERG Land-Sea mask dataset for the "AR6_CAR" GeoRegion is not available, downloading from the NASA OPeNDAP servers ...
[ Info: 2024-02-17T00:56:28.391 - NASAPrecipitation.jl - Retrieving the original IMERG Land-Sea Mask data from NASA's EOSDIS OPeNDAP servers
[ Info: 2024-02-17T00:56:30.224 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID IMERG
[ Info: 2024-02-17T00:56:33.431 - GeoRegions.jl - Creating a RegionGrid for the Caribbean GeoRegion
[ Info: 2024-02-17T00:56:33.431 - GeoRegions.jl - Creating vector of latitude indices to extract ...
[ Info: 2024-02-17T00:56:33.431 - GeoRegions.jl - Creating vector of longitude indices to extract ...
[ Info: 2024-02-17T00:56:33.431 - GeoRegions.jl - Since the Caribbean GeoRegion is a PolyRegion, we need to defined a mask as well ...
[ Info: 2024-02-17T00:56:33.857 - NASAPrecipitation.jl - Extracting regional IMERG Land-Sea mask for the "AR6_CAR" GeoRegion from the Global IMERG Land-Sea mask dataset ...
[ Info: 2024-02-17T00:56:34.359 - NASAPrecipitation.jl - Retrieving the regional IMERG Land-Sea mask for the "AR6_CAR" GeoRegion ...
[ Info: 2024-02-17T00:56:36.676 - NASAPrecipitation.jl - Downloading IMERGv7 Monthly data for the Caribbean GeoRegion from 2020-01-01 to 2020-12-31
[ Info: 2024-02-17T00:56:36.676 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID IMERG
[ Info: 2024-02-17T00:56:36.677 - GeoRegions.jl - Performing a check to determine if the Caribbean GeoRegion (AR6_CAR) is inside the Global IMERG Dataset GeoRegion (IMERG)
[ Info: 2024-02-17T00:56:36.677 - GeoRegions.jl - The GeoRegion AR6_CAR (Caribbean) is indeed a subset of the GeoRegion IMERG (Global IMERG Dataset)
[ Info: 2024-02-17T00:56:36.677 - GeoRegions.jl - Creating a RegionGrid for the Caribbean GeoRegion
[ Info: 2024-02-17T00:56:36.678 - GeoRegions.jl - Creating vector of latitude indices to extract ...
[ Info: 2024-02-17T00:56:36.678 - GeoRegions.jl - Creating vector of longitude indices to extract ...
[ Info: 2024-02-17T00:56:36.678 - GeoRegions.jl - Since the Caribbean GeoRegion is a PolyRegion, we need to defined a mask as well ...
[ Info: 2024-02-17T00:56:36.679 - NASAPrecipitation.jl - Preallocating temporary arrays for extraction of IMERGv7 Monthly data for the Caribbean GeoRegion from the original gridded dataset
[ Info: 2024-02-17T00:56:36.679 - NASAPrecipitation.jl - Downloading IMERGv7 Monthly data for the Caribbean GeoRegion from the NASA Earthdata servers using OPeNDAP protocols for 2020 ...
[ Info: 2024-02-17T00:56:44.952 - NASAPrecipitation.jl - Saving IMERGv7 Monthly data in the Caribbean GeoRegion for 2020-01-01
[ Info: 2024-02-17T00:56:44.952 - NASAPrecipitation.jl - Creating NetCDF file /home/runner/imergv7monthly/AR6_CAR/imergv7monthly-AR6_CAR-2020.nc ...
[ Info: 2024-02-17T00:56:45.970 - NASAPrecipitation.jl - IMERGv7 Monthly data in the Caribbean GeoRegion for 2020-01-01 has been saved into /home/runner/imergv7monthly/AR6_CAR/imergv7monthly-AR6_CAR-2020.nc

Reading data for a downloaded NASAPrecipitationDataset

And now that you have downloaded the data, you can use the function read() to call the NCDataset that points towards the downloaded data.

ds = read(npd,geo,Date(2020))

Dataset: /home/runner/imergv7monthly/AR6_CAR/imergv7monthly-AR6_CAR-2020.nc
Group: /

Dimensions
   longitude = 350
   latitude = 130
   time = 12

Variables
  longitude   (350)
    Datatype:    Float32 (Float32)
    Dimensions:  longitude
    Attributes:
     units                = degrees_east
     long_name            = longitude

  latitude   (130)
    Datatype:    Float32 (Float32)
    Dimensions:  latitude
    Attributes:
     units                = degrees_north
     long_name            = latitude

  precipitation   (350 × 130 × 12)
    Datatype:    Float32 (Float32)
    Dimensions:  longitude × latitude × time
    Attributes:
     units                = kg m**-2 s**-1
     long_name            = precipitation_rate
     full_name            = Precipitation Rate

Global attributes
  AlgorithmVersion     = 3IMERGM_6.3
  AlgorithmID          = 3IMERGM
  doi                  = 10.5067/GPM/IMERG/3B-MONTH/07

As shown in the printout of the NCDataset, the precipitation data is saved under the field name precipitation, and is in units of kg m**-2 s**-1, or alternatively mm s**-1.

prcp = ds["precipitation"][:,:,:] * 3600
close(ds)

fig = Figure()
_,_,slon,slat = coordGeoRegion(geo)
aspect = (maximum(slon)-minimum(slon))/(maximum(slat)-minimum(slat))

ax = Axis(
    fig[1,1],width=350,height=350/aspect,
    title="February 2020",xlabel="Longitude / º",ylabel="Latitude / º",
    limits=(minimum(slon)-2,maximum(slon)+2,minimum(slat)-2,maximum(slat)+2)
)
contourf!(
    ax,lsd.lon,lsd.lat,prcp[:,:,2],colormap=:Blues,
    levels=range(0,0.5,length=11),extendlow=:auto,extendhigh=:auto
)
lines!(ax,clon,clat,color=:black)
lines!(ax,slon,slat,color=:red,linewidth=5)

ax = Axis(
    fig[1,2],width=350,height=350/aspect,
    title="August 2020",xlabel="Longitude / º",
    limits=(minimum(slon)-2,maximum(slon)+2,minimum(slat)-2,maximum(slat)+2)
)
contourf!(
    ax,lsd.lon,lsd.lat,prcp[:,:,8],colormap=:Blues,
    levels=range(0,0.5,length=11),extendlow=:auto,extendhigh=:auto
)
lines!(ax,clon,clat,color=:black)
lines!(ax,slon,slat,color=:red,linewidth=5)

hideydecorations!(ax, ticks = false,grid=false)

resize_to_layout!(fig)
fig

Where is the data saved to?

You can check where the data is saved to for a given dataset, georegion and datetime by using the function npdfnc()

fnc = npdfnc(npd,geo,Date(2020))

"/home/runner/imergv7monthly/AR6_CAR/imergv7monthly-AR6_CAR-2020.nc"

API

setup(;
    login     :: AbstractString = "",
    password  :: AbstractString = "",
    overwrite :: Bool = false
)

download(
    npd :: NASAPrecipitationDataset,
    geo :: GeoRegion = GeoRegion("GLB");
    overwrite :: Bool = false
) -> nothing

read(
    npd :: NASAPrecipitationDataset,
    geo :: GeoRegion,
    dt  :: TimeType;
    lonlat :: Bool = false
) -> NCDataset           (if lonlat = false)
  -> lon, lat, NCDataset (if lonlat = true)

npdfnc(
    npd :: NASAPrecipitationDataset,
    geo :: GeoRegion,
    dt  :: TimeType
) -> String