From f9cec089f5d018ca90f5fa884dccc7359922432a Mon Sep 17 00:00:00 2001 From: Nathanael Wong Date: Sat, 7 Sep 2024 14:13:04 -0400 Subject: [PATCH] Updating documentation --- docs/make.jl | 7 ++- docs/src/georegions/create.md | 62 ------------------------- docs/src/georegions/intro.md | 2 +- docs/src/georegions/using/overview.md | 48 +++++++++++++++++++ docs/src/georegions/using/polyregion.md | 24 ++++++++++ docs/src/georegions/using/rectregion.md | 32 +++++++++++++ 6 files changed, 111 insertions(+), 64 deletions(-) delete mode 100644 docs/src/georegions/create.md create mode 100644 docs/src/georegions/using/overview.md create mode 100644 docs/src/georegions/using/polyregion.md create mode 100644 docs/src/georegions/using/rectregion.md diff --git a/docs/make.jl b/docs/make.jl index 877e66e8..a4dc9571 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -37,7 +37,12 @@ makedocs(; "GeoRegions" => [ "What is a GeoRegion?" => "georegions/intro.md", "Predefined GeoRegions" => "georegions/predefined.md", - "Creating GeoRegions" => "georegions/create.md", + "Using GeoRegions.jl" => [ + "An Overview" => "georegions/using/overview.md", + "RectRegion Example" => "georegions/using/rectregion.md", + "PolyRegion Example" => "georegions/using/polyregion.md", + "TiltRegion Example" => "georegions/using/tiltregion.md", + ] # "Retrieving GeoRegions" => "georegions/read.md", ], # "Tutorials" => [ diff --git a/docs/src/georegions/create.md b/docs/src/georegions/create.md deleted file mode 100644 index ef512f9c..00000000 --- a/docs/src/georegions/create.md +++ /dev/null @@ -1,62 +0,0 @@ -# Defining new GeoRegions - -Recall that there are three different types of `GeoRegion`s: (a) `RectRegion`s, (b) `TiltRegion`s and (c) `PolyRegion`s. - -We use the functions `RectRegion()`, `TiltRegion()` and `PolyRegion` to create new `GeoRegion`s of their respective types. -!!! warning "New GeoRegions are no longer automatically saved in GeoRegions.jl ≥ v7" - As of GeoRegions.jl ≥v7, the abovementioned functions no longer automatically save GeoRegions.jl into the directory `joinpath(DEPOT_PATH[1],"files","GeoRegions")`. If you wish to automatically save new GeoRegions **as they are created** by these functions, specify the keyword argument `save = true`. - -Regardless of `GeoRegion` type, the **first three inputs are always the same**, in respective order: -1. The ID (`ID`) -2. parent `GeoRegion` ID, (`pID`) -3. Name of the GeoRegion (`name`) - -!!! warning "Constraints on `ID` and `pID` when `save = true`" - When `save = true`, the GeoRegion `pID` must already have been previously defined, and the region defined by the GeoRegion `ID` must be entirely within the region defined by the GeoRegion `pID`. - -## Defining New `RectRegion`s - -Out of all three `GeoRegion` types currently available, the `RectRegion` is most straightforward to define. All you need to do is specify the `[N, S, E, W]` boundaries, in that order. - -For example, we construct the sample `RectRegion` `TRR` - -```@repl -using GeoRegions -RectRegion("TRR","GLB","Test Rectangle Region",[30,20,50,10]) -``` - -!!! tip "Constraints on N, S, E, W bounds" - The following are the constraints on the North, South, East and West bounds: - 1. N > S - 2. E > W - 3. -90 ≤ N,S ≤ 90 - 4. -180 ≤ E,W ≤ 360 - 5. (E - W) < 360 - -```@docs -RectRegion( - ::AbstractString, ::AbstractString, ::AbstractString, - ::Vector{<:Real} -) -``` - -## Defining New `PolyRegion`s - -Out of all three `GeoRegion` types currently available, the `PolyRegion` grants the most flexibility in terms of specification of the domain shape. With it, you can specify any closed polygon on a rectilinear grid using two vectors, for `lon` and `lat` respectively. - -For example, we construct the sample `RectRegion` `TPR`, with longitude (`lon`) and latitude (`lat`) vectors of `[30,40,50,40,30]` and `[20,30,20,10,20]` - -```@repl -using GeoRegions -PolyRegion("TPR","GLB","Test Polygonal Region",[30,40,50,40,30],[20,30,20,10,20]) -``` - -!!! tip "Longitude and Latitude Vectors must be the same length" - As state in the header, the `lon` and `lat` vectors must be of the same length. - -```@docs -PolyRegion( - ::AbstractString, ::AbstractString, ::AbstractString, - ::Vector{<:Real}, ::Vector{<:Real} -) -``` \ No newline at end of file diff --git a/docs/src/georegions/intro.md b/docs/src/georegions/intro.md index 578124a6..51876087 100644 --- a/docs/src/georegions/intro.md +++ b/docs/src/georegions/intro.md @@ -6,7 +6,7 @@ In essence, a `GeoRegion` is: * a subregion of a **parent** `GeoRegion` (identified by `pID`, which must also be a valid `ID`) !!! tip "Default GeoRegions" - When using `GeoRegions.jl`, the default `GeoRegion` should generally be the global domain, specified by `GLB` and given by the `[N,S,E,W]` coordinates `[90,-90,360,0]`. The Global GeoRegion `GLB` is considered to be a subset of itself. + When using GeoRegions.jl, the default `GeoRegion` should generally be the global domain, specified by `GLB` and given by the `[N,S,E,W]` coordinates `[90,-90,360,0]`. The Global GeoRegion `GLB` is considered to be a subset of itself. ```@docs GeoRegion diff --git a/docs/src/georegions/using/overview.md b/docs/src/georegions/using/overview.md new file mode 100644 index 00000000..6c432e5c --- /dev/null +++ b/docs/src/georegions/using/overview.md @@ -0,0 +1,48 @@ +# Using GeoRegions.jl to specify custom GeoRegions + +Recall that there are three different types of `GeoRegion`s: (a) `RectRegion`s, (b) `TiltRegion`s and (c) `PolyRegion`s. + +## Creating new GeoRegions + +We use the functions `RectRegion()`, `TiltRegion()` and `PolyRegion` to create new `GeoRegion`s of their respective types. Regardless of `GeoRegion` type, the **first three inputs are always the same**, in respective order: +1. The ID (`ID`) +2. parent `GeoRegion` ID, (`pID`) +3. Name of the GeoRegion (`name`) + +```julia +RectRegion(ID, pID, name, ...) +TiltRegion(ID, pID, name, ...) +PolyRegion(ID, pID, name, ...) +``` + +!!! warning "Constraints on `ID` and `pID` when `save = true`" + When `save = true`, the GeoRegion `pID` must already have been previously defined, and the region defined by the GeoRegion `ID` must be entirely within the region defined by the GeoRegion `pID`. + +## Saving new GeoRegions + +As of `≥v7` and above, new GeoRegions are no longer automatically saved. If you wish to automatically save a new GeoRegions **as it is created**, specify the keyword argument `save = true`. To specify the directory to which the GeoRegion information is saved to, use the `path` keyword. + +* `RectRegion(ID, pID, name, ..., save = true, path = ...)` writes to `$path/rectlist.txt` +* `TiltRegion(ID, pID, name, ..., save = true, path = ...)` writes to `$path/tiltlist.txt` +* `PolyRegion(ID, pID, name, ..., save = true, path = ...)` writes to `$path/polylist.txt` + +!!! tip "Default `path` Directory" + By default, `path = joinpath(DEPOT_PATH[1],"files","GeoRegions")`. If `path` is not specified, the information will be saved in the respective custom lists in this directory. + +!!! warning "Modification of Custom Lists" + While it is possible to do manually modify the lists, it is not recommended to do so, especially for `polylist.txt`, which is pretty complicated. Instead, you should let GeoRegions.jl do most of the heavy lifting. + +You can also add a `GeoRegion` variable in the workspace that you have not yet saved into the custom lists + +```julia +geo = PolyRegion(ID, pID, name, ...) +add(geo, path = "") +``` + +## Calling saved GeoRegions + +If a GeoRegion has been saved to a `path`, it and its properties can be called using its `ID` using the function `GeoRegion()`. There is no need to specify the GeoRegion subtype, as `GeoRegion`s with the same `ID` **cannot** be saved to the same `path`, even if they are of different subtypes. + +```julia +geo = GeoRegion(ID, path = "") +``` \ No newline at end of file diff --git a/docs/src/georegions/using/polyregion.md b/docs/src/georegions/using/polyregion.md new file mode 100644 index 00000000..48b08d16 --- /dev/null +++ b/docs/src/georegions/using/polyregion.md @@ -0,0 +1,24 @@ +# Defining New `PolyRegion`s + +Out of all three `GeoRegion` types currently available, the `PolyRegion` grants the most flexibility in terms of specification of the domain shape. With it, you can specify any closed polygon on a rectilinear grid using two vectors, for `lon` and `lat` respectively. + +!!! tip "Longitude and Latitude Vectors must be the same length" + As state in the header, the `lon` and `lat` vectors must be of the same length. + +```julia +PolyRegion(ID, pID, name, lon, lat) +``` + +For example, we construct the sample `RectRegion` `TPR`, with longitude (`lon`) and latitude (`lat`) vectors of `[30,40,50,40,30]` and `[20,30,20,10,20]` + +```@repl +using GeoRegions +PolyRegion("TPR","GLB","Test Polygonal Region",[30,40,50,40,30],[20,30,20,10,20]) +``` + +```@docs +PolyRegion( + ::AbstractString, ::AbstractString, ::AbstractString, + ::Vector{<:Real}, ::Vector{<:Real} +) +``` \ No newline at end of file diff --git a/docs/src/georegions/using/rectregion.md b/docs/src/georegions/using/rectregion.md new file mode 100644 index 00000000..6b0c05b5 --- /dev/null +++ b/docs/src/georegions/using/rectregion.md @@ -0,0 +1,32 @@ +# Defining New `RectRegion`s + +Out of all three `GeoRegion` types currently available, the `RectRegion` is most straightforward to define. All you need to do is specify the `[N, S, E, W]` boundaries, in that order. + +```julia +RectRegion(ID, pID, name, [N, S, E, W]) +``` +## Example + +As an example construct the sample `RectRegion`, with `ID` `TRR`, `pID` `GLB` and with the `name` as `Test Rectangle Region` + +```@repl +using GeoRegions +RectRegion("TRR","GLB","Test Rectangle Region",[30,20,50,10]) +``` + +!!! tip "Constraints on N, S, E, W bounds" + The following are the constraints on the North, South, East and West bounds: + 1. N > S + 2. E > W + 3. -90 ≤ N,S ≤ 90 + 4. -180 ≤ E,W ≤ 360 + 5. (E - W) < 360 + +## API + +```@docs +RectRegion( + ::AbstractString, ::AbstractString, ::AbstractString, + ::Vector{<:Real} +) +``` \ No newline at end of file