GitHub

Creating GeoRegions

In this section, we go through the basic steps of creating a GeoRegion, and removing it once defined so it can be redefined.

Defining a new GeoRegion

We use the functions RectRegion and PolyRegion to define rectilinear and polygonal regions respectively. For example, we construct the sample RectRegion TRC

julia> using GeoRegions
julia> RectRegion("TRC","GLB","Test Rectangle Region",[30,20,50,10])[ Info: 2024-01-12T00:13:11.088 - GeoRegions.jl - Checking to see if the ID TRC is in use
┌ Warning: 2024-01-12T00:13:11.173 - GeoRegions.jl - TRC is not a valid GeoRegion identifier, use either RectRegion() or PolyRegion() to add this GeoRegion to the list.
└ @ GeoRegions ~/work/GeoRegions.jl/GeoRegions.jl/src/georegions/read.jl:489
[ Info: 2024-01-12T00:13:11.176 - GeoRegions.jl - Adding the GeoRegion TRC to the list.
[ Info: 2024-01-12T00:13:11.179 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID GLB
[ Info: 2024-01-12T00:13:11.651 - GeoRegions.jl - Performing a check to determine if the Test Rectangle Region GeoRegion (TRC) is inside the Globe GeoRegion (GLB)
[ Info: 2024-01-12T00:13:11.651 - GeoRegions.jl - The GeoRegion TRC (Test Rectangle Region) is indeed a subset of the GeoRegion GLB (Globe)
The Rectilinear Region TRC has the following properties:
    Region ID    (ID) : TRC
    Parent ID   (pID) : GLB
    Name      (name)  : Test Rectangle Region
    Bounds  (N,S,E,W) : [30.0, 20.0, 50.0, 10.0]
        (is180,is360) : (false, true)
julia> PolyRegion("TPL","GLB","Test Polygonal Region",[30,40,50,40,30],[20,30,20,10,20])[ Info: 2024-01-12T00:13:11.972 - GeoRegions.jl - Checking to see if the ID TPL is in use
┌ Warning: 2024-01-12T00:13:11.972 - GeoRegions.jl - TPL is not a valid GeoRegion identifier, use either RectRegion() or PolyRegion() to add this GeoRegion to the list.
└ @ GeoRegions ~/work/GeoRegions.jl/GeoRegions.jl/src/georegions/read.jl:489
[ Info: 2024-01-12T00:13:11.972 - GeoRegions.jl - Adding the GeoRegion TPL to the list.
[ Info: 2024-01-12T00:13:12.022 - GeoRegions.jl - Retrieving information for the GeoRegion defined by the ID GLB
[ Info: 2024-01-12T00:13:12.062 - GeoRegions.jl - Performing a check to determine if the Test Polygonal Region GeoRegion (TPL) is inside the Globe GeoRegion (GLB)
[ Info: 2024-01-12T00:13:12.062 - GeoRegions.jl - The GeoRegion TPL (Test Polygonal Region) is indeed a subset of the GeoRegion GLB (Globe)
The Polygonal Region TPL has the following properties:
    Region ID    (ID) : TPL
    Parent ID   (pID) : GLB
    Name       (name) : Test Polygonal Region
    Bounds  (N,S,E,W) : [30.0, 10.0, 50.0, 30.0]
    Shape     (shape) : Point2{Float64}[[30.0, 20.0], [40.0, 30.0], [50.0, 20.0], [40.0, 10.0], [30.0, 20.0]]
        (is180,is360) : (false, true)
Defining PolyRegions

When defining PolyRegions, the first and last set of (lon,lat) coordinates must be the same (i.e. a closed polygon must be defined)

The GeoRegions will be automatically added to the following files in joinpath(DEPOT_PATH[1],"files","GeoRegions"):

  • RectRegions will be added to rectlist.txt
  • PolyRegions will be added to polylist.txt

If the GeoRegion ID TRC already exists, however, this will throw an error

julia> using GeoRegions
julia> RectRegion("TRC","GLB","Test Rectangle Region2",[40,20,52,10])[ Info: 2024-01-12T00:13:12.324 - GeoRegions.jl - Checking to see if the ID TRC is in use
[ Info: 2024-01-12T00:13:12.324 - GeoRegions.jl - The ID TRC is already in use
ERROR: 2024-01-12T00:13:12.324 - GeoRegions.jl - The GeoRegion TRC has already been defined.  Please use another identifier.
GeoRegions.RectRegion — Method
RectRegion(
    RegID :: AbstractString,
    ParID :: AbstractString,
    name  :: AbstractString,
    bound :: Vector{<:Real};
    savegeo :: Bool = true,
    verbose :: Bool = true,
    ST = String,
    FT = Float64
) -> RectRegion{ST,FT}

Creates a rectilinear GeoRegion RegID.

Arguments

  • RegID : The keyword ID that will be used to identify the GeoRegion. If the ID is already in use, then an error will be thrown.
  • ParID : The ID of the parent GeoRegion where information can be extracted from
  • name : A name for the GeoRegion (meta information, can be used in Logging)
  • bound : The [N,S,E,W] coordinates defining the region

Keyword Arguments

  • savegeo : Save the GeoRegion into the master list? Default is true
  • verbose : Verbose logging for ease of monitoring? Default is true
source
GeoRegions.PolyRegion — Method
PolyRegion(
    RegID :: AbstractString,
    ParID :: AbstractString,
    name  :: AbstractString,
    lonpt :: Vector{<:Real},
    latpt :: Vector{<:Real};
    savegeo :: Bool = true,
    verbose :: Bool = true,
    ST = String,
    FT = Float64
) -> PolyRegion{ST,FT}

Creates a rectilinear GeoRegion RegID.

Arguments

  • RegID : The keyword ID that will be used to identify the GeoRegion. If the ID is already in use, then an error will be thrown.

  • ParID : The ID of the parent GeoRegion where information can be extracted from

  • name : A name for the GeoRegion (meta information, can be used in Logging)

  • lonpt : A vector containing the longitude points

  • latpt : A vector containing the latitude points

Keyword Arguments

  • savegeo : Save the GeoRegion into the master list? Default is true
  • verbose : Verbose logging for ease of monitoring? Default is true
Start and End Points

The 1st and last elements of lonpt and latpt must be equal.

source

Is it already a GeoRegion?

Sometimes we would like to independently check if an ID has already been used. We can use the function isGeoRegion() to perform this checkIf the GeoRegion IDTRC` already exists, however, this will throw an error

GeoRegions.isGeoRegion — Function
isGeoRegion(
    RegID :: AbstractString;
    throw :: Bool = true
) -> tf :: Bool

Extracts information of the GeoRegion with the ID RegID. If no GeoRegion with this ID exists, an error is thrown.

Arguments

  • RegID : The keyword ID that will be used to identify the GeoRegion. 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 GeoRegion identifier instead of returning the Boolean tf

Returns

  • tf : True / False
source
julia> using GeoRegions
julia> isGeoRegion("AR6_SEA")[ Info: 2024-01-12T00:13:12.907 - GeoRegions.jl - Checking to see if the ID AR6_SEA is in use
[ Info: 2024-01-12T00:13:12.907 - GeoRegions.jl - The ID AR6_SEA is already in use
true
julia> isGeoRegion("RND",throw=false)[ Info: 2024-01-12T00:13:12.918 - GeoRegions.jl - Checking to see if the ID RND is in use
┌ Warning: 2024-01-12T00:13:12.918 - GeoRegions.jl - RND is not a valid GeoRegion identifier, use either RectRegion() or PolyRegion() to add this GeoRegion to the list.
└ @ GeoRegions ~/work/GeoRegions.jl/GeoRegions.jl/src/georegions/read.jl:489
false
julia> isGeoRegion("RND")[ Info: 2024-01-12T00:13:12.919 - GeoRegions.jl - Checking to see if the ID RND is in use
ERROR: 2024-01-12T00:13:12.919 - GeoRegions.jl - RND is not a valid GeoRegion identifier, use either RectRegion() or PolyRegion() to add this GeoRegion to the list.

Removing an existing GeoRegion

To remove an existing GeoRegion, we can use the function removeGeoRegion

julia> using GeoRegions
julia> removeGeoRegion("TRC")[ Info: 2024-01-12T00:13:12.971 - GeoRegions.jl - Removing the GeoRegion TRC ...
Global GeoRegion

The Global GeoRegion GLB is considered to be an integral part of the GeoRegions.jl package and therefore it cannot be removed.

julia> using GeoRegions
julia> removeGeoRegion("GLB")ERROR: 2024-01-12T00:13:13.004 - GeoRegions.jl - The Global GeoRegion "GLB" is an integral part of the GeoRegions.jl package and cannot be removed.
GeoRegions.removeGeoRegion — Method
removeGeoRegion(RegID::AbstractString)

Creates the GeoRegion associated with the ID RegID.

Arguments

  • RegID : The keyword ID that will be used to identify the GeoRegion. If the ID is not valid (i.e. not being used), then an error will be thrown.
source

Reset the list of GeoRegions

Should one wish to entirely reset the list of GeoRegions, one can call resetGeoRegions(). See Custom GeoRegions for more details.