Skip to content

Commit 5f74b3d

Browse files
joa-quimjoa-quim
committed
Add ecmwf funs
1 parent 04e3675 commit 5f74b3d

File tree

9 files changed

+283
-12
lines changed

9 files changed

+283
-12
lines changed

‎documentation/all_docs_ref/all_refs.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737

3838
| | | | | | | | |
3939
|:-----|:----|:----|:----|:----|:----|:----|:----|
40-
| \myreflink{maregrams} | \myreflink{mosaic} | \myreflink{pastplates} | \myreflink{seismicity} | \myreflink{weather} | \myreflink{wmsread} | | |
40+
| \myreflink{ecmwf} | \myreflink{gadm} | \myreflink{maregrams} | \myreflink{mosaic} | \myreflink{pastplates} | \myreflink{seismicity} | \myreflink{weather} | \myreflink{wmsread} |
4141

4242

4343
## Supplemental Modules (Potential methods)

‎documentation/utilities/binarize.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
11
# binarize
22

33
```julia
4-
Ibw = binarize(I::GMTimage, threshold::Int=0; band=1, revert=false) -> GMTimage
4+
Ibw = binarize(I::GMTimage, threshold::Int=0; band=1, , threshold::Int=0, revert=false) -> GMTimage
55
```
66

77
Convert an image to a binary image (black-and-white) using a threshold.
88

99
### Args
1010
- `I::GMTimage`: input image of type UInt8.
1111

12-
- `threshold::Int`: A number in the range [0 255]. If the default (`nothing`) is maintained,
13-
the threshold is computed using the \myreflink{isodata} method.
12+
- `threshold::Int`: A number in the range [0 255]. If the default (0) is kept and the keyword
13+
`threshold` is not used, then the threshold is computed using the \myreflink{isodata} method.
1414

1515
### Kwargs
16-
- band: If the `I` image has more than one band, use `band` to specify which one to binarize.
16+
- `band`: If the `I` image has more than one band, use `band` to specify which one to binarize.
17+
By default the first band is used.
18+
19+
- `threshold`: Alternative keyword argument to the positional `threshold` argument. Meaning, one can either
20+
use the `binarize(I, ??)` or `binarize(I, threshold=??)`.
1721

1822
- `revert`: If `true`, values below the threshold are set to 255, and values above the threshold are set to 0.
1923

‎documentation/utilities/ecmwf.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# ecmwf
2+
3+
```julia
4+
ecmwf(; filename="", cb::Bool=false, dataset="", params::AbstractString="", key::String="",
5+
url::String="", region="", format="netcdf", dryrun::Bool=false, verbose::Bool=true)
6+
```
7+
8+
Retrieves data from the Climate Data Store [CDS](https://cds.climate.copernicus.eu) service.
9+
10+
11+
---
12+
ecmwf(:forecast; levlist="", kw...)
13+
14+
Download forecast datasets or just some variables from the ECMWF. (see man after that of first mode)
15+
16+
17+
---
18+
Get ERA5 data from the Copernicus Climate Change Service (C3S) Climate Data Store (CDS) using the CDS API.
19+
20+
- `filename`: The name of the file to save the data to. If not provided, the function will generate a
21+
name based on the dataset and the data format.
22+
23+
- `cb`: A boolean indicating whether to use the clipboard contents. If true, the function will use the
24+
``clipboard()`` to fetch its contents. The clipboard should contain a valid API request code as generated
25+
by the CDS website. This site provides a ``Show API request`` button at the bottom of the download tab
26+
of each dataset. After clicking it, the user can copy the request code with a Control-C (or click ``Copy``
27+
button) which will and paste it into the clipboard.
28+
29+
- `dataset`: The name of the dataset to retrieve. This option can be skipped if the `dataset` option
30+
is provided in the `params` argument, or is included clipboard copy (the `cb` option is set to true).
31+
32+
- `params`: A JSON string containing the request parameters. This string should be in the format expected
33+
by the CDSAPI. When using input via this option the `dataset` option is mandatory.
34+
If you feel brave, you can create the request parametrs yourself and pass them as a two elements string
35+
vector with the output of the ``era5vars()`` and ``era5time()`` functions. In this case, a region selection
36+
and pressure levels, if desired, must be provided via the `region` and `levlist` options. The `region`
37+
option has the same syntax in all other GMT.jl modules that use it, _e.g._ the ``coast`` function.
38+
39+
- `key`: The API key for the CDSAPI server. Default is the value in the ``.cdsapirc`` file in the home directory.
40+
but if that file does not exist, the user can provide the `key` and `url` as arguments. Instructions on how
41+
to create the ``.cdsapirc`` file for your user account can be found at [CDS](https://cds.climate.copernicus.eu/how-to-api)
42+
43+
- `url`: The URL of the CDS API server. Default is https://cds.climate.copernicus.eu/api
44+
45+
- `levlist`: List of pressure levels to retrieve. It can be a string to select a unique level, or a vector
46+
of strings or Ints to select multiple levels. But it can also be a range of levels, e.g. "1000:-100:500".
47+
This option is only used when the `params` argument is provided as a string vector.
48+
49+
- `region`: Specify a region of a specific geographic area. It can be provided as a string with form "N/W/S/E"
50+
or a 4-element vector or tuple with numeric data. This option is only used when the `params` argument is
51+
provided as a string vector.
52+
53+
- `format`: The format of the data to download. Default is "netcdf". Other options is "grib".
54+
55+
- `dryrun`: A boolean indicating whether to print the `params` from the outputs of the `era5vars()` and
56+
`era5time()` functions. I this case, we just print the `params` and return without trying to download any file.
57+
58+
- `verbose`: A boolean indicating whether to print the attemps to connect to the CDS server. Default is true.
59+
60+
### Credits
61+
This function is based in part on bits of CDSAPI.jl but doesn't require any of the dependencies of that package.
62+
63+
Examples
64+
--------
65+
66+
```julia
67+
# Copy the following code by selecting it and pressing Ctrl-C
68+
69+
{"product_type": ["reanalysis"],
70+
"variable": [
71+
"10m_u_component_of_wind",
72+
"10m_v_component_of_wind"
73+
],
74+
"year": ["2024"],
75+
"month": ["12"],
76+
"day": ["06"],
77+
"time": ["16:00"],
78+
"data_format": "netcdf",
79+
"download_format": "unarchived",
80+
"area": [58, 6, 55, 9]
81+
}
82+
83+
# Now call the function but WARNING: DO NOT COPY_PASTE it as it would replace the clipboard contents
84+
ecmwf(dataset="reanalysis-era5-single-levels", cb=true)
85+
```
86+
87+
### Let's dare and build the request ourselves
88+
```julia
89+
var = era5vars(["t2m", "skt"]) # "t2m" is the 2m temperature and "skt" is the skin temperature
90+
datetime = era5time(hour=10:14);
91+
ecmwf(dataset="reanalysis-era5-land", params=[var, datetime], region=(-10, 0, 30, 45))
92+
```
93+
94+
95+
---
96+
ecmwf(:forecast; levlist="", kw...)
97+
98+
Download forecast data
99+
100+
101+
### Kwargs
102+
- `cube`: If true [the default], when downloading pressure levels variables, save them data as a netCDF 3D cubes instead
103+
of one file per layer (when `cube=false`).
104+
105+
- `date`: The date to select. It can be a string to select a unique date, a ``DateTime`` object, or a Int.
106+
Where the Int is the number of days to go back from today. If the Int is greater than 3, an error is raised.
107+
If the date is a string, it must be in the form YYYYMMDD or YYYY-MM-DD.
108+
109+
- `dryrun`: Print the URL of the requested data and return without trying to download anything.
110+
111+
- `format`: The format in which to save the downloaded data. It can be "grib" or "netcdf". Default is "netcdf".
112+
113+
- `levlist`: The pressure levels to select. It can be a string to select a unique pressure level,
114+
or a vector of strings or Ints to select multiple pressure levels.
115+
116+
- `model`: A string with the model to select. Either "ifs" or "aifs". Default is "ifs".
117+
118+
- `param, variable, var, vars`: The variable(s) to select. It can be a string to select a unique variable, or a vector
119+
of strings or Ints to select multiple variables. When variable(s) is requested, we download only those
120+
variables as separate files. The names of those files are the same as the variable names with the .grib2 extension.
121+
NOTE: Not specifying a variable will download the entire forecast grib file for each forecast step selected with the `step` option.
122+
123+
\textinput{common_opts/opt_R}
124+
125+
- `root`: The root URL of the CDS ERA5 dataset. Default is "https://data.ecmwf.int/forecasts".
126+
127+
- `step`: An Int with the forecast step to select.
128+
129+
- `stream`: The stream to select. It can be one of: "oper", "enfo", "waef", "wave", "scda", "scwv", "mmsf". Default is "oper".
130+
131+
- `time`: The time in hours to select. It can be a string a ``Time`` object, or a Int. What ever it is,
132+
it will floored to 0, 6, 12 or 18. The default is the current hour.
133+
134+
- `stream`: A string with the stream to select, it must be one of: "oper", "enfo", "waef", "wave", "scda", "scwv", "mmsf". Default is "oper".
135+
136+
- `type`: A string with the type of forecast to select, it must be one of: "fc", "ef", "ep", "tf". Default is "fc".
137+
138+
Example
139+
-------
140+
141+
Get the latest 10m wind and 2m temperature forecast for today.
142+
143+
```julia
144+
ecmwf(:forecast, vars=["10u", "2t"])
145+
```
146+
147+
148+
See Also
149+
--------
150+
151+
\myreflink{weather}, \myreflink{era5vars}, \myreflink{era5time}, \myreflink{listecmwfvars}

‎documentation/utilities/era5time.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# era5time
2+
3+
```julia
4+
era5time(; year="", month="", day="", hour="") -> String
5+
```
6+
7+
Select one or more date-times from a CDS ERA5 dataset.
8+
9+
This function returns a JSON formatted string that can be used as an input to the \myreflink{ecmwf} function `params` option.
10+
11+
- `year`: The year(s) to select. It can be a string to select a unique year, or a vector of strings or Ints to select multiple years.
12+
It can also be a range of years, e.g. "2010:2020".
13+
14+
- `month`: The month(s) to select. It can be a string to select a unique month, or a vector of strings or Ints to select multiple months.
15+
It can also be a range of months, e.g. "01:06".
16+
17+
- `day`: The day(s) to select. It can be a string to select a unique day, or a vector of strings or Ints to select multiple days.
18+
It can also be a range of days, e.g. "01:20".
19+
20+
- `hour`: The hour(s) to select. It can be a string to select a unique hour, or a vector of strings or Ints to select multiple hours.
21+
It can also be a range of hours, e.g. "01:10".
22+
23+
### Returns
24+
A string with the JSON formatted date-time.
25+
26+
Examples
27+
--------
28+
29+
```julia
30+
# All times in 2023
31+
var = era5time(year="2023")
32+
"\"year\": [\"2023\"],\n\"month\": [\"5\"],\n\"day\": [\"13\"],\n\"time\": [\"2\"],\n"
33+
```
34+
35+
See Also
36+
--------
37+
38+
\myreflink{ecmwf}, \myreflink{era5vars}, \myreflink{listecmwfvars}

‎documentation/utilities/era5vars.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# era5vars
2+
3+
```julia
4+
era5vars(varID; single::Bool=true, pressure::Bool=false) -> String
5+
```
6+
7+
Selec one or more variables from a CDS ERA5 dataset.
8+
9+
This function returns a JSON formatted string that can be used as an input to the \myreflink{ecmwf} function `params` option.
10+
See the \myreflink{listecmwfvars} function for a list of available variables.
11+
12+
### Args
13+
- `varID`: The variable name. It can be a string or a symbol to select a unique variavle, or a vector of
14+
strings/symbols to select multiple variables.
15+
16+
### Kwargs
17+
- `single`: If true, only single-level variables are listed. If false, pressure-level variables are listed [Default is true].
18+
19+
- `pressure`: If true, only pressure-level variables are listed. If false, single-level variables are listed.
20+
[Default is false].
21+
22+
### Returns
23+
A string with the JSON formatted variable name.
24+
25+
Examples
26+
--------
27+
28+
```julia
29+
# "t2m" is the 2m temperature and "skt" is the skin temperature
30+
var = era5vars(["t2m", "skt"])
31+
"\"variable\": [\n\t\"2m_temperature\",\n\t\"skin_temperature\"\n],"
32+
```
33+
34+
See Also
35+
--------
36+
37+
\myreflink{ecmwf}, \myreflink{era5time}, \myreflink{listecmwfvars}

‎documentation/utilities/findpeaks.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# findpeaks
22

33
```
4-
findpeaks(y, x=1:length(y); min_height=minimum(y), min_prom=minimum(y), min_dist=0, threshold=0)
4+
findpeaks(y, x=1:length(y); min_height=minimum(y), min_prom=minimum(y), min_dist=0, threshold=0; xsorted::Bool=false)
55
or
66
7-
findpeaks(D::GMTdataset; min_height=D.bbox[1], min_prom=zero(D[1]), min_dist=0, threshold=0)
7+
findpeaks(D::GMTdataset; min_height=D.bbox[1], min_prom=zero(D[1]), min_dist=0, threshold=0; xsorted::Bool=false)
88
```
99

1010
Returns indices of local maxima (sorted from highest peaks to lowest) in 1D array of real numbers.
@@ -35,8 +35,10 @@ The peaks are output in order of occurrence. This function is from the [Findpeak
3535
- `threshold`: Minimal difference (absolute value) between peak and neighboring points. Use this argument to have
3636
``findpeaks`` return only those peaks that exceed their immediate neighboring values by at least the value of `threshold`.
3737

38+
- `xsorted`: If true, the indices of local maxima are sorted in ascending order of `x`. Default is to sort by amplitude.
39+
3840
### Returns
39-
- `peaks`: A vector of indices of local maxima (sorted from highest peaks to lowest).
41+
- `peaks`: A vector of indices of local maxima (sorted from highest peaks to lowest when `xsorted=false`).
4042

4143
### Examples
4244

‎documentation/utilities/listecmwfvars.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# listecmwfvars
2+
3+
```julia
4+
listecmwfvars(source::Symbol=:reanalysis; single::Bool=true, levlist::Bool=false, contain::AbstractString="")
5+
```
6+
7+
Print a list of CDS ERA5 variables.
8+
9+
### Args
10+
- `source`: The source of the data. It can be either ``:reanalysis`` or ``:forecast``. Default is `:reanalysis`.
11+
12+
### Kwargs
13+
- `single`: If true, only single-level variables are listed. If false, pressure-level variables are listed [Default is true].
14+
15+
- `pressure`: If true, only pressure-level variables are listed. If false, single-level variables are listed.
16+
17+
- `contain`: A string to filter the variables by their Name. Only those containing this string (case sensitive)
18+
are listed. If not provided, all variables are listed.
19+
20+
Examples
21+
--------
22+
23+
Print all pressure-level variables.
24+
25+
```julia
26+
listecmwfvars(pressure=true)
27+
```
28+
29+
Print only single-level variables containing "Temperature" in their name from the foorecast datasets.
30+
31+
```julia
32+
listecmwfvars(:forecast, contain="Temperature")
33+
```
34+
35+
36+
See Also
37+
--------
38+
39+
\myreflink{ecmwf}, \myreflink{era5time}, \myreflink{era5vars}

‎documentation/utilities/mosaic.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ Get image tiles from a web map tiles provider for given longitude, latitude coor
5555
- `provider`: Tile provider name. Currently available options are (but for more details see the docs of the
5656
`getprovider` function, *i.e.* ``? getprovider``):
5757
- "Bing" (the default), "OSM", "Esri" or a custom provider.
58-
- A `Provider` type from the ``TileProviders.jl`` package. You must consult the documentation of that package
59-
for more details on how to choose a *provider*.
58+
- A `Provider` type from the [TileProviders.jl](https://github.com/JuliaGeo/TileProviders.jl) package.
59+
You must consult the documentation of that package for more details on how to choose a *provider*.
6060

6161
- `zoom`: Zoom level (0 for automatic). A number between 0 and ~19. The maximum is provider and area dependent.
6262
If `zoom=0`, the zoom level is computed automatically based on the `mapwidth` and `dpi` options.

‎documentation/utilities/weather.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
```julia
44
[D =] weather(lon=0.0, lat=0.0; city::String="", last=0, days=7, year::Int=0, starttime::Union{DateTime, String}="",
5-
endtime::Union{DateTime, String}="", variable="temperature_2m", debug=false, show=false, kw...)
5+
endtime::Union{DateTime, String}="", variable="temperature_2m", dryrun=false, show=false, kw...)
66
```
77

88
Plot and/or retrieve weather data obtained from the [Open-Meteo](https://open-meteo.com/en/docs) API.
@@ -39,7 +39,7 @@ that inspired this function, that is much smaller (~25 LOC) and has no further d
3939

4040
- `year`: An integer, restrict data download to this year.
4141

42-
- `debug`: Print the url of the requested data and return.
42+
- `dryrun`: Print the url of the requested data and return.
4343

4444
- `data`: The default is to make a seismicity map but if the `data` option is used (containing whatever)
4545
we return the data in a ``GMTdataset``

0 commit comments

Comments
 (0)