Manipulation of User-Defined GeoRegions.jl for your Project
In this tutorial, we will show you the ropes of adding, retrieving the information of, and removing GeoRegions for a project.
using GeoRegions
using DelimitedFiles
using CairoMakie
download("https://raw.githubusercontent.com/natgeo-wong/GeoPlottingData/main/coastline_resl.txt","coast.cst")
coast = readdlm("coast.cst",comments=true)
clon = coast[:,1]
clat = coast[:,2]
nothingWe start off by defining a test directory:
mkpath(joinpath(pwd(),"test"))
setupGeoRegions(path=joinpath(pwd(),"test"))1. Adding custom GeoRegions to your Project
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.
GeoRegion (ID, pID, name, ..., save = true, path = ...)writes to$path/.georegions/$ID.json
Default path Directory
By default, path = joinpath(homedir(),".georegions"). If path is not specified, the information will be saved in the respective custom lists in this directory.
You can also add a GeoRegion variable in the workspace that you have not yet saved into the custom lists
geo = GeoRegion(lon, lat, ID = ..., pID = ..., name = ..., ...)
add(geo, path = ...)For example, we can do
geo = GeoRegion(
[10,100,-50,10],[20,10,0,20],
ID = "TST", pID = "GLB", name = "Test Save GeoRegion 1"
)
add(geo,path=joinpath(pwd(),"test"))[ Info: 2025-03-08T02:30:37.967 - GeoRegions.jl - Adding the GeoRegion TST to the list.See the API here
Or we can just directly add the GeoRegion simultaneously when it is defined, as follows:
GeoRegion(
[3,8,5,3],[40,-20,14,40],
ID = "TST2", pID = "GLB", name = "Test Save GeoRegion 2",
save = true, path = joinpath(pwd(),"test")
)The GeoRegion TST2 has the following properties:
Region ID (ID) : TST2
Parent ID (pID) : GLB
Name (name) : Test Save GeoRegion 2
Bounds (N,S,E,W) : 40.0, -20.0, 8.0, 3.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions/TST2.json
Centroid (geometry.centroid) : [5.333333333333333, 11.333333333333334]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)See the API here
2. Check if GeoRegions have been added
Now that we have added some user-defined custom GeoRegions, let us see if they can be listed using tableGeoRegions():
tableGeoRegions(path=joinpath(pwd(),"test"),crop=true) ---------- ------------------------- -------- ------------------------------- ------------ -------------
ID Name Parent Bounds [N,S,E,W] Rotation θ Folder
---------- ------------------------- -------- ------------------------------- ------------ -------------
GLB Globe GLB [90.0, -90.0, 360.0, 0.0] 0.0 .files
TST Test Save GeoRegion 1 GLB [20.0, 0.0, 100.0, -50.0] 0.0 .georegions
TST2 Test Save GeoRegion 2 GLB [40.0, -20.0, 8.0, 3.0] 0.0 .georegions
GF_ALA Alaska GLB [75.0, 50.0, 255.0, 180.0] 0.0 GF
⋮ ⋮ ⋮ ⋮ ⋮ ⋮
AR6_WNA Western North America GLB [50.0, 33.8, -105.0, -130.0] 0.0 AR6
AR6_WSAF Western South Africa GLB [-10.0, -36.0, 25.0, 8.0] 0.0 AR6
AR6_WSB Western Siberia GLB [65.0, 45.0, 90.0, 60.0] 0.0 AR6
---------- ------------------------- -------- ------------------------------- ------------ -------------
108 rows omittedAnd we see that yes, we can confirm their addition to the files.
Alternatively, we can check if the IDs have been added using the function isID:
isID("TST",path=joinpath(pwd(),"test"))trueSee the API here
3. Reading and Retrieving GeoRegions for your Project
So now that we have saved information on the abovementioned user-defined GeoRegions, let's see if we can retrieve the information on these GeoRegions:
geo1 = GeoRegion("TST",path=joinpath(pwd(),"test"))The GeoRegion TST has the following properties:
Region ID (ID) : TST
Parent ID (pID) : GLB
Name (name) : Test Save GeoRegion 1
Bounds (N,S,E,W) : 20.0, 0.0, 100.0, -50.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions/TST.json
Centroid (geometry.centroid) : [20.0, 10.0]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)Let's try retrieving and plotting the shape of this GeoRegion
lon,lat = coordinates(geo1)
aspect = (geo1.E-geo1.W+4)/(geo1.N-geo1.S+4)
fig = Figure()
ax = Axis(
fig[1,1],width=750,height=750/aspect,
limits=(geo1.W-2,geo1.E+2,geo1.S-2,geo1.N+2)
)
lines!(ax,clon,clat,color=:black,linewidth=3)
lines!(ax,lon,lat,linewidth=5)
resize_to_layout!(fig)
fig
See the API here
3.1 Loading all custom GeoRegions for your Project
If you have multiple GeoRegions saved in your project and you want to load all of them as a vector, you can use the loadGeoRegions() function
geovec = loadGeoRegions(path=joinpath(pwd(),"test"))3-element Vector{GeoRegion}:
The GeoRegion GLB has the following properties:
Region ID (ID) : GLB
Parent ID (pID) : GLB
Name (name) : Globe
Bounds (N,S,E,W) : 90.0, -90.0, 360.0, 0.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/src/.files/GLB.json
Centroid (geometry.centroid) : [180.0, -0.0]
Shape (geometry.shape) : Vector{Point{2, Float64}}(5)
The GeoRegion TST has the following properties:
Region ID (ID) : TST
Parent ID (pID) : GLB
Name (name) : Test Save GeoRegion 1
Bounds (N,S,E,W) : 20.0, 0.0, 100.0, -50.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions/TST.json
Centroid (geometry.centroid) : [20.0, 10.0]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)
The GeoRegion TST2 has the following properties:
Region ID (ID) : TST2
Parent ID (pID) : GLB
Name (name) : Test Save GeoRegion 2
Bounds (N,S,E,W) : 40.0, -20.0, 8.0, 3.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions/TST2.json
Centroid (geometry.centroid) : [5.333333333333333, 11.333333333333334]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)Which returns a Vector of GeoRegion types.
GLB is automatically included
The GLB GeoRegion will automatically be included in this vector, so your vector will always have at least 1 element inside it.
See the API here
4. Overwriting Information for a Previously Defined GeoRegion
Once a GeoRegion associated with an ID has been saved into the directory named path, this ID can no longer be used in association with another GeoRegion for this Project. Therefore, you cannot save another GeoRegion of this ID into the same project.
julia> geo2 = GeoRegion(
[10,90,-50,10],[20,10,0,20],
ID = "TST", pID = "GLB", name = "Test Save PolyRegion 2"
)
The GeoRegion TST has the following properties:
Region ID (ID) : TST
Parent ID (pID) : GLB
Name (name) : Test Save PolyRegion 2
Bounds (N,S,E,W) : 20.0, 0.0, 90.0, -50.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/.georegions/TST.json
Centroid (geometry.centroid) : [16.666666666666668, 10.0]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)
julia> add(geo2,path=joinpath(pwd(),"test"))
ERROR: 2025-03-08T02:30:39.444 - GeoRegions.jl - The GeoRegion TST has already been defined. Please use another identifier.We see that we cannot add another GeoRegion with the ID = TSP. In order to replace the GeoRegion associated with this ID with another set of information, you need to overwrite the preexisting information with overwrite()
overwrite(geo2,path=joinpath(pwd(),"test"))[ Info: 2025-03-08T02:30:41.371 - GeoRegions.jl - Adding the GeoRegion TST to the list.And we reload the GeoRegion associated with the ID = TSP
geo3 = GeoRegion("TST",path=joinpath(pwd(),"test"))The GeoRegion TST has the following properties:
Region ID (ID) : TST
Parent ID (pID) : GLB
Name (name) : Test Save PolyRegion 2
Bounds (N,S,E,W) : 20.0, 0.0, 90.0, -50.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions/TST.json
Centroid (geometry.centroid) : [16.666666666666668, 10.0]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)See the API here
5. Removing a custom GeoRegions from your Project
Now, we've realized that you don't really need a GeoRegion anymore, or for some reason you want to delete the information of a particular GeoRegion associate with a certain ID and replace it with a new information, there are two ways to do it:
5.1 Removing a GeoRegion that has been loaded
THe first method is to remove a GeoRegion geo that has already been loaded into the workspace. We use the function rm() to do this
rm(geo3,path=joinpath(pwd(),"test"))[ Info: 2025-03-08T02:30:41.433 - GeoRegions.jl - Removing the GeoRegion TST ...And now we check if the GeoRegion TSP now exists:
julia> isID("TST",path=joinpath(pwd(),"test"))
ERROR: 2025-03-08T02:30:41.434 - GeoRegions.jl - TST is not a valid GeoRegion identifier, use GeoRegion() to add this GeoRegion to the list.And we see that it does not.
See the API here
5.2 Removing a GeoRegion based on its ID
The second method is to remove a GeoRegion based on an ID, or its string identifier. We do this with the function rmID()
rmID("TST2",path=joinpath(pwd(),"test"))[ Info: 2025-03-08T02:30:41.440 - GeoRegions.jl - Removing the GeoRegion TST2 ...julia> isID("TST2",path=joinpath(pwd(),"test"))
ERROR: 2025-03-08T02:30:41.441 - GeoRegions.jl - TST2 is not a valid GeoRegion identifier, use GeoRegion() to add this GeoRegion to the list.Predefined GeoRegions cannot be removed
You cannot remove GLB, GF_*, SRX_* or AR6_* that have been predefined in GeoRegions.jl
See the API here
6. Removing a the custom GeoRegions lists from your Project
If you use deleteGeoRegions() to remove all the custom lists, you will remove all the custom GeoRegions for the projects and they cannot be retrieved.
GeoRegion(
[3,8,5,3],[40,-20,14,40],
ID = "TST", pID = "GLB", name = "Test Save GeoRegion",
save = true, path = joinpath(pwd(),"test")
)The GeoRegion TST has the following properties:
Region ID (ID) : TST
Parent ID (pID) : GLB
Name (name) : Test Save GeoRegion
Bounds (N,S,E,W) : 40.0, -20.0, 8.0, 3.0
Rotation (θ) : 0.0
File Path (path) : /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions/TST.json
Centroid (geometry.centroid) : [5.333333333333333, 11.333333333333334]
Shape (geometry.shape) : Vector{Point{2, Float64}}(4)deleteGeoRegions(path=joinpath(pwd(),"test"))┌ Warning: 2025-03-08T02:30:41.488 - GeoRegions.jl - Removing custom GeoRegions.jl files from /home/runner/work/GeoRegions.jl/GeoRegions.jl/docs/build/tutorials/projects/test/.georegions, all GeoRegion information saved into these files will be permanently lost.
└ @ GeoRegions ~/work/GeoRegions.jl/GeoRegions.jl/src/georegions/project.jl:142Let's test and see if we can retrieve the user-defined GeoRegions now we have deleted their information from the project.
julia> isID("TST",path=joinpath(pwd(),"test"),throw=false)
false