From 88fbea8ce8ea24a5b9584c0df7b229c5ae52dbcd Mon Sep 17 00:00:00 2001 From: Nathanael Wong Date: Tue, 24 Sep 2024 17:14:36 -0400 Subject: [PATCH] MORE DOCUMENTATION CHANGES --- docs/make.jl | 6 +- .../api/{addreadremove.md => addreadrm.md} | 0 docs/src/basics/properties/isequal.md | 134 ++++++++++++++++++ docs/src/basics/read/predefined.md | 6 +- docs/src/basics/read/tables.md | 4 +- docs/src/tutorials/addreadrm.md | 68 +++++++++ docs/src/tutorials/projects.md | 47 +----- 7 files changed, 215 insertions(+), 50 deletions(-) rename docs/src/api/{addreadremove.md => addreadrm.md} (100%) create mode 100644 docs/src/basics/properties/isequal.md create mode 100644 docs/src/tutorials/addreadrm.md diff --git a/docs/make.jl b/docs/make.jl index 1a043131..1c25ef4f 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -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", ], diff --git a/docs/src/api/addreadremove.md b/docs/src/api/addreadrm.md similarity index 100% rename from docs/src/api/addreadremove.md rename to docs/src/api/addreadrm.md diff --git a/docs/src/basics/properties/isequal.md b/docs/src/basics/properties/isequal.md new file mode 100644 index 00000000..a9e1eeaa --- /dev/null +++ b/docs/src/basics/properties/isequal.md @@ -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) +``` \ No newline at end of file diff --git a/docs/src/basics/read/predefined.md b/docs/src/basics/read/predefined.md index 4a526af7..380962d4 100644 --- a/docs/src/basics/read/predefined.md +++ b/docs/src/basics/read/predefined.md @@ -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] @@ -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] @@ -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]) \ No newline at end of file +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]) \ No newline at end of file diff --git a/docs/src/basics/read/tables.md b/docs/src/basics/read/tables.md index 48cfcfc1..d842dc4b 100644 --- a/docs/src/basics/read/tables.md +++ b/docs/src/basics/read/tables.md @@ -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 diff --git a/docs/src/tutorials/addreadrm.md b/docs/src/tutorials/addreadrm.md new file mode 100644 index 00000000..716f017c --- /dev/null +++ b/docs/src/tutorials/addreadrm.md @@ -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")) +``` \ No newline at end of file diff --git a/docs/src/tutorials/projects.md b/docs/src/tutorials/projects.md index 5068c04a..ba7051a6 100644 --- a/docs/src/tutorials/projects.md +++ b/docs/src/tutorials/projects.md @@ -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. @@ -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()`. @@ -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 ``` \ No newline at end of file