An Introduction to ERA5Regions

What is an ERA5Region and why do we need it?

By default, ERA5Reanalysis.jl will conduct downloads, or analyse data over, the entire globe. However, most of the time we would rather perform these tasks over specified regions of interest. In ERA5Reanalysis, we do this by specifying an ERA5Region, which is built on top of the GeoRegion functionality in GeoRegions.jl.

Why not just use `GeoRegion`s directly?

The functionality of ERA5Regions and the basic manipulations are very similar to those of GeoRegions. However, in ERA5Reanalysis.jl, we must additionally specify the resolution of the data that needs to be downloaded and/or analyzed, and therefore we build an ERA5Region as a container of a GeoRegion.

ERA5Reanalysis.ERA5Region — Type
ERA5Region

Structure that imports relevant GeoRegion properties used in the handling of the gridded ERA5 datasets.

All ERA5Region Types contain the following fields:

  • geo : The GeoRegion containing the geographical information
  • geoID : The ID used to specify the GeoRegion
  • gres : The resolution of the gridded data to be downloaded/analysed
  • gstr : String, for specification of folder and file name
  • isglb : A Bool, true if spans the globe, false if no
  • is360 : True if it spans 360º longitude

The package GeoRegions.jl is automatically reexported by ERA5Reanalysis.jl, so one can define or retrieve a GeoRegion and its information directly without needing to explicitly call GeoRegions.jl in the REPL. Once a GeoRegion has been retrieved, we can use it to define an ERA5Region, which will also contain information on the horizontal resolution at which the dataset will be downloaded/analyzed.

ERA5Reanalysis.ERA5Region — Method
ERA5Region(
    geo  :: GeoRegion;
    gres :: Real = 0,
    ST = String,
    FT = Float64
) -> egeo :: ERA5Region

Argument

  • geo : A GeoRegion structure type

Keyword Argument

  • gres : The spatial resolution that ERA5 reanalysis data will be downloaded/analyzed, and 360 must be a multiple of gres

Basic Example

Here, we define ERA5Regions that cover the same domain based on the same GeoRegion, GF_WAF, but using different spatial resolution. We see that gres = 1.3 is not a valid resolution, because 360 then is not a multiple of gres.

julia> using ERA5Reanalysis
julia> geo   = GeoRegion("AR6_SEA")[ Info: 2023-04-03T03:55:09.914 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID AR6_SEA
The Polygonal Region AR6_SEA has the following properties:
    Region ID (regID) : AR6_SEA
    Parent ID (parID) : GLB
    Name       (name) : Southeast Asia
    Bounds  (N,S,E,W) : [19.5, -10.0, 155.0, 93.0]
    Shape     (shape) : Point2{Float64}[[93.0, -10.0], [93.0, 19.5], [132.0, 19.5], [132.0, 5.0], [155.0, -10.0], [93.0, -10.0]]
        (is180,is360) : (false, true)
julia> egeo1 = ERA5Region(geo)[ Info: 2023-04-03T03:55:10.629 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
[ Info: 2023-04-03T03:55:10.629 - ERA5Reanalysis.jl - No grid resolution specified, defaulting to the module default (1.0º for global GeoRegion, 0.25º for all others)
The ERA5Region wrapper for the "AR6_SEA" GeoRegion has the following properties:
    Region ID      (geoID) : AR6_SEA
    Name        (geo.name) : Southeast Asia
    Resolution      (gres) : 0.25
    Folder ID       (gstr) : AR6_SEAx0.25
    Bounds (geo.[N,S,E,W]) : [19.5, -10.0, 155.0, 93.0]
    Shape      (geo.shape) : Point2{Float64}[[93.0, -10.0], [93.0, 19.5], [132.0, 19.5], [132.0, 5.0], [155.0, -10.0], [93.0, -10.0]]
       (geo.[is180,is360]) : (false, true)
julia> egeo2 = ERA5Region(geo,gres=1.0)[ Info: 2023-04-03T03:55:10.684 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
The ERA5Region wrapper for the "AR6_SEA" GeoRegion has the following properties:
    Region ID      (geoID) : AR6_SEA
    Name        (geo.name) : Southeast Asia
    Resolution      (gres) : 1.0
    Folder ID       (gstr) : AR6_SEAx1.00
    Bounds (geo.[N,S,E,W]) : [19.5, -10.0, 155.0, 93.0]
    Shape      (geo.shape) : Point2{Float64}[[93.0, -10.0], [93.0, 19.5], [132.0, 19.5], [132.0, 5.0], [155.0, -10.0], [93.0, -10.0]]
       (geo.[is180,is360]) : (false, true)
julia> egeo3 = ERA5Region(geo,gres=1.3)[ Info: 2023-04-03T03:55:10.685 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
ERROR: 2023-04-03T03:55:10.686 - ERA5Reanalysis.jl - The grid resolution 1.3º is not valid as it does not divide 360º without remainder