Basic documentation

docs/src/regiongrids/create.md

@@ -0,0 +1,92 @@
+# RegionGrid: Applying GeoRegions to Gridded Data
+
+In this section, we go through the basic steps of creating a RegionGrid for `RectRegion`s and `PolyRegion`s.  See if you can spot the differences between the RegionGrids generated by the two different types.
+
+### Setup
+
+````@example regiongrid
+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
+````
+
+## `RectGrid` Example
+
+````@example regiongrid
+geo  = GeoRegion("GF_SSA")
+lon  = -180:5:180
+lat  = -90:5:90
+ggrd = RegionGrid(geo,lon[1:(end-1)],lat)
+````
+
+## `PolyGrid` Example
+
+````@example regiongrid
+geo  = GeoRegion("AR6_NWS")
+lon  = -180:2:180;
+lat  = -90:2:90;
+ggrd = RegionGrid(geo,lon[1:(end-1)],lat)
+````
+
+So here, we see that in this `PolyGrid` example, the `RegionGrid` contains an additional field `mask` that, within the rectilinear longitude-latitude shape bounding the `GeoRegion` (because gridded data here is assumed to be rectilinear), the data is within the GeoRegion.  Values of `1` indicate it is within the GeoRegion, otherwise the values are `NaN.
+
+````@example regiongrid
+ggrd.mask
+````
+
+## The Mask of a `PolyGrid`
+
+The `PolyGrid` type derived from a `PolyRegion` allows us to apply a mask to filter out data that is within the `shape` of a `PolyRegion` on a rectilinear lon-lat grid defined by the `bound` of a PolyRegion.  We consider the following example of an AR6 region over South Asia:
+
+````@example regiongrid
+geo  = GeoRegion("AR6_SAS")
+lon  = -180:5:180;
+lat  = -90:2:90;
+ggrd = RegionGrid(geo,lon[1:(end-1)],lat)
+````
+
+And using the field mask, we plot the points that are in the region (blue), and out of the region (red).
+
+````@example regiongrid
+mask = ggrd.mask
+grid = ones(size(mask))
+inlon = grid .* ggrd.lon;  inlon = inlon[.!isnan.(mask)]
+inlat = grid .* ggrd.lat'; inlat = inlat[.!isnan.(mask)]
+otlon = grid .* ggrd.lon;  otlon = otlon[isnan.(mask)]
+otlat = grid .* ggrd.lat'; otlat = otlat[isnan.(mask)]
+blon,blat,slon,slat = coordGeoRegion(geo)
+
+fig = Figure()
+aspect = (maximum(slon)-minimum(slon))/(maximum(slat)-minimum(slat))
+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)
+lines!(ax,blon,blat)
+lines!(ax,slon,slat)
+scatter!(ax,otlon,otlat)
+scatter!(ax,inlon,inlat)
+
+resize_to_layout!(fig)
+fig
+````
+
+## API
+
+```@docs
+RegionGrid(::RectRegion,::Vector{<:Real},::Vector{<:Real})
+RegionGrid(::GeoRegion,::Array{<:Real,2},::Array{<:Real,2})
+```
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+

docs/src/regiongrids/intro.md

@@ -0,0 +1,14 @@
+# What is a RegionGrid?
+
+But how do we go from defining a GeoRegion, to **extracting data** for that GeoRegion?  The answer is with the information in the `RegionGrid` types, which maps gridded lon-lat data to a given GeoRegion as follows:
+* Mapping gridded lon-lat data to a **`RectRegion`** gives a `RectGrid` structure
+* Mapping gridded lon-lat data to a **`PolyRegion`** gives a `PolyGrid` structure
+* Mapping non-rectilinear gridded lon-lat data to a **`RegionMask`** gives a `RegionMask` structure
+
+However, the basic uses of `RectGrid` and `PolyGrid` are the same, and as such their differences are largely transparent to the user, except for one field found in `PolyGrid`, the `mask`, which will be elaborated upon later.
+
+```@docs
+RegionGrid
+```
+
+So basically a `RegionGrid` contains information on the indices of the gridded data that are part of the `GeoRegion`, thus helping us extract the relevant data for a given `GeoRegion`.

docs/src/using/extract.md

@@ -0,0 +1,96 @@
+```@meta
+EditURL = "<unknown>/literate/using/extract.jl"
+```
+
+# Extracting Gridded Data using RegionGrid
+
+Suppose we have Global Data.  However, we are only interested in a specific region (say, the North Central American region as defined in AR6), how do we extract data for this region?
+
+The simple answer is, we use the `extractGrid()` function, which takes in a `RegionGrid` and a data array, and returns a new data array for the GeoRegion.
+
+### Setup
+
+````@example extract
+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
+````
+
+## Let us define the GeoRegion of interest
+
+````@example extract
+geo  = GeoRegion("AR6_NCA")
+````
+
+We also define some sample test data in the global domain
+
+````@example extract
+lon = collect(0:360); pop!(lon); nlon = length(lon)
+lat = collect(-90:90);           nlat = length(lat)
+odata = randn((nlon,nlat))
+````
+
+Our next step is to define the RegionGrid based on the longitude and latitude vectors and their intersection with the GeoRegion
+
+````@example extract
+ggrd = RegionGrid(geo,lon,lat)
+````
+
+Then we extract the data
+
+````@example extract
+ndata = extractGrid(odata,ggrd)
+````
+
+Let us plot the old and new data
+
+````@example extract
+fig = Figure()
+_,_,slon,slat = coordGeoRegion(geo); slon = slon .+ 360
+aspect = (maximum(slon)-minimum(slon))/(maximum(slat)-minimum(slat))
+
+ax = Axis(
+    fig[1,1],width=350,height=350/aspect,
+    limits=(minimum(slon)-2,maximum(slon)+2,minimum(slat)-2,maximum(slat)+2)
+)
+contourf!(
+    ax,lon,lat,odata,
+    levels=range(-1,1,length=11),extendlow=:auto,extendhigh=:auto
+)
+lines!(ax,clon,clat,color=:black)
+lines!(ax,slon,slat,color=:red,linewidth=5)
+
+ax = Axis(
+    fig[1,2],width=350,height=350/aspect,
+    limits=(minimum(slon)-2,maximum(slon)+2,minimum(slat)-2,maximum(slat)+2)
+)
+contourf!(
+    ax,ggrd.lon,ggrd.lat,ndata,
+    levels=range(-1,1,length=11),extendlow=:auto,extendhigh=:auto
+)
+lines!(ax,clon,clat,color=:black)
+lines!(ax,slon,slat,color=:red,linewidth=5)
+
+hideydecorations!(ax, ticks = false,grid=false)
+
+resize_to_layout!(fig)
+fig
+````
+
+## API
+
+```@docs
+extractGrid
+extractGrid!
+```
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+