diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 0ec8414..8b8a914 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.1","generation_timestamp":"2024-02-19T23:16:11","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.1","generation_timestamp":"2024-02-20T03:37:17","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/dev/components/datasets/cds.html b/dev/components/datasets/cds.html index 77514c6..4533c5f 100644 --- a/dev/components/datasets/cds.html +++ b/dev/components/datasets/cds.html @@ -1,11 +1,11 @@ -Climate Data Store Datasets · ERA5Reanalysis.jl
GitHub

ERA5 Datasets available in CDS

The ERA5CDStore Type of the parent type of all ERA5 Datasets that are naturally available from the Climate Data Store and can thus be downloaded directly using the CDSAPI.

Note

The Climate Data Store also has an option to download ERA5 Monthly data by hour-of-day. This is subsumed into the ERA5Monthly dataset and can be selected by specifying hours = true.

ERA5Reanalysis.ERA5Hourly — Type
ERA5Hourly <: ERA5CDStore

Specifies that the dataset to be analyzed contains hourly data. All fields are the same as that specified in the ERA5Dataset docstring.

source
ERA5Reanalysis.ERA5Monthly — Type
ERA5Monthly <: ERA5CDStore

Specifies that the dataset to be analyzed contains monthly-mean data. The ERA5Monthly Type will also contain the following fields:

  • hours : specifies the hour(s) of day for which monthly data is downloaded
source

There are other potential modules that could be incorporated into ERA5Reanalysis.jl, such as

  • ERA5-Land data
  • Ensemble model averages, individual members, and standard deviations

They have not been added yet into ERA5Reanalysis.jl. If you are potentially interested in me adding these datasets to ERA5Reanalysis.jl, please submit a pull request.

API

ERA5Reanalysis.ERA5Hourly — Method
ERA5Hourly(;
+Climate Data Store Datasets · ERA5Reanalysis.jl
GitHub
ERA5 Datasets available in CDS
The ERA5CDStore Type of the parent type of all ERA5 Datasets that are naturally available from the Climate Data Store and can thus be downloaded directly using the CDSAPI.
Note
The Climate Data Store also has an option to download ERA5 Monthly data by hour-of-day. This is subsumed into the ERA5Monthly dataset and can be selected by specifying hours = true.
ERA5Reanalysis.ERA5Hourly — Type
ERA5Hourly <: ERA5CDStore
Specifies that the dataset to be analyzed contains hourly data.  All fields are the same as that specified in the ERA5Dataset docstring.
source
ERA5Reanalysis.ERA5Monthly — Type
ERA5Monthly <: ERA5CDStore
Specifies that the dataset to be analyzed contains monthly-mean data.  The ERA5Monthly Type will also contain the following fields:
  • hours : specifies the hour(s) of day for which monthly data is downloaded
source
There are other potential modules that could be incorporated into ERA5Reanalysis.jl, such as
  • ERA5-Land data
  • Ensemble model averages, individual members, and standard deviations
They have not been added yet into ERA5Reanalysis.jl. If you are potentially interested in me adding these datasets to ERA5Reanalysis.jl, please submit a pull request.
API
ERA5Reanalysis.ERA5Hourly — Method
ERA5Hourly(;
     start :: TimeType,
     stop  :: TimeType,
     path  :: AbstractString = homedir(),
-) -> ERA5Hourly <: ERA5Dataset
A function that creates an ERA5Hourly module.  All possible hours are downloaded, and data is saved month-by-month.
Keyword Arguments
  • path : The specified directory in which to save the data
  • start : The date for which downloads/analysis begins, automatically rounded to the nearest month
  • stop : The date for which downloads/analysis finishes, automatically rounded to the nearest month
source
ERA5Reanalysis.ERA5Monthly — Method
ERA5Monthly(;
+) -> ERA5Hourly <: ERA5Dataset
A function that creates an ERA5Hourly module.  All possible hours are downloaded, and data is saved month-by-month.
Keyword Arguments
  • path : The specified directory in which to save the data
  • start : The date for which downloads/analysis begins, automatically rounded to the nearest month
  • stop : The date for which downloads/analysis finishes, automatically rounded to the nearest month
source
ERA5Reanalysis.ERA5Monthly — Method
ERA5Monthly(;
     start :: TimeType,
     stop  :: TimeType,
     path  :: AbstractString = homedir(),
     hours :: Bool = false,
-) -> ERA5Monthly <: ERA5Dataset or ERA5MonthlyHour <: ERA5Dataset
A function that creates an ERA5Monthly or ERA5MonthlyHour module depending on the input arguments of hours.  Data is saved year-by-year.
Keyword Arguments
  • path : The specified directory in which to save the data
  • start : The date for which downloads/analysis begins, automatically rounded to the nearest year
  • stop : The date for which downloads/analysis finishes, automatically rounded to the nearest year
  • hours : If false, download monthly-averaged data. If true, download monthly-averaged data for each hour
source

+) -> ERA5Monthly <: ERA5Dataset or ERA5MonthlyHour <: ERA5Dataset

A function that creates an ERA5Monthly or ERA5MonthlyHour module depending on the input arguments of hours. Data is saved year-by-year.

Keyword Arguments

  • path : The specified directory in which to save the data
  • start : The date for which downloads/analysis begins, automatically rounded to the nearest year
  • stop : The date for which downloads/analysis finishes, automatically rounded to the nearest year
  • hours : If false, download monthly-averaged data. If true, download monthly-averaged data for each hour
source
diff --git a/dev/components/datasets/custom.html b/dev/components/datasets/custom.html index 1cc2233..d889cec 100644 --- a/dev/components/datasets/custom.html +++ b/dev/components/datasets/custom.html @@ -1,5 +1,5 @@ -Custom ERA5 Datasets · ERA5Reanalysis.jl
GitHub

Custom ERA5 Datasets defined in ERA5Reanalysis.jl

We also have created a custom ERA5Daily dataset, which is a daily-average of the hourly data from ERA5Hourly data.

ERA5Reanalysis.ERA5Daily — Type
ERA5Daily <: ERA5Custom

Specifies that the dataset to be analyzed contains hourly data. All fields are the same as that specified in the ERA5Dataset docstring. However, the fields sldoi, pldoi and ptype are all set to N/A because ERA5Daily is not available in, nor downloadable from, the Climate Data Store.

source

In order to create the ERA5 daily datasets from an ERA5Hourly dataset, use the hour2day function as below:

using ERA5Reanalysis
+Custom ERA5 Datasets · ERA5Reanalysis.jl
GitHub
Custom ERA5 Datasets defined in ERA5Reanalysis.jl
We also have created a custom ERA5Daily dataset, which is a daily-average of the hourly data from ERA5Hourly data.
ERA5Reanalysis.ERA5Daily — Type
ERA5Daily <: ERA5Custom
Specifies that the dataset to be analyzed contains hourly data.  All fields are the same as that specified in the ERA5Dataset docstring.  However, the fields sldoi, pldoi and ptype are all set to N/A because ERA5Daily is not available in, nor downloadable from, the Climate Data Store.
source
In order to create the ERA5 daily datasets from an ERA5Hourly dataset, use the hour2day function as below:
using ERA5Reanalysis
 e5ds = ERA5Hourly(start=Date(2015),stop=Date(2015),path=datadir())
 evar = SingleVariable("t2m")
 egeo = GeoRegion("TRP")
@@ -7,4 +7,4 @@
     start :: TimeType,
     stop  :: TimeType,
     path  :: AbstractString = homedir(),
-) -> ERA5Daily <: ERA5Dataset
A function that creates an ERA5Hourly module.  All possible hours are downloaded, and data is saved month-by-month.
Keyword Arguments
  • path : The specified directory in which to save the data
  • start : The date for which downloads/analysis begins, automatically rounded to the nearest month
  • stop : The date for which downloads/analysis finishes, automatically rounded to the nearest month
source
+) -> ERA5Daily <: ERA5Dataset

A function that creates an ERA5Hourly module. All possible hours are downloaded, and data is saved month-by-month.

Keyword Arguments

source diff --git a/dev/components/datasets/define.html b/dev/components/datasets/define.html index 10e227b..a1eae44 100644 --- a/dev/components/datasets/define.html +++ b/dev/components/datasets/define.html @@ -1,15 +1,15 @@ -Defining ERA5 Datasets · ERA5Reanalysis.jl
GitHub

ERA5Dataset Examples

Here, we list some basic examples for the creation of ERA5Dataset

Specifying an hourly dataset:

julia> using ERA5Reanalysis
julia> ERA5Hourly(start=Date(2017,1,2),stop=Date(2018,5,1))[ Info: 2024-02-19T23:15:25.483 - ERA5Reanalysis.jl - Setting up data structure containing information on the ERA5 Hourly data to be downloaded
+Defining ERA5 Datasets · ERA5Reanalysis.jl
GitHub
ERA5Dataset Examples
Here, we list some basic examples for the creation of ERA5Dataset
Specifying an hourly dataset:
julia> using ERA5Reanalysis
julia> ERA5Hourly(start=Date(2017,1,2),stop=Date(2018,5,1))[ Info: 2024-02-20T03:36:28.294 - ERA5Reanalysis.jl - Setting up data structure containing information on the ERA5 Hourly data to be downloaded
 The ERA5Hourly Module has the following properties:
     Dataset ID        (ID) : era5hr
     Date Begin     (start) : 2017-01-01
     Date End        (stop) : 2018-05-31
     Data Directory  (path) : /home/runner/era5hr
-    Mask Directory (emask) : /home/runner/emask
Note that the resultant ERA5Hourly dataset processes data by whole-months.  It is not possible to specify specific days in which to download data.
Specifying a monthly dataset with custom home directory:
julia> using ERA5Reanalysis
julia> ERA5Monthly(start=Date(2017,1,2),stop=Date(2018,5,1),path=pwd())[ Info: 2024-02-19T23:15:25.698 - ERA5Reanalysis.jl - Setting up data structure containing information on the ERA5 Monthly data to be downloaded
+    Mask Directory (emask) : /home/runner/emask
Note that the resultant ERA5Hourly dataset processes data by whole-months.  It is not possible to specify specific days in which to download data.
Specifying a monthly dataset with custom home directory:
julia> using ERA5Reanalysis
julia> ERA5Monthly(start=Date(2017,1,2),stop=Date(2018,5,1),path=pwd())[ Info: 2024-02-20T03:36:28.527 - ERA5Reanalysis.jl - Setting up data structure containing information on the ERA5 Monthly data to be downloaded
 The ERA5Monthly Module has the following properties:
     Dataset ID        (ID) : era5mo
     Date Begin     (start) : 2017-01-01
     Date End        (stop) : 2018-12-31
     Data Directory  (path) : /home/runner/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/docs/build/components/datasets/era5mo
     Mask Directory (emask) : /home/runner/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/docs/build/components/datasets/emask
-    Hour-of-Day?   (hours) : false
Note that the resultant ERA5Monthly dataset processes data by years.  It is not possible to specify specific months in which to download data.  The same holds true for the ERA5MonthlyHour dataset.
Specifying a monthly-hour dataset:
julia> using ERA5Reanalysis
julia> ERA5Monthly(start=Date(2017,1,2),stop=Date(2018,5,1),hours=[0,3,6,9,12,15,18,21])ERROR: TypeError: non-boolean (Vector{Int64}) used in boolean context

+    Hour-of-Day?   (hours) : false

Note that the resultant ERA5Monthly dataset processes data by years. It is not possible to specify specific months in which to download data. The same holds true for the ERA5MonthlyHour dataset.

Specifying a monthly-hour dataset:

julia> using ERA5Reanalysis
julia> ERA5Monthly(start=Date(2017,1,2),stop=Date(2018,5,1),hours=[0,3,6,9,12,15,18,21])ERROR: TypeError: non-boolean (Vector{Int64}) used in boolean context
diff --git a/dev/components/datasets/dummy.html b/dev/components/datasets/dummy.html index 8ba43f7..d05f867 100644 --- a/dev/components/datasets/dummy.html +++ b/dev/components/datasets/dummy.html @@ -1,6 +1,6 @@ -Dummy ERA5 Datasets · ERA5Reanalysis.jl
GitHub

Dummy ERA5 Datasets

Dummy datasets are meant to specify the paths to the ERA5 data root directory, and LandSea folder, without needing inputs for date.

julia> using ERA5Reanalysis
julia> e5ds = ERA5Dummy(path=homedir())[ Info: 2024-02-19T23:15:26.301 - ERA5Reanalysis.jl - Setting up data structure for the ERA5 Dummy Dataset
+Dummy ERA5 Datasets · ERA5Reanalysis.jl
GitHub
Dummy ERA5 Datasets
Dummy datasets are meant to specify the paths to the ERA5 data root directory, and LandSea folder, without needing inputs for date.
julia> using ERA5Reanalysis
julia> e5ds = ERA5Dummy(path=homedir())[ Info: 2024-02-20T03:36:29.153 - ERA5Reanalysis.jl - Setting up data structure for the ERA5 Dummy Dataset
 The ERA5Monthly Module has the following properties:
     Mask Directory (emask) : /home/runner/emask
julia> isdir(e5ds.emask)true
API
ERA5Reanalysis.ERA5Dummy — Method
ERA5Dummy(;
     path  :: AbstractString = homedir(),
-) -> ERA5Dummy <: ERA5Dataset
A function that creates a dummy ERA5Dataset that contains only information on the path of the ERA5 LandSea mask
Keyword Arguments
  • path : The specified directory in which to save the data
source

+) -> ERA5Dummy <: ERA5Dataset

A function that creates a dummy ERA5Dataset that contains only information on the path of the ERA5 LandSea mask

Keyword Arguments

  • path : The specified directory in which to save the data
source
diff --git a/dev/components/datasets/overview.html b/dev/components/datasets/overview.html index fd4a72a..de6992d 100644 --- a/dev/components/datasets/overview.html +++ b/dev/components/datasets/overview.html @@ -1,4 +1,4 @@ An Overview of ERA5 Datasets · ERA5Reanalysis.jl
GitHub

An Overview of ERA5 Reanalysis Datasets

An ERA5 Dataset is defined to be a module containing ERA5 Reanalysis data from the Climate Data Store, and is to distinguish between datasets with differing time-resolution, from hourly to monthly.

ERA5 reanalysis data is stored on the Climate Data Store in several different categories, so different people with different needs may access different data types depending on their research. In ERA5Reanalysis, we defined these datasets as ERA5Dataset Types.

When defining an ERA5Dataset container, we also indicate the start and end dates of the dataset that we want to work on.

ERA5Reanalysis.ERA5Dataset — Type
ERA5Dataset

Abstract supertype for ERA5 reanalysis datasets, with the following subtypes:

ERA5CDStore <: ERA5Dataset
 ERA5Custom  <: ERA5Dataset
-ERA5Dummy   <: ERA5Dataset

All ERA5Dataset Types contain the following fields:

  • path : The specified directory in which to save the data
  • emask : The specified directory in which to save the LandSea dataset

All ERA5CDStore and ERA5Custom Types also contain the following additional fields:

  • ID : The module ID, that also acts as a prefix to filenames
  • name : The full name of the module
  • start : The date for which downloads/analysis begins
  • stop : The date for which downloads/analysis finishes
  • sldoi : Single-Level DOI (N/A for ERA5Daily)
  • pldoi : Pressure-Level DOI (N/A for ERA5Daily)
  • ptype : Product type (N/A for ERA5Daily), set to reanalysis
source
+ERA5Dummy <: ERA5Dataset

All ERA5Dataset Types contain the following fields:

All ERA5CDStore and ERA5Custom Types also contain the following additional fields:

source diff --git a/dev/components/overview.html b/dev/components/overview.html index c1482b2..4a77283 100644 --- a/dev/components/overview.html +++ b/dev/components/overview.html @@ -1,2 +1,2 @@ -Overview · ERA5Reanalysis.jl
GitHub
+Overview · ERA5Reanalysis.jl
GitHub
diff --git a/dev/components/regions/gridded.html b/dev/components/regions/gridded.html index 9c3032c..702f934 100644 --- a/dev/components/regions/gridded.html +++ b/dev/components/regions/gridded.html @@ -3,4 +3,4 @@ e5geo :: ERA5Region{ST,FT}, lon :: Vector{<:Real}, lat :: Vector{<:Real} -) -> GeoRegion.RegionGrid

Creates a RegionGrid containing information and mask information required to extract regional data for the ERA5Region from the raw data.

Arguments

source +) -> GeoRegion.RegionGrid

Creates a RegionGrid containing information and mask information required to extract regional data for the ERA5Region from the raw data.

Arguments

source diff --git a/dev/components/regions/index.html b/dev/components/regions/index.html index 541ecdf..188ce31 100644 --- a/dev/components/regions/index.html +++ b/dev/components/regions/index.html @@ -1,18 +1,18 @@ -What is an ERA5Region · ERA5Reanalysis.jl
GitHub

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.

The ERA5Region Type contain the following fields:

  • geo : The GeoRegion containing the geographical information
  • ID : The ID used to specify the GeoRegion
  • resolution : The resolution of the gridded data to be downloaded/analysed
  • string : Specification of folder and file name, mostly for backend usage
  • isglb : A Bool, true if spans the globe, false if no
  • is360 : True if it spans 360º longitude
source

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(
+What is an ERA5Region · ERA5Reanalysis.jl
GitHub
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.
The ERA5Region Type contain the following fields:
  • geo : The GeoRegion containing the geographical information
  • ID : The ID used to specify the GeoRegion
  • resolution : The resolution of the gridded data to be downloaded/analysed
  • string : Specification of folder and file name, mostly for backend usage
  • isglb : A Bool, true if spans the globe, false if no
  • is360 : True if it spans 360º longitude
source
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;
     resolution :: Real = 0,
     ST = String,
     FT = Float64
-) -> ereg :: ERA5Region
Argument
  • geo  : A GeoRegion structure type
Keyword Argument
  • resolution : The spatial resolution that ERA5 reanalysis data will be downloaded/analyzed, and 360 must be a multiple of resolution
source
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: 2024-02-19T23:15:26.759 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID AR6_SEA
+) -> ereg :: ERA5Region
Argument
  • geo  : A GeoRegion structure type
Keyword Argument
  • resolution : The spatial resolution that ERA5 reanalysis data will be downloaded/analyzed, and 360 must be a multiple of resolution
source

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: 2024-02-20T03:36:29.614 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID AR6_SEA
 The Polygonal Region AR6_SEA has the following properties:
     Region ID    (ID) : AR6_SEA
     Parent ID   (pID) : 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: 2024-02-19T23:15:28.194 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
-[ Info: 2024-02-19T23:15:28.194 - ERA5Reanalysis.jl - No grid resolution specified, defaulting to the module default (1.0º for global GeoRegion, 0.25º for all others)
+        (is180,is360) : (false, true)
julia> egeo1 = ERA5Region(geo)[ Info: 2024-02-20T03:36:31.114 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
+[ Info: 2024-02-20T03:36:31.114 - 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          (ID) : AR6_SEA
     Name         (geo.name) : Southeast Asia
@@ -20,7 +20,7 @@
     Folder ID      (string) : 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,resolution=1.0)[ Info: 2024-02-19T23:15:28.278 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
+        (geo.[is180,is360]) : (false, true)
julia> egeo2 = ERA5Region(geo,resolution=1.0)[ Info: 2024-02-20T03:36:31.215 - 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          (ID) : AR6_SEA
     Name         (geo.name) : Southeast Asia
@@ -28,5 +28,5 @@
     Folder ID      (string) : 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,resolution=1.3)[ Info: 2024-02-19T23:15:28.279 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
-ERROR: 2024-02-19T23:15:28.279 - ERA5Reanalysis.jl - The grid resolution 1.3º is not valid as it does not divide 360º without remainder
+ (geo.[is180,is360]) : (false, true)
julia> egeo3 = ERA5Region(geo,resolution=1.3)[ Info: 2024-02-20T03:36:31.216 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA" +ERROR: 2024-02-20T03:36:31.216 - ERA5Reanalysis.jl - The grid resolution 1.3º is not valid as it does not divide 360º without remainder diff --git a/dev/components/regions/isin.html b/dev/components/regions/isin.html index 1b53f8d..907707f 100644 --- a/dev/components/regions/isin.html +++ b/dev/components/regions/isin.html @@ -5,9 +5,9 @@ tlon :: Real = 0, tlat :: Real = 0, throw :: Bool = true -) -> Bool

Check if a geographical point Point is within an ERA5Region defined by e5geo.

Arguments

Keyword Arguments

source
isinERA5Region(
+) -> Bool

Check if a geographical point Point is within an ERA5Region defined by e5geo.

Arguments

Keyword Arguments

source
isinERA5Region(
     geo    :: GeoRegion,
     e5geo  :: ERA5Region;
     domask :: Bool = false,
     throw  :: Bool = true
-) -> Bool

Check if a child GeoRegion defined by geo is within a ERA5Region e5geo.

Arguments

Keyword Arguments

source
+) -> Bool

Check if a child GeoRegion defined by geo is within a ERA5Region e5geo.

Arguments

Keyword Arguments

source diff --git a/dev/components/variables/custom.html b/dev/components/variables/custom.html index 35a481e..618744d 100644 --- a/dev/components/variables/custom.html +++ b/dev/components/variables/custom.html @@ -5,14 +5,14 @@ long :: AbstractString = "", name :: AbstractString, units :: AbstractString -) -> evar :: SingleLevel

Create a custom Single-Level variable that is not in the default list exported by ERA5Reanalysis.jl. These variables are not available in the CDS store, and so they must be separately calculated from other variables and analyzed.

Keyword Arguments

source

Removing Custom SingleLevel Variables

To remove a SingleCustom variable, we can use the rmSingle() function:

ERA5Reanalysis.rmSingle — Method
rmSingle( ID :: AbstractString ) -> nothing

Remove the Single-Level Variable with the ID ID from the lists.

Arguments

  • RegID : The keyword ID that will be used to identify the Single-Level Variable that is to be removed
source

An Example!

In this example, we add a SingleLevel variable to the list:

The Eddy Kinetic Energy is calculated by the following:

\[E = \frac{1}{2g} \int_0^{p_s} \overline{u'^2} + \overline{v'^2} \>dp\]

And it is often used as a measure of storm-track intensity.

julia> using ERA5Reanalysis
julia> SingleVariable(
+) -> evar :: SingleLevel

Create a custom Single-Level variable that is not in the default list exported by ERA5Reanalysis.jl. These variables are not available in the CDS store, and so they must be separately calculated from other variables and analyzed.

Keyword Arguments

source

Removing Custom SingleLevel Variables

To remove a SingleCustom variable, we can use the rmSingle() function:

ERA5Reanalysis.rmSingle — Method
rmSingle( ID :: AbstractString ) -> nothing

Remove the Single-Level Variable with the ID ID from the lists.

Arguments

  • RegID : The keyword ID that will be used to identify the Single-Level Variable that is to be removed
source

An Example!

In this example, we add a SingleLevel variable to the list:

The Eddy Kinetic Energy is calculated by the following:

\[E = \frac{1}{2g} \int_0^{p_s} \overline{u'^2} + \overline{v'^2} \>dp\]

And it is often used as a measure of storm-track intensity.

julia> using ERA5Reanalysis
julia> SingleVariable(
            ID = "eke",
            units = "J m**-2",
            name = "Eddy Kinetic Energy",
            long = "eddy_kinetic_energy"
-       )┌ Warning: 2024-02-19T23:15:28.503 - ERA5Reanalysis.jl - "eke" is not a valid SingleVariable identifier, use the function SingleVariable() or SingleCustom() to add this ERA5Variable to the list.
+       )┌ Warning: 2024-02-20T03:36:31.452 - ERA5Reanalysis.jl - "eke" is not a valid SingleVariable identifier, use the function SingleVariable() or SingleCustom() to add this ERA5Variable to the list.
 └ @ ERA5Reanalysis ~/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/src/variable/single.jl:187
-[ Info: 2024-02-19T23:15:28.503 - ERA5Reanalysis.jl - Adding the SingleVariable "eke" to the list.
+[ Info: 2024-02-20T03:36:31.452 - ERA5Reanalysis.jl - Adding the SingleVariable "eke" to the list.
 The Single-Level Variable "eke" has the following properties:
     Variable ID       (ID) : eke
     Long Name       (long) : eddy_kinetic_energy
@@ -21,7 +21,7 @@
   Variable Type   ID    Name                   Units    ERA5 Long-Name
  --------------- ----- --------------------- --------- ---------------------
   SingleCustom    eke   Eddy Kinetic Energy   J m**-2   eddy_kinetic_energy
- --------------- ----- --------------------- --------- ---------------------
julia> rmSingle("eke")[ Info: 2024-02-19T23:15:29.650 - ERA5Reanalysis.jl - Successfully removed the Single-Level variable defined by "eke"
julia> isSingle("eke",throw=false) # don't throw error, just show warning┌ Warning: 2024-02-19T23:15:29.655 - ERA5Reanalysis.jl - "eke" is not a valid SingleVariable identifier, use the function SingleVariable() or SingleCustom() to add this ERA5Variable to the list.
+ --------------- ----- --------------------- --------- ---------------------
julia> rmSingle("eke")[ Info: 2024-02-20T03:36:32.640 - ERA5Reanalysis.jl - Successfully removed the Single-Level variable defined by "eke"
julia> isSingle("eke",throw=false) # don't throw error, just show warning┌ Warning: 2024-02-20T03:36:32.646 - ERA5Reanalysis.jl - "eke" is not a valid SingleVariable identifier, use the function SingleVariable() or SingleCustom() to add this ERA5Variable to the list.
 └ @ ERA5Reanalysis ~/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/src/variable/single.jl:187
 false

Custom PressureLevel variables

In ERA5Reanalysis.jl, we have predefined all the pressure-level variables that are available directly from the CDS. As such, all custom PressureLevel variables are defined under the PressureCustom type.

Defining Custom PressureLevel Variables

PressureCustom variables are defined using the PressureVariable() function, as follows:

ERA5Reanalysis.PressureVariable — Type
PressureVariable(
     ST = String;
@@ -31,15 +31,15 @@
     units :: AbstractString,
     hPa   :: Int = 0,
     throw :: Bool = true
-) -> evar :: PressureCustom

Create a custom Pressure-Level variable that is not in the default list exported by ERA5Reanalysis.jl. These variables are not available in the CDS store, and so they must be separately calculated from other variables and analyzed.

Keyword Arguments

  • ID : variable ID (in string format) used in the NetCDF file
  • long : long-name for variable (used in specifying variable for CDS downloads)
  • name : user-defined variable name
  • units : user-defined units of the variable
  • hPa : Pressure level specified in hPa. Default is 0, which indicates all levels.
  • throw : if hPa level does not exist and throw is true, throw error, otherwise find nearest pressure level
source

Removing Custom PressureLevel Variables

To remove a PressureCustom variable, we can use the rmPressure() function:

ERA5Reanalysis.rmPressure — Method
rmPressure( ID :: AbstractString ) -> nothing

Remove the Pressure-Level Variable with the ID ID from the lists.

Arguments

  • RegID : The keyword ID that will be used to identify the Pressure-Level Variable that is to be removed
source

An Example!

Let us define the custom variable "vt" for Virtual Temperature, which is a proxy to buoyancy in the atmosphere. Virtual Temperature is calculated from both the water vapour mixing ratio and atmospheric temperature and is given by the formula:

\[T_v = T(1+0.61q)\]

Virtual Temperature has the units "K", and for this example let us define the pressure level height we are interested in to be at 1000 hPa. The resultant PressureCustom variable is given by:

julia> using ERA5Reanalysis
julia> PressureVariable(
+) -> evar :: PressureCustom

Create a custom Pressure-Level variable that is not in the default list exported by ERA5Reanalysis.jl. These variables are not available in the CDS store, and so they must be separately calculated from other variables and analyzed.

Keyword Arguments

source

Removing Custom PressureLevel Variables

To remove a PressureCustom variable, we can use the rmPressure() function:

ERA5Reanalysis.rmPressure — Method
rmPressure( ID :: AbstractString ) -> nothing

Remove the Pressure-Level Variable with the ID ID from the lists.

Arguments

  • RegID : The keyword ID that will be used to identify the Pressure-Level Variable that is to be removed
source

An Example!

Let us define the custom variable "vt" for Virtual Temperature, which is a proxy to buoyancy in the atmosphere. Virtual Temperature is calculated from both the water vapour mixing ratio and atmospheric temperature and is given by the formula:

\[T_v = T(1+0.61q)\]

Virtual Temperature has the units "K", and for this example let us define the pressure level height we are interested in to be at 1000 hPa. The resultant PressureCustom variable is given by:

julia> using ERA5Reanalysis
julia> PressureVariable(
            ID = "vt",
            units = "K",
            hPa   = 1000,
            long = "virtual_temperature",
            name = "Virtual Temperature"
-       )┌ Warning: 2024-02-19T23:15:29.941 - ERA5Reanalysis.jl - "vt" is not a valid PressureVariable identifier, use the function PressureCustom() to add this ERA5Variable to the list.
+       )┌ Warning: 2024-02-20T03:36:32.940 - ERA5Reanalysis.jl - "vt" is not a valid PressureVariable identifier, use the function PressureCustom() to add this ERA5Variable to the list.
 └ @ ERA5Reanalysis ~/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/src/variable/pressure.jl:233
-[ Info: 2024-02-19T23:15:29.941 - ERA5Reanalysis.jl - Adding the PressureVariable "vt" to the list.
+[ Info: 2024-02-20T03:36:32.940 - ERA5Reanalysis.jl - Adding the PressureVariable "vt" to the list.
 The Pressure-Level Variable "vt" has the following properties:
     Variable ID       (ID) : vt
     Long Name       (long) : virtual_temperature
@@ -65,6 +65,6 @@
   PressureVariable   cswc   Specific Snow Water Contnet                kg kg**-1         specific_snow_water_content
   PressureVariable    o3    Ozone Mass Mixing Ration                   kg kg**-1         ozone_mass_mixing_ratio
    PressureCustom     vt    Virtual Temperature                            K             virtual_temperature
- ------------------ ------ ------------------------------------- ---------------------- -------------------------------------
julia> rmPressure("vt")[ Info: 2024-02-19T23:15:30.352 - ERA5Reanalysis.jl - Successfully removed the Pressure-Level variable defined by "vt"
julia> isPressure("vt",throw=false) # don't throw error, just show warning┌ Warning: 2024-02-19T23:15:30.357 - ERA5Reanalysis.jl - "vt" is not a valid PressureVariable identifier, use the function PressureCustom() to add this ERA5Variable to the list.
+ ------------------ ------ ------------------------------------- ---------------------- -------------------------------------
julia> rmPressure("vt")[ Info: 2024-02-20T03:36:33.358 - ERA5Reanalysis.jl - Successfully removed the Pressure-Level variable defined by "vt"
julia> isPressure("vt",throw=false) # don't throw error, just show warning┌ Warning: 2024-02-20T03:36:33.363 - ERA5Reanalysis.jl - "vt" is not a valid PressureVariable identifier, use the function PressureCustom() to add this ERA5Variable to the list.
 └ @ ERA5Reanalysis ~/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/src/variable/pressure.jl:233
-false
+false diff --git a/dev/components/variables/index.html b/dev/components/variables/index.html index 449a1e8..06b7cb0 100644 --- a/dev/components/variables/index.html +++ b/dev/components/variables/index.html @@ -1,5 +1,5 @@ What is an ERA5 Variable · ERA5Reanalysis.jl
GitHub

Variable Types in ERA5Reanalysis.jl

In order to download data from the Climate Data Store, we need to specify at least a variable to download. This variable can be one found directly from CDS, or it can be a custom user-defined variable (in which case it has to be calculated by the user). Information regarding this variable will be loaded into an ERA5Variable.

ERA5Reanalysis.ERA5Variable — Type
ERA5Variable

Abstract supertype for ERA5 variables, with the following subtypes

SingleLevel   <: ERA5Variable
-PressureLevel <: ERA5Variable

All ERA5Variable Types contain the following fields:

  • ID : The variable ID, that is also the identifier in the NetCDF files
  • name : The full-name of the variable
  • long : The variable long-name, which is used to specify retrievals from CDS
  • dataset : The full-name of the variable
  • units : The units of the variable

All PressureLevel Types contain the following fields:

  • hPa : The pressure level (in hPa) of the pressure-variable of interest
source

SingleLevel and PressureLevel variables

There are two main ERA5Variable types in ERA5 reanalysis:

  • SingleLevel variables, such as surface temperature, or total cloud cover, that are provided in the (lon,lat) space
  • PressureLevel variables, such as atmospheric temperature, or specific humidity, that are provided in the (lon,lat,pressure) space
ERA5Reanalysis.SingleLevel — Type
SingleLevel <: ERA5Variable

Abstract supertype for Single-Level variables, with the following subtypes:

SingleVariable <: SingleLevel
-SingleCustom   <: SingleLevel
source
ERA5Reanalysis.PressureLevel — Type
PressureLevel <: ERA5Variable

Abstract supertype for Single-Level variables, with the following subtypes:

PressureVariable <: PressureLevel
-PressureCustom   <: PressureLevel
source

Custom ERA5Variables

Each of these supertypes are further broken down into XXVariable and XXCustom subtypes, where XXVariable represents a variable that is available directly from CDS, and XXCustom variables are user-defined variables. XXCustom variables therefore cannot be downloaded - trying to do so will result in a method error - and can only be calculated from existing variable data.

ERA5Reanalysis.SingleCustom — Type
SingleCustom <: SingleLevel

Subtype for custom user-defined Single-Level variables, which can only be calculated and not downloaded from the Climate Data Store.

source
ERA5Reanalysis.PressureCustom — Type
PressureCustom <: PressureLevel

Subtype for custom user-defined Pressure-Level variables which can only be calculated and not downloaded from the Climate Data Store.

source
+PressureLevel <: ERA5Variable

All ERA5Variable Types contain the following fields:

All PressureLevel Types contain the following fields:

source

SingleLevel and PressureLevel variables

There are two main ERA5Variable types in ERA5 reanalysis:

ERA5Reanalysis.SingleLevel — Type
SingleLevel <: ERA5Variable

Abstract supertype for Single-Level variables, with the following subtypes:

SingleVariable <: SingleLevel
+SingleCustom   <: SingleLevel
source
ERA5Reanalysis.PressureLevel — Type
PressureLevel <: ERA5Variable

Abstract supertype for Single-Level variables, with the following subtypes:

PressureVariable <: PressureLevel
+PressureCustom   <: PressureLevel
source

Custom ERA5Variables

Each of these supertypes are further broken down into XXVariable and XXCustom subtypes, where XXVariable represents a variable that is available directly from CDS, and XXCustom variables are user-defined variables. XXCustom variables therefore cannot be downloaded - trying to do so will result in a method error - and can only be calculated from existing variable data.

ERA5Reanalysis.SingleVariable — Type
SingleVariable <: SingleLevel

Subtype for Single-Level variables that can be directly retrieved from the Climate Data Store.

source
ERA5Reanalysis.SingleCustom — Type
SingleCustom <: SingleLevel

Subtype for custom user-defined Single-Level variables, which can only be calculated and not downloaded from the Climate Data Store.

source
ERA5Reanalysis.PressureVariable — Type
PressureVariable <: PressureLevel

Subtype for Pressure-Level variables that can be directly retrieved from the Climate Data Store.

source
ERA5Reanalysis.PressureCustom — Type
PressureCustom <: PressureLevel

Subtype for custom user-defined Pressure-Level variables which can only be calculated and not downloaded from the Climate Data Store.

source
diff --git a/dev/components/variables/list.html b/dev/components/variables/list.html index 1a8b261..74ee3f0 100644 --- a/dev/components/variables/list.html +++ b/dev/components/variables/list.html @@ -285,4 +285,4 @@ PressureVariable crwc Specific Rain Water Content kg kg**-1 specific_rain_water_content PressureVariable cswc Specific Snow Water Contnet kg kg**-1 specific_snow_water_content PressureVariable o3 Ozone Mass Mixing Ration kg kg**-1 ozone_mass_mixing_ratio - ------------------ ------ ------------------------------------- ---------------------- ------------------------------------- + ------------------ ------ ------------------------------------- ---------------------- ------------------------------------- diff --git a/dev/components/variables/read.html b/dev/components/variables/read.html index 75e0034..43b5511 100644 --- a/dev/components/variables/read.html +++ b/dev/components/variables/read.html @@ -2,8 +2,8 @@ Retrieving Existing ERA5 Variables · ERA5Reanalysis.jl
GitHub

Reading in Pre-existing ERA5Variable Information

In order to familiarize ourselves with using ERA5Variables, we load some of the pre-existing variables that are prepackaged with ERA5Reanalysis.jl.

Loading Single-Level Variable Information

The easiest example is to load a single-level variable using the SingleVariable() function, for example the u-component of wind 100m above the surface:

ERA5Reanalysis.SingleVariable — Type
SingleVariable(
     ID :: AbstractString,
     ST = String,
-) -> evar :: SingleLevel

Retrieve the basic properties of the Single-Level variable defined by ID and put them in the evar SingleLevel type structure.

Arguments

  • ID : variable ID (in string format) used in the NetCDF file
source
Note

As of v0.3 and above, all Single-Level variables available in the CDS are available by default in ERA5Reanalysis.jl.

julia> using ERA5Reanalysis
julia> SingleVariable("u100")[ Info: 2024-02-19T23:15:30.818 - ERA5Reanalysis.jl - Retrieving information for the SingleVariable defined by the ID "u100"
-[ Info: 2024-02-19T23:15:30.819 - ERA5Reanalysis.jl - The ERA5Variable defined by "u100" is of the SingleVariable type
+) -> evar :: SingleLevel

Retrieve the basic properties of the Single-Level variable defined by ID and put them in the evar SingleLevel type structure.

Arguments

  • ID : variable ID (in string format) used in the NetCDF file
source
Note

As of v0.3 and above, all Single-Level variables available in the CDS are available by default in ERA5Reanalysis.jl.

julia> using ERA5Reanalysis
julia> SingleVariable("u100")[ Info: 2024-02-20T03:36:33.858 - ERA5Reanalysis.jl - Retrieving information for the SingleVariable defined by the ID "u100"
+[ Info: 2024-02-20T03:36:33.859 - ERA5Reanalysis.jl - The ERA5Variable defined by "u100" is of the SingleVariable type
 The Single-Level Variable "u100" has the following properties:
     Variable ID       (ID) : u100
     Long Name       (long) : 100m_u_component_of_wind
@@ -13,24 +13,24 @@
     ST = String;
     hPa   :: Int = 0
     throw :: Bool = true
-) -> evar :: SingleLevel

Retrieve the basic properties of the Pressure-Level variable defined by ID at pressure-height indicated by hPa and put them in the evar SingleLevel type structure.

Arguments

Keyword Arguments

source
julia> using ERA5Reanalysis
julia> PressureVariable("cc",hPa=1000)[ Info: 2024-02-19T23:15:30.856 - ERA5Reanalysis.jl - Retrieving information for the PressureVariable defined by the ID "cc"
-[ Info: 2024-02-19T23:15:30.857 - ERA5Reanalysis.jl - The ERA5Variable defined by "cc" is of the PressureVariable type
+) -> evar :: SingleLevel

Retrieve the basic properties of the Pressure-Level variable defined by ID at pressure-height indicated by hPa and put them in the evar SingleLevel type structure.

Arguments

Keyword Arguments

source
julia> using ERA5Reanalysis
julia> PressureVariable("cc",hPa=1000)[ Info: 2024-02-20T03:36:33.887 - ERA5Reanalysis.jl - Retrieving information for the PressureVariable defined by the ID "cc"
+[ Info: 2024-02-20T03:36:33.888 - ERA5Reanalysis.jl - The ERA5Variable defined by "cc" is of the PressureVariable type
 The Pressure-Level Variable "cc" has the following properties:
     Variable ID       (ID) : cc
     Long Name       (long) : fraction_of_cloud_cover
     Variable Name   (name) : Cloud Cover Fraction (1000 hPa)
     Variable Units (units) : %
-    Pressure Level   (hPa) : 1000
julia> PressureVariable("cc",hPa=890)[ Info: 2024-02-19T23:15:30.872 - ERA5Reanalysis.jl - Retrieving information for the PressureVariable defined by the ID "cc"
-ERROR: 2024-02-19T23:15:30.873 - ERA5Reanalysis.jl - Pressure level specified in "hPa" argument is invalid, please check and see if you requested correctly
julia> PressureVariable("cc",hPa=890,throw=false)[ Info: 2024-02-19T23:15:30.880 - ERA5Reanalysis.jl - Retrieving information for the PressureVariable defined by the ID "cc"
-┌ Warning: 2024-02-19T23:15:30.881 - ERA5Reanalysis.jl - Pressure level specified in "hPa" argument does not exist, snapping to nearest pressure level
+    Pressure Level   (hPa) : 1000
julia> PressureVariable("cc",hPa=890)[ Info: 2024-02-20T03:36:33.905 - ERA5Reanalysis.jl - Retrieving information for the PressureVariable defined by the ID "cc"
+ERROR: 2024-02-20T03:36:33.906 - ERA5Reanalysis.jl - Pressure level specified in "hPa" argument is invalid, please check and see if you requested correctly
julia> PressureVariable("cc",hPa=890,throw=false)[ Info: 2024-02-20T03:36:33.915 - ERA5Reanalysis.jl - Retrieving information for the PressureVariable defined by the ID "cc"
+┌ Warning: 2024-02-20T03:36:33.916 - ERA5Reanalysis.jl - Pressure level specified in "hPa" argument does not exist, snapping to nearest pressure level
 └ @ ERA5Reanalysis ~/work/ERA5Reanalysis.jl/ERA5Reanalysis.jl/src/variable/pressure.jl:83
-[ Info: 2024-02-19T23:15:30.881 - ERA5Reanalysis.jl - The ERA5Variable defined by "cc" is of the PressureVariable type
+[ Info: 2024-02-20T03:36:33.916 - ERA5Reanalysis.jl - The ERA5Variable defined by "cc" is of the PressureVariable type
 The Pressure-Level Variable "cc" has the following properties:
     Variable ID       (ID) : cc
     Long Name       (long) : fraction_of_cloud_cover
     Variable Name   (name) : Cloud Cover Fraction (900 hPa)
     Variable Units (units) : %
-    Pressure Level   (hPa) : 900

Valid ERA5 Pressure-Levels in CDS

A list of valid ERA5 pressure-levels available directly from CDS can be retrieved using the function era5Pressures

ERA5Reanalysis.era5Pressures — Method
era5Pressures() -> parray :: Vector{Int}

Returns the a vector containing the 37 pressure levels available in ERA5 in hPa units.

Returns

  • parray : vector containing list of pressures in Int format and hPa units
source
julia> using ERA5Reanalysis
julia> era5Pressures()37-element Vector{Int64}:
+    Pressure Level   (hPa) : 900

Valid ERA5 Pressure-Levels in CDS

A list of valid ERA5 pressure-levels available directly from CDS can be retrieved using the function era5Pressures

ERA5Reanalysis.era5Pressures — Method
era5Pressures() -> parray :: Vector{Int}

Returns the a vector containing the 37 pressure levels available in ERA5 in hPa units.

Returns

  • parray : vector containing list of pressures in Int format and hPa units
source
julia> using ERA5Reanalysis
julia> era5Pressures()37-element Vector{Int64}:
     1
     2
     3
@@ -54,8 +54,8 @@
     ID :: AbstractString;
     throw :: Bool = true,
     dolog :: Bool = false
-) -> tf :: Bool

Extracts information of the Single-Level Variable with the ID ID. If no Single-Level Variable with this ID exists, an error is thrown.

Arguments

Returns

source
ERA5Reanalysis.isPressure — Function
isPressure(
+) -> tf :: Bool

Extracts information of the Single-Level Variable with the ID ID. If no Single-Level Variable with this ID exists, an error is thrown.

Arguments

  • RegID : The keyword ID that will be used to identify the Single-Level Variable. If the ID is not valid (i.e. not being used), then an error will be thrown.
  • throw : If true, then throws an error if RegID is not a valid Single-Level Variable identifier instead of returning the Boolean tf
  • dolog : If true, then return logging to screen along with results

Returns

  • tf : True / False
source
ERA5Reanalysis.isPressure — Function
isPressure(
     ID :: AbstractString;
     throw :: Bool = true,
     dolog :: Bool = false
-) -> tf :: Bool

Extracts information of the Pressure-Level Variable with the ID ID. If no Pressure-Level Variable with this ID exists, an error is thrown.

Arguments

  • RegID : The keyword ID that will be used to identify the Pressure-Level Variable. If the ID is not valid (i.e. not being used), then an error will be thrown.
  • throw : If true, then throws an error if RegID is not a valid Pressure-Level Variable identifier instead of returning the Boolean tf
  • dolog : If true, then return logging to screen along with results

Returns

  • tf : True / False
source
julia> using ERA5Reanalysis
julia> isSingle("tcwv")true
+) -> tf :: Bool

Extracts information of the Pressure-Level Variable with the ID ID. If no Pressure-Level Variable with this ID exists, an error is thrown.

Arguments

Returns

source
julia> using ERA5Reanalysis
julia> isSingle("tcwv")true
diff --git a/dev/components/variables/reset.html b/dev/components/variables/reset.html index 2cf828a..5aadcb9 100644 --- a/dev/components/variables/reset.html +++ b/dev/components/variables/reset.html @@ -1,2 +1,2 @@ -Resetting ERA5 Variables · ERA5Reanalysis.jl
GitHub

Resetting the ERA5Variable Lists

We can reset the list of ERA5Variables back to the default predefined list using the function resetERA5Variables(). Alternatively, if we only want to reset SingleLevel or PressureLevel variables, we can use resetSingles() or resetPressures().

For the resetERA5Variables() and resetSingles() functions, the allfiles keyword will reset the list of SingleVariable variables as well, instead of just the list of SingleCustom variables.

ERA5Reanalysis.resetERA5Variables — Function
resetERA5Variables( allfiles :: Bool ) -> nothing

Reset the list of Single-Level and PressureCustom variables.

Arguments

  • allfiles : If false, only get rid of all the SingleCustom variables, but if true, then the SingleVariable list will be reset back to the default for ERA5Reanalysis.jl
source
ERA5Reanalysis.resetSingles — Function
resetSingles( allfiles :: Bool ) -> nothing

Reset the list of Single-Level variables.

Arguments

  • allfiles : If false, only get rid of all the SingleCustom variables, but if true, then the SingleVariable list will be reset back to the default for ERA5Reanalysis.jl
source
+Resetting ERA5 Variables · ERA5Reanalysis.jl
GitHub

Resetting the ERA5Variable Lists

We can reset the list of ERA5Variables back to the default predefined list using the function resetERA5Variables(). Alternatively, if we only want to reset SingleLevel or PressureLevel variables, we can use resetSingles() or resetPressures().

For the resetERA5Variables() and resetSingles() functions, the allfiles keyword will reset the list of SingleVariable variables as well, instead of just the list of SingleCustom variables.

ERA5Reanalysis.resetERA5Variables — Function
resetERA5Variables( allfiles :: Bool ) -> nothing

Reset the list of Single-Level and PressureCustom variables.

Arguments

  • allfiles : If false, only get rid of all the SingleCustom variables, but if true, then the SingleVariable list will be reset back to the default for ERA5Reanalysis.jl
source
ERA5Reanalysis.resetSingles — Function
resetSingles( allfiles :: Bool ) -> nothing

Reset the list of Single-Level variables.

Arguments

  • allfiles : If false, only get rid of all the SingleCustom variables, but if true, then the SingleVariable list will be reset back to the default for ERA5Reanalysis.jl
source
diff --git a/dev/index.html b/dev/index.html index 6be50d3..02dde47 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,3 +1,3 @@ Home · ERA5Reanalysis.jl
GitHub

ERA5Reanalysis.jl

Managing ERA5 Reanalysis Datasets

ERA5Reanalysis.jl is a Julia package that aims to streamline the following processes:

  • downloads of ERA5 Datasets from the Climate Data Store (does not include MARS requests)
  • basic analysis of said datasets
  • perform all the above operations innately over a given geographical region using the GeoRegion functionality of GeoRegions.jl (v2 and above)

Installation Instructions

ERA5Reanalysis.jl has not been officially registered as a Julia package yet. To install it, add it directly using the GitHub link as follows:

julia> ]
-(@v1.6) pkg> add https://github.com/natgeo-wong/ERA5Reanalysis.jl.git

The Basic Components of ERA5Reanalysis.jl

There are three essential components to specifying an ERA5 reanalysis dataset:

  1. The ERA5 dataset (hourly, monthly, month-by-hour, etc.), held in an ERA5Dataset supertype
  2. The ERA5 variable (single-level, or pressure-level), held in the ERA5Variable supertype
  3. The ERA5 region to be downloaded/analyzed, held in an ERA5Region supertype, built over a GeoRegion

Documentation Overview

The documentation for ERA5Reanalysis.jl is divided into three components:

  1. Tutorials - meant to introduce the three key components of ERA5Reanalysis.jl: (a) ERA5Dataset Types that specify the ERA5 Dataset of interest (b) ERA5Variable Types that specifiy the Single- and Pressure-level Variables of interest (c) ERA5Region Type that specifies the Geographic Regions of interest
  2. How-to Examples - geared towards those looking for specific examples of what can be done
  3. API Reference - comprehensive summary of all exported functionalities
Obtaining Example Datasets

All the output for the coding examples were produced using my computer with key security information (such as login info) omitted. The examples cannot be run online because the file size requirements are too big. Copying and pasting the code examples (with relevant directory and login information changes) should produce the same results.

Getting help

If you are interested in using ERA5Reanalysis.jl or are trying to figure out how to use it, please feel free to ask me questions and get in touch! Please feel free to open an issue if you have any questions, comments, suggestions, etc!

+(@v1.6) pkg> add https://github.com/natgeo-wong/ERA5Reanalysis.jl.git

The Basic Components of ERA5Reanalysis.jl

There are three essential components to specifying an ERA5 reanalysis dataset:

  1. The ERA5 dataset (hourly, monthly, month-by-hour, etc.), held in an ERA5Dataset supertype
  2. The ERA5 variable (single-level, or pressure-level), held in the ERA5Variable supertype
  3. The ERA5 region to be downloaded/analyzed, held in an ERA5Region supertype, built over a GeoRegion

Documentation Overview

The documentation for ERA5Reanalysis.jl is divided into three components:

  1. Tutorials - meant to introduce the three key components of ERA5Reanalysis.jl: (a) ERA5Dataset Types that specify the ERA5 Dataset of interest (b) ERA5Variable Types that specifiy the Single- and Pressure-level Variables of interest (c) ERA5Region Type that specifies the Geographic Regions of interest
  2. How-to Examples - geared towards those looking for specific examples of what can be done
  3. API Reference - comprehensive summary of all exported functionalities
Obtaining Example Datasets

All the output for the coding examples were produced using my computer with key security information (such as login info) omitted. The examples cannot be run online because the file size requirements are too big. Copying and pasting the code examples (with relevant directory and login information changes) should produce the same results.

Getting help

If you are interested in using ERA5Reanalysis.jl or are trying to figure out how to use it, please feel free to ask me questions and get in touch! Please feel free to open an issue if you have any questions, comments, suggestions, etc!

diff --git a/dev/using/download.html b/dev/using/download.html index 8e51af2..50a330e 100644 --- a/dev/using/download.html +++ b/dev/using/download.html @@ -4,10 +4,10 @@ <ERA5Variable>, <ERA5Region>, kwargs... -)

See below for the different examples and methods. Note that downloading a PressureVariable is a bit more complicated and involved than downloading a SingleVariable because we need to also specify the range of pressures to download the data from the CDS when a PressureVariable is chosen.

Setting up the CDSAPI Key

In order for your downloads to work with ERA5Reanalysis, you first need to set up your CDSAPI key. To do this, you must first register with the Climate Data Store in order to obtain your key here.

Then, you can either follow the instructions above in the API-how-to, or you can simply use the function addCDSAPIkey() to do it for you if you don't want to fiddle around with hidden files and the like.

So, example

julia> using ERA5Reanalysis
julia> ckeys = ERA5Reanalysis.cdskey()[ Info: 2024-02-19T23:15:31.393 - CDSAPI - Loading CDSAPI credentials from /home/runner/.cdsapirc ...
+)

See below for the different examples and methods. Note that downloading a PressureVariable is a bit more complicated and involved than downloading a SingleVariable because we need to also specify the range of pressures to download the data from the CDS when a PressureVariable is chosen.

Setting up the CDSAPI Key

In order for your downloads to work with ERA5Reanalysis, you first need to set up your CDSAPI key. To do this, you must first register with the Climate Data Store in order to obtain your key here.

Then, you can either follow the instructions above in the API-how-to, or you can simply use the function addCDSAPIkey() to do it for you if you don't want to fiddle around with hidden files and the like.

So, example

julia> using ERA5Reanalysis
julia> ckeys = ERA5Reanalysis.cdskey()[ Info: 2024-02-20T03:36:34.449 - CDSAPI - Loading CDSAPI credentials from /home/runner/.cdsapirc ...
 Dict{Any, Any} with 2 entries:
   "key" => "199699:c52da207-6f7d-4ae8-bd33-085246faee6e"
-  "url" => "https://cds.climate.copernicus.eu/api/v2"
julia> addCDSAPIkey("<your-key-here>")[ Info: 2024-02-19T23:15:31.582 - CDSAPI - Existing .cdsapirc file detected at /home/runner/.cdsapirc, since overwrite options is not selected, leaving file be ...  ...

See the API below for more details.

Examples

The following is the most basic download example

using ERA5Reanalysis
+  "url" => "https://cds.climate.copernicus.eu/api/v2"
julia> addCDSAPIkey("<your-key-here>")[ Info: 2024-02-20T03:36:34.649 - CDSAPI - Existing .cdsapirc file detected at /home/runner/.cdsapirc, since overwrite options is not selected, leaving file be ...  ...

See the API below for more details.

Examples

The following is the most basic download example

using ERA5Reanalysis
 e5ds = ERA5Hourly(start=Date(2015),stop=Date(2015))
 evar = SingleVariable("t2m")
 egeo = ERA5Region("AR6_SEA")
@@ -20,18 +20,18 @@
     url :: AbstractString = "https://cds.climate.copernicus.eu/api/v2",
     filename  :: AbstractString = ".cdsapirc",
     overwrite :: Bool = false
-) -> nothing

Adds the user's CDSAPI key to a file in the homedir() (by default specified as .cdsapirc)

Arguments

Keyword Arguments

source
Base.download — Method
download(
+) -> nothing

Adds the user's CDSAPI key to a file in the homedir() (by default specified as .cdsapirc)

Arguments

  • key : The user's CDSAPI key

Keyword Arguments

  • url : The user's CDSAPI key
  • filename : The name of the file the url and key are saved to in the homedir()
  • overwrite : If true and if filename already exists, then overwrite
source
Base.download — Method
download(
     e5ds :: Union{ERA5Hourly,ERA5Monthly},
     evar :: SingleVariable,
     ereg :: ERA5Region;
     ispy :: Bool = false,
     overwrite :: Bool = false
-) -> nothing

Downloads ERA5 data from the CDS datastore for a specified Single-Level variable and geographic region. You can specify to download via python scripts generated by selecting ispy to true, or to instead use Julia directly.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

  • e5ds : The ERA5Dataset specified (Hourly or Monthly)
    • e5ds.start defines the start date
    • e5ds.stop defines the end date
    • e5ds.path defines the path to which all reanalysis data is saved
  • evar : Specifies the Single-Level variable to be downloaded
  • ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
  • ipsy : Specifies whether to generate a python script that can be used to download the data instead of Julia
  • overwrite : false by default. If set to true, existing data will be overwritten.
source
Base.download — Method
download(
+) -> nothing

Downloads ERA5 data from the CDS datastore for a specified Single-Level variable and geographic region. You can specify to download via python scripts generated by selecting ispy to true, or to instead use Julia directly.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

  • e5ds : The ERA5Dataset specified (Hourly or Monthly)
    • e5ds.start defines the start date
    • e5ds.stop defines the end date
    • e5ds.path defines the path to which all reanalysis data is saved
  • evar : Specifies the Single-Level variable to be downloaded
  • ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
  • ipsy : Specifies whether to generate a python script that can be used to download the data instead of Julia
  • overwrite : false by default. If set to true, existing data will be overwritten.
source
Base.download — Method
download(
     e5ds :: Union{ERA5Hourly,ERA5Monthly},
     evar :: Vector{SingleVariable},
     ereg :: ERA5Region;
     overwrite :: Bool = false
-) -> nothing

Downloads ERA5 data from the CDS datastore for a specified variable and geographic region. There is no python option for this method.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

  • e5ds : The ERA5Dataset specified (Hourly or Monthly)
    • e5ds.start defines the start date
    • e5ds.stop defines the end date
    • e5ds.path defines the path to which all reanalysis data is saved
  • evar : Specifies a vector of Single-Level variables to be downloaded in a temporary file. Once downloaded, the different variables will be extracted out and saved in their respective folders.
  • ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
  • overwrite : false by default. If set to true, existing data will be overwritten.
source
Base.download — Method
download(
+) -> nothing

Downloads ERA5 data from the CDS datastore for a specified variable and geographic region. There is no python option for this method.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

  • e5ds : The ERA5Dataset specified (Hourly or Monthly)
    • e5ds.start defines the start date
    • e5ds.stop defines the end date
    • e5ds.path defines the path to which all reanalysis data is saved
  • evar : Specifies a vector of Single-Level variables to be downloaded in a temporary file. Once downloaded, the different variables will be extracted out and saved in their respective folders.
  • ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
  • overwrite : false by default. If set to true, existing data will be overwritten.
source
Base.download — Method
download(
     e5ds :: Union{ERA5Hourly,ERA5Monthly},
     evar :: PressureVariable,
     ereg :: ERA5Region;
@@ -41,4 +41,4 @@
     pbot :: Int = 0,
     pvec :: Vector{Int} = [0],
     overwrite :: Bool = false
-) -> nothing

Downloads ERA5 data from the CDS datastore for a specified Pressure-Level variable and geographic region. You can choose to specify (1) one pressure level, (2) a vector of pressure levels or (3) a set of pressure levels defined by their top and bottom levels. A python option is also available, but this will generate python scripts for all pressure levels.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

  • e5ds : The ERA5Dataset specified (Hourly or Monthly)
    • e5ds.start defines the start date
    • e5ds.stop defines the end date
    • e5ds.path defines the path to which all reanalysis data is saved
  • evar : Specifies a Pressure-Level variable to be downloaded. By default (if pall is not selected), then the pressure level closest to what is specified in evar.hPa will be downloaded.
  • ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
  • ipsy : Specifies whether to generate a python script that can be used to download the data instead of Julia. If true, scripts for all pressure levels will be generated
  • pall : Indicates that we are selecting a range of pressure levels to be downloaded at the same time.
    • ptop : Indicates the pressure level at the top layer. ptop must be < pbot
    • pbot : Indicates the pressure level at the bottom layer. pbot must be > ptop
    • pvec : Defines a set of pressure levels to download. Overrides ptop and pbot
  • overwrite : false by default. If set to true, existing data will be overwritten.
source
+) -> nothing

Downloads ERA5 data from the CDS datastore for a specified Pressure-Level variable and geographic region. You can choose to specify (1) one pressure level, (2) a vector of pressure levels or (3) a set of pressure levels defined by their top and bottom levels. A python option is also available, but this will generate python scripts for all pressure levels.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

source diff --git a/dev/using/landsea/create.html b/dev/using/landsea/create.html index 2a8f06f..db8b415 100644 --- a/dev/using/landsea/create.html +++ b/dev/using/landsea/create.html @@ -30,4 +30,4 @@ σlat :: Int = 0, iterations :: Int = 100, FT = Float64 -) -> LandSea

Retrieve the Land-Sea Mask data for the ERA5Dataset specified.

Arguments

Keyword Arguments

source +) -> LandSea

Retrieve the Land-Sea Mask data for the ERA5Dataset specified.

Arguments

Keyword Arguments

source diff --git a/dev/using/landsea/intro.html b/dev/using/landsea/intro.html index 9bd2843..72d6be7 100644 --- a/dev/using/landsea/intro.html +++ b/dev/using/landsea/intro.html @@ -1,3 +1,3 @@ -What is a LandSea Dataset · ERA5Reanalysis.jl
GitHub

Land-Sea Mask Datasets

Similar to ETOPO 2022, NASA also provides global land-sea masks at the same resolution as the IMERG and TRMM datasets. NASAPrecipitation.jl - in a manner similar to GeoRegions.jl for ETOPO 2022 data - is able to retrieve the land-sea mask datasets provided by NASA that allows for us to easily distinguish between precipitation data points over land and over the ocean.

This land-sea mask is then saved into a LandSea data type, which is defined to be a subType of the LandSeaFlat abstract type in GeoRegions.jl.

Units for the Land-Sea Mask

For standardization purposes, NASAPrecipitation.jl converts the land-sea mask provided by NASA to the same units as the LandSea Dataset provided by GeoRegions.jl

0 represents fully ocean, while 1 represents fully land.

See the figure below:

landseamaskunits

ERA5Reanalysis.LandSea — Type
ERA5Reanalysis.LandSea <: GeoRegions.LandSeaTopo

Object containing information on the Land Sea mask for ERA5, a subType extension of the GeoRegions.LandSeaTopo superType

source
GeoRegions.AbstractLandSea — Type
AbstractLandSea

Abstract supertype for LandSea Datasets, with the following subtypes:

LandSeaTopo <: AbstractLandSea
-LandSeaFlat <: AbstractLandSea

Both LandSeaTopo and LandSeaFlat types contain the following fields:

  • lon - Vector containing the longitude points for the Land-Sea Dataset
  • lat - Vector containing the latitude points for the Land-Sea Dataset
  • lsm - Array containing data regarding the Land-Sea Mask. 1 is Land, 0 is Ocean, NaN is outside the bounds of the GeoRegion
  • mask - Mask determining if point is within the GeoRegion or not. 1 is true, 0 is false.

A LandSeaTopo type will also contain the following field:

  • z - Array containing data regarding the Orographic Height in meters. NaN is outside the bounds of the GeoRegion
source
+What is a LandSea Dataset · ERA5Reanalysis.jl
GitHub

Land-Sea Mask Datasets

Similar to ETOPO 2022, NASA also provides global land-sea masks at the same resolution as the IMERG and TRMM datasets. NASAPrecipitation.jl - in a manner similar to GeoRegions.jl for ETOPO 2022 data - is able to retrieve the land-sea mask datasets provided by NASA that allows for us to easily distinguish between precipitation data points over land and over the ocean.

This land-sea mask is then saved into a LandSea data type, which is defined to be a subType of the LandSeaFlat abstract type in GeoRegions.jl.

Units for the Land-Sea Mask

For standardization purposes, NASAPrecipitation.jl converts the land-sea mask provided by NASA to the same units as the LandSea Dataset provided by GeoRegions.jl

0 represents fully ocean, while 1 represents fully land.

See the figure below:

landseamaskunits

ERA5Reanalysis.LandSea — Type
ERA5Reanalysis.LandSea <: GeoRegions.LandSeaTopo

Object containing information on the Land Sea mask for ERA5, a subType extension of the GeoRegions.LandSeaTopo superType

source
GeoRegions.AbstractLandSea — Type
AbstractLandSea

Abstract supertype for LandSea Datasets, with the following subtypes:

LandSeaTopo <: AbstractLandSea
+LandSeaFlat <: AbstractLandSea

Both LandSeaTopo and LandSeaFlat types contain the following fields:

  • lon - Vector containing the longitude points for the Land-Sea Dataset
  • lat - Vector containing the latitude points for the Land-Sea Dataset
  • lsm - Array containing data regarding the Land-Sea Mask. 1 is Land, 0 is Ocean, NaN is outside the bounds of the GeoRegion
  • mask - Mask determining if point is within the GeoRegion or not. 1 is true, 0 is false.

A LandSeaTopo type will also contain the following field:

  • z - Array containing data regarding the Orographic Height in meters. NaN is outside the bounds of the GeoRegion
source