Adding what is a GeoRegion and predefined list

docs/make.jl

@@ -34,6 +34,20 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "GeoRegions" => [
+            "What is a GeoRegion?"  => "georegions/intro.md",
+            # "Creating GeoRegions"   => "georegions/create.md",
+            # "Predefined GeoRegions" => "georegions/predefined.md",
+            # "Retrieving GeoRegions" => "georegions/read.md",
+        ],
+        # "Tutorials" => [
+        #     "Is it in a GeoRegion?" => "using/isin.md",
+        #     "Custom GeoRegions"     => "using/custom.md",
+        # ],
+        "Listing `GeoRegion`s"   => [
+            # "API"     => "lists/api.md",
+            "Default" => "lists/default.md",
+        ],
     ],
 )
 

docs/src/georegions/intro.md

@@ -0,0 +1,18 @@
+# What is a GeoRegion?
+
+In essence, a `GeoRegion` is:
+* a geographical region of interest
+* identified by an `ID`
+* itself a subregion of a **parent** `GeoRegion` (identified by `pID`, which must itself 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.
+
+In GeoRegions.jl, we differentiate between several different types of GeoRegions:
+* Rectilinear GeoRegions are denoted by the `RectRegion` type, available in all version of GeoRegions.jl
+* Tilted rectangular GeoRegions are denoted by the `TiltRegion` type, available in ≥v6
+* Polygonal GeoRegions are denoted by the `PolyRegion` type, available in ≥v2
+```@docs
+GeoRegion
+```
+

docs/src/lists/default.md

@@ -0,0 +1,44 @@
+# Default List of Predefined GeoRegions
+```@example listgeo
+using GeoRegions
+resetGeoRegions(all=true);
+```
+
+## GeoRegions.jl's default region is the Globe
+
+```@example listgeo
+tableGeoRegions(custom=false)
+```
+
+## Giorgi & Francisco [2000]
+
+Add the `GF_` prefix to the 3-letter IDs given in Giorgi & Francisco [2000] to call GeoRegions adapted from this paper.  All GeoRegions are defined as the `RectRegion` type.
+
+!!! compat "Defined in GeoRegions > 1.1"
+    All `GF_*` domains are defined only in versions ≥1.1
+
+```@example listgeo
+tableRectRegions(giorgi=true)
+```
+
+## SREX Regions from Seneviratne et al. [2012]
+
+Add the `SRX_` prefix to the 3-letter IDs given in Seneviratne et al. [2012] to call GeoRegions adapted from this paper.  All GeoRegions are defined as the `PolyRegion` type, even though many of them are rectilinear.
+
+!!! compat "Defined in GeoRegions ≧ 2"
+    All `SRX_*` domains are defined only in versions ≥2
+
+```@example listgeo
+tablePolyRegions(srex=true)
+```
+
+## IPCC AR6 Regions from Iturbide et al., [2020]
+
+Add the `AR6_` prefix to the 3-letter IDs given in Iturbide et al., [2020] to call GeoRegions adapted from this paper.  All GeoRegions are defined as the `PolyRegion` type.
+
+!!! compat "Defined in GeoRegions ≧ 2"
+    All `AR6_*` domains are defined only in versions ≥2
+
+```@example listgeo
+tablePolyRegions(ar6=true)
+```

src/GeoRegions.jl

@@ -29,9 +29,10 @@ export
 Abstract supertype for geographical regions, with the following subtypes:
     
     RectRegion{ST<:AbstractString, FT<:Real} <: GeoRegion
+    TiltRegion{ST<:AbstractString, FT<:Real} <: GeoRegion
     PolyRegion{ST<:AbstractString, FT<:Real} <: GeoRegion
 
-Both `RectRegion` and `PolyRegion` types contain the following fields:
+All `GeoRegion` types contain the following fields:
 * `ID` - A `String` Type, the identifier for the GeoRegion
 * `pID` - A `String` Type, the identifier for the parent GeoRegion
 * `name` - A `String` Type, the full name of the GeoRegion
@@ -44,6 +45,13 @@ Both `RectRegion` and `PolyRegion` types contain the following fields:
 
 A `PolyRegion` type will also contain the following field:
 * `shape` - A vector of `Point2` Types, defining a non-rectilinear shape of the GeoRegion
+
+A `TiltRegion` type will also contain the following field:
+- `X`  : Longitude coordinate of region centre
+- `Y`  : Latitude coordinate of region centre
+- `θ`  : Tilt of rectangular region in **degrees** in the clockwise direction
+- `ΔX` : Half-width in longitude coordinates (before tilting)
+- `ΔY` : Half-width in latitude coordinates (before tilting)
 """
 abstract type GeoRegion end
 
@@ -76,15 +84,15 @@ struct TiltRegion{ST<:AbstractString, FT<:Real} <: GeoRegion
     ID    :: ST
     pID   :: ST
     name  :: ST
-    X     :: FT
-    Y     :: FT
-    ΔX    :: FT
-    ΔY    :: FT
-    θ     :: FT
     N     :: FT
     S     :: FT
     E     :: FT
     W     :: FT
+    X     :: FT
+    Y     :: FT
+    θ     :: FT
+    ΔX    :: FT
+    ΔY    :: FT
     is180 :: Bool
     is360 :: Bool
 end