Integrating GeoRegions.jl with NASAPrecipitation.jl

addNPDGeoRegions() -> nothing

Checks for the three GeoRegions (GPM, TRMM, TRMMLSM) required by NASAPrecipitation.jl, and adds them if they do not exist.

GeoRegion

Abstract supertype for geographical regions, with the following subtypes:

RectRegion{ST<:AbstractString, FT<:Real} <: GeoRegion
PolyRegion{ST<:AbstractString, FT<:Real} <: GeoRegion

Both RectRegion and PolyRegion types contain the following fields:

• ID - A String Type, the identifier for the GeoRegion
• pID - A String Type, the identifier for the parent GeoRegion
• name - A String Type, the full name of the GeoRegion
• N - A Float Type, the north boundary of the GeoRegion
• S - A Float Type, the south boundary of the GeoRegion
• E - A Float Type, the east boundary of the GeoRegion
• W - A Float Type, the est boundary of the GeoRegion
• is180 - A Bool Type, is W < 0
• is360 - A Bool Type, is E > 180

A PolyRegion type will also contain the following field:

• shape - A vector of Point2 Types, defining a non-rectilinear shape of the GeoRegion

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

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

isinGeoRegion(
    Point  :: Point2{<:Real},
    geo    :: GeoRegion;
    tlon   :: Real = 0,
    tlat   :: Real = 0,
    throw  :: Bool = true
) -> Bool

Check if a geographical point Point is within a GeoRegion defined by geo.

Arguments

• Point : A geographical point of Type Point2. Pass Point2(plon,plat), where plon and plat are the longitude and latitudes of the point.
• geo : The GeoRegion struct container

Keyword Arguments

• tlon : Threshold for the longitude bound
• tlat : Threshold for the latitude bound
• throw : If true, then if Point is not within geo, an error is thrown and the program stops running.

isinGeoRegion(
    Child  :: GeoRegion,
    polyG  :: PolyRegion;
    domask :: Bool = false,
    throw  :: Bool = true
) -> Bool

Check if a child GeoRegion defined by Child is within a PolyRegion polyG.

Arguments

• Child : A GeoRegion that we postulate to be a "child", or a subset of the GeoRegion defined by polyG
• polyG : A GeoRegion that we postulate to be a "parent", or containing the GeoRegion defined by Child

Keyword Arguments

• throw : If true, then if Child is not within polyG, an error is thrown and the program stops running
• domask : If throw is false and domask is true, return a mask (with bounds defined by the Child GeoRegion) showing the region where Child and polyG do not overlap

isinGeoRegion(
    Child  :: GeoRegion,
    rectG  :: RectRegion;
    throw  :: Bool = true
) -> Bool

Check if a child GeoRegion defined by Child is within a RectRegion rectG.

Arguments

• Child : A GeoRegion that we postulate to be a "child", or a subset of the GeoRegion defined by polyG
• polyG : A GeoRegion that we postulate to be a "parent", or containing the GeoRegion defined by Child

Keyword Arguments

• throw : If true, then if Child is not within polyG, an error is thrown and the program stops running

coordGeoRegion(geo::PolyRegion) ->
    blon::Vector{<:Real}, blat::Vector{<:Real},
    slon::Vector{<:Real}, slat::Vector{<:Real},

For a given RectRegion, extract the [N,S,E,W] bounds and create a longitude and latitude vectors for the bound and the shape of the GeoRegion

Arguments

• geo : A PolyRegion (i.e. a polygonal GeoRegion)

Returns

• blon : A vector of longitude points for the bound of the GeoRegion
• blat : A vector of latitude points for the bound of the GeoRegion
• slon : A vector of longitude points for the shape of the GeoRegion
• slat : A vector of latitude points for the shape of the GeoRegion

coordGeoRegion(geo::RectRegion) -> blon::Vector{<:Real}, blat::Vector{<:Real}

For a given RectRegion, extract the [N,S,E,W] bounds and create a longitude and latitude vector.

Arguments

• geo : A RectRegion (i.e. a rectilinear GeoRegion)

Returns

• blon : A vector of longitude points for the bound of the GeoRegion
• blat : A vector of latitude points for the bound of the GeoRegion

RegionGrid

Abstract supertype for geographical region gridded information, with the following subtypes:

RectGrid{FT<:Real} <: RegionGrid
PolyGrid{FT<:Real} <: RegionGrid
RegionMask{FT<:Real} <: RegionGrid

Both RectGrid and PolyGrid types contain the following fields:

• grid - A vector of Ints defining the gridpoint indices of the [N,S,E,W] points respectively
• lon - A vector of Floats defining the latitude vector describing the region
• lat - A vector of Floats defining the latitude vector describing the region
• ilon - A vector of Ints defining indices of the parent longitude vector describing the region
• ilat - A vector of Ints defining indices of the parent latitude vector describing the region

A PolyGrid type will also contain the following field:

• mask - An array of 0s and 1s defining a non-rectilinear shape within a rectilinear grid where data is valid (only available in PolyGrid types)

A RegionMask type will contain the following fields:

• lon - An array of longitude points
• lat - An array of latitude points
• mask - An array of NaNs and 1s defining the region within the original field in which data points are valid

RegionGrid(
    geo :: GeoRegion,
    lon :: Union{Vector{<:Real},AbstractRange{<:Real},
    lat :: Union{Vector{<:Real},AbstractRange{<:Real}
) -> RectGrid, PolyGrid

Creates a RectGrid or PolyGrid type based on the following arguments. This method is suitable for rectilinear grids of longitude/latitude output such as from Isca, or from satellite and reanalysis gridded datasets.

Arguments

• geo : A GeoRegion of interest
• lon : A vector or AbstractRange containing the longitude points
• lat : A vector or AbstractRange containing the latitude points

RegionGrid(
    geo :: GeoRegion,
    lon :: Array{<:Real,2},
    lat :: Array{<:Real,2}
) -> RegionGrid

Creates a RegionMask type based on the following arguments. This method is more suitable for non-rectilinear grids of longitude and latitude points, such as in the output of WRF or CESM.

Arguments

• geo : A GeoRegion of interest
• lon : An array containing the longitude points
• lat : An array containing the latitude points

extractGrid(
    odata :: AbstractArray{<:Real,N},
    ggrd  :: RegionGrid
) where N <: Int -> Array{<:Real,N}

Extracts data from odata, an Array of dimension N (where N ∈ 2,3,4) that contains data of a Parent GeoRegion, into another Array of dimension N, containing only within a sub GeoRegion we are interested in.

Arguments

• odata : An array of dimension N containing gridded data in the region we are interesting in extracting from
• ggrd : A RegionGrid containing detailed information on what to extract