Skip to content

Commit

Permalink
MORE DOCUMENTATION CHANGES
Browse files Browse the repository at this point in the history
  • Loading branch information
natgeo-wong committed Sep 24, 2024
1 parent e074ef5 commit 88fbea8
Show file tree
Hide file tree
Showing 7 changed files with 215 additions and 50 deletions.
6 changes: 4 additions & 2 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -31,17 +31,19 @@ makedocs(;
"GeoRegion Properties" => [
"Shape of a GeoRegion" => "basics/properties/shape.md",
"Is it in a GeoRegion?" => "basics/properties/isin.md",
"Equivalent GeoRegions" => "basics/properties/isequal.md",
]
],
"Tutorials" => [
"Project Setup (START HERE)" => "tutorials/projects.md",
"Project Setup (START HERE)" => "tutorials/addreadrm.md",
"Custom GeoRegion Files" => "tutorials/files.md",
],
"API" => [
"Creation" => "api/create.md",
# "Add" => "api/add.md",
"Add" => "api/addreadrm.md",
# "Read" => "api/read.md",
# "Tables" => "api/tables.md",
"Tables" => "api/tables.md",
],
"Ecosystem" => "ecosystem.md",
],
Expand Down
File renamed without changes.
134 changes: 134 additions & 0 deletions docs/src/basics/properties/isequal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# Is it in a GeoRegion?

When dealing with geographic data, we often wish to check if a point or region is inside another region. GeoRegions.jl allows you to perform this check easily with the function `isinGeoRegion`.

!!! note "Point Type"
We use the `Point2` Type from the package GeometryBasics.jl, which is reexported by GeoRegions.jl, as an easy way to denote points. This also allows us to use the package PolygonOps.jl to determine if a point is inside a region.

```@example isin
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]
nothing
```

## Is a Point in a GeoRegion?

As an example, let us test if a point is in GeoRegion `AR6_EAO`, defined in the blue bounding box below. We define the below points:
* Point *A* at coordinates (-20,5)
* Point *B* at coordinates (340,5)
* Point *C* at coordinates (30,15)

```@example isin
A = Point2(-20,5)
B = Point2(340,5)
C = Point2(-45,-7.5)
geo = GeoRegion("AR6_EAO")
```

Here, we note that the coordinates of the GeoRegion (Equatorial Atlantic Ocean) are given in the bounds of (-180,180). It is trivial in this case to calculate if points A and C are within the bounds of the GeoRegion.

```@example isin
slon,slat = coordinates(geo)
aspect = (maximum(slon)-minimum(slon))/(maximum(slat)-minimum(slat))
fig = Figure()
ax = Axis(
fig[1,1],width=750,height=750/aspect,
limits=(minimum(slon)-2,maximum(slon)+2,minimum(slat)-2,maximum(slat)+2)
)
lines!(ax,clon,clat,color=:black,linewidth=3)
lines!(ax,slon,slat,linewidth=5)
scatter!(ax,A,markersize=20)
scatter!(ax,C,markersize=20)
resize_to_layout!(fig)
fig
```

By eye it is easy to see that Point A is inside the GeoRegion. However, C is not. Let us now see if we are able to corroborate this with GeoRegions.jl using the function `in()`

```@example isin
in(A,geo), # Point A
in(C,geo) # Point C
```

But what about Point B? Point B is also very obvious within the bounds of the GeoRegion, it is simply that the longitude of Point A is shifted by 360º such that it is now in the (0,360) coordinates frame. We see that this is of no concern to GeoRegions.jl, which can detect that it is within the bounds of the GeoRegion anyway.

```@example isin
in(B,geo)
```

## Is a GeoRegion inside a GeoRegion?

Since any arbitrary geographic region can be defined as a `GeoRegion`, the natural extension now is to determine if a GeoRegion is wholly within another GeoRegion.

Let us consider an arbitrary GeoRegion `BIG`, and other smaller GeoRegions `TS1-4` as defined below, and plot them on a map.

```@example isin
geo_BIG = PolyRegion(
"BIG","GLB","A Big Region",
[-120,-100,-100,-80,-30,15,45,75,90,115,120,105,85,45,20,-5,-45,-80,-120],
[0,10,30,50,40,50,55,44,32,30,12,8,5,0,-10,-30,-40,-43,0]
)
geo_TS1 = RectRegion("TS1","GLB","Test Region 1",[45,20,20,-70])
geo_TS2 = PolyRegion("TS2","GLB","Test Region 2",[60,90,110,90,60],[20,25,20,15,20])
geo_TS3 = PolyRegion(
"TS3","GLB","Test Region 3",
[-110,-98,-95,-90,-80,-100,-110,-110],
[0,10,20,15,5,0,-20,0]
)
geo_TS4 = PolyRegion(
"TS4","GLB","Test Region 4",
[300,325,330,355,330,325,320,300],
[-10,-5,0,-10,-30,-35,-20,-10]
)
slon_b,slat_b = coordinates(geo_BIG)
slon_1,slat_1 = coordinates(geo_TS1)
slon_2,slat_2 = coordinates(geo_TS2)
slon_3,slat_3 = coordinates(geo_TS3)
slon_4,slat_4 = coordinates(geo_TS4)
fig = Figure()
ax = Axis(
fig[1,1],width=750,height=750/2,
limits=(-180,180,-90,90)
)
lines!(ax,clon,clat,color=:black,linewidth=3)
lines!(ax,slon_b,slat_b,linewidth=5,color=:blue)
lines!(ax,slon_1,slat_1,linewidth=5,color=:red)
lines!(ax,slon_2,slat_2,linewidth=5,color=:green)
lines!(ax,slon_3,slat_3,linewidth=5,color=:red)
lines!(ax,slon_4.-360,slat_4,linewidth=5,color=:green)
resize_to_layout!(fig)
fig
```

We see by eye that GeoRegion `TS2` and `TS4` are in the `BIG` region, but the other GeoRegions are not. Now let us verify this with `isinGeoRegion()`

```@example isin
in(geo_TS1,geo_BIG),
in(geo_TS2,geo_BIG),
in(geo_TS3,geo_BIG),
in(geo_TS4,geo_BIG)
```

And we see that this is indeed the case.

## API

```@docs
in(
Point :: Point2{<:Real},
geo :: RectRegion;
)
in(::GeoRegion,::RectRegion)
in(::GeoRegion,::PolyRegion)
```
6 changes: 3 additions & 3 deletions docs/src/basics/read/predefined.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ using GeoRegions
GeoRegion("GF_WAF")
```

To see the full list of predefined GeoRegions from Giorgi & Francisco [2000], go [here](/basics/listall#Giorgi-and-Francisco-[2000])
To see the full list of predefined GeoRegions from Giorgi & Francisco [2000], go [here](/basics/read/listall#Giorgi-and-Francisco-[2000])

## SREX Regions adapted from Seneviratne et al. [2012]

Expand All @@ -28,7 +28,7 @@ using GeoRegions
GeoRegion("SRX_CNA")
```

To see the full list of predefined GeoRegions from Seneviratne et al. [2012], go [here]basics/listall#SREX-Regions-from-Seneviratne-et-al.-[2012])
To see the full list of predefined GeoRegions from Seneviratne et al. [2012], go [here](basics/read/listall#SREX-Regions-from-Seneviratne-et-al.-[2012])

## AR6 Regions adapted from Iturbide et al., [2020]

Expand All @@ -42,4 +42,4 @@ using GeoRegions
GeoRegion("AR6_EAS")
```

To see the full list of predefined GeoRegions from Iturbide et al., [2020], go [here](/basics/listall#IPCC-AR6-Regions-from-Iturbide-et-al.,-[2020])
To see the full list of predefined GeoRegions from Iturbide et al., [2020], go [here](/basics/read/listall#IPCC-AR6-Regions-from-Iturbide-et-al.,-[2020])
4 changes: 2 additions & 2 deletions docs/src/basics/read/tables.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Tabular Listings of GeoRegions

A list of GeoRegions and their basic properties can be called using the function `tableGeoRegions()`, which lists all available GeoRegions, both predefined and [user-defined](/tutorials/overview). You can also choose to list only predefined or user-customized GeoRegions by setting their respective keywords arguments to `true/false`.
A list of GeoRegions and their basic properties can be called using the function `tableGeoRegions()`, which lists all available GeoRegions, both predefined and [user-defined](/basics/create). You can also choose to list only predefined or user-customized GeoRegions by setting their respective keywords arguments to `true/false`.

```julia
tableGeoRegions(predefined = true/false, custom = true/false)
```

!!! tip "Additional Functionality for `tableGeoRegions()`"
It is possible to use `tableGeoRegions()` to list user-defined `GeoRegion`s in specific paths/directories. By default, it will list user-defined `GeoRegion`s saved into the path `joinpath(DEPOT_PATH[1],"files","GeoRegions")`. For more on user-defined GeoRegions and saving them as part of a larger project, refer to how to [setup](/tutorials/setup) GeoRegions.jl for a project. Full API documentation for `tableGeoRegions()` is given [here](/tutorials/overview#Table-of-user-defined-GeoRegions).
It is possible to use `tableGeoRegions()` to list user-defined `GeoRegion`s in specific paths/directories. By default, it will list user-defined `GeoRegion`s saved into the path `joinpath(DEPOT_PATH[1],"files","GeoRegions")`. For more on user-defined GeoRegions and saving them as part of a larger project, refer to how to [setup](/tutorials/projects) GeoRegions.jl for a project. Full API documentation for `tableGeoRegions()` is given [here](/api/tables).

## More specific lists of GeoRegions

Expand Down
68 changes: 68 additions & 0 deletions docs/src/tutorials/addreadrm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# 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 `GeoRegion`s for a project.

```@example addreadremove
using GeoRegions
mkpath(joinpath(pwd(),"test"))
setupGeoRegions(path=joinpath(pwd(),"test"))
```

## 1. Adding custom `GeoRegion`s 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.

* `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 = ...)
```

For example, we can do

```@example addreadremove
geo = PolyRegion("TSP","GLB","Test Save PolyRegion",[10,100,-50,10],[20,10,0,20])
add(geo,path=joinpath(pwd(),"test"))
```

Or we can just directly add the GeoRegion simultaneously when it is defined, as follows:

```@example addreadremove
RectRegion("TSR","GLB","Test Save RectRegion",[40,-20,14,-60],save=true,path=joinpath(pwd(),"test"))
```

## 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()`:

```@example addreadremove
tableGeoRegions(path=joinpath(pwd(),"test"),crop=true)
```

And we see that yes, we can confirm their addition to the files.

## 3. Reading and Retrieving GeoRegions for your Project

So now that we have

## 4. Removing a the custom GeoRegions list from your Project

Say you want to completely clear your project of custom GeoRegions, replacing them with new lists. You can just delete the files directly, or you can do `deleteGeoRegions()`.

!!! tip "Default `path` is `pwd()`"
For `deleteGeoRegions()`, the default `path` is the current directory `pwd()`.

```@example addreadremove
deleteGeoRegions(path=joinpath(pwd(),"test"))
```
47 changes: 4 additions & 43 deletions docs/src/tutorials/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,41 +31,7 @@ If any of these files already exist in `path`, they will not be overwritten. To
setupGeoRegions(path=pwd(),overwrite=true)
```

## 2. Adding custom `GeoRegion`s 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.

* `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 = ...)
```

For example, we can do

```@example projects
geo = PolyRegion("TSP","GLB","Test Save PolyRegion",[10,100,-50,10],[20,10,0,20])
add(geo,path=pwd())
```

Or we can just directly add the GeoRegion simultaneously when it is defined, as follows:

```@example projects
RectRegion("TSR","GLB","Test Save RectRegion",[40,-20,14,-60],save=true,path=pwd())
```

## 3. Listing out the custom `GeoRegion`s for your Project
## 2. Listing out the custom `GeoRegion`s for your Project

You can create a table of all the `GeoRegion`s that have been saved to `path` using `tableGeoRegions()` as follows.

Expand All @@ -79,9 +45,11 @@ For example, we create a table of user-defined and predefined GeoRegions for the
We always specify the custom user-defined GeoRegions first, because those are most relevant to a project.

```@example projects
tableGeoRegions(path=pwd(),crop=true)
tableGeoRegions(path=pwd(),predefined=false)
```

Note, we have no custom GeoRegions added, so there is nothing to list right now even though the files exist. If any of `rectlist.txt`, `polylist.txt` and `tiltlist.txt` are not present, a warning will be shown unless the keyword `warn = false` is set.

## 4. Removing a the custom GeoRegions list from your Project

Say you want to completely clear your project of custom GeoRegions, replacing them with new lists. You can just delete the files directly, or you can do `deleteGeoRegions()`.
Expand All @@ -99,11 +67,4 @@ And then we see if `rectlist.txt` exists!
isfile(joinpath(pwd(),"rectlist.txt")),
isfile(joinpath(pwd(),"polylist.txt")),
isfile(joinpath(pwd(),"tiltlist.txt"))
```

```@docs
setupGeoRegions
add
tableGeoRegions
deleteGeoRegions
```

0 comments on commit 88fbea8

Please sign in to comment.