Manual

readshape(path::AbstractString, index::Int=-1; 
	extset = [".shp", ".geojson", ".gpkg"]) :: AG.IFeatureLayer

Read a shape file located at path. If path refers to a file, the file is directly read; otherwise, if path refers to a directory, a random shape file inside is read.

extset describes possible extensions of shape files (see also readlayers). By setting extset to nothing, the extension filtering is not processed, i.e., all files are regarded as shape files. extset is indifferent when path refers to a file.

The shape file should contain a dataset. When the dataset consists of multiple layers, index indicates which data layer should be returned.

lookup(shptable::AG.IFeatureLayer, 
	column::Union{AbstractString, Symbol}, entry)
lookup(shptable::AG.IFeatureLayer, 
	column::Union{AbstractString, Symbol}, entries::AbstractArray)
lookup(shptable::AG.IFeatureLayer)

Find row(s) in the shape table whose column record(s) equal(s) to entry or elements of entries. When the third argument is an array, results are output as an array of the same shape by broadcasting.

filterext(dir::AbstractString, extset=nothing) :: Vector{String}

Find all file names in dir with extensions in extset. When extset is set to nothing (by default), all extensions are acceptable.

goodcolumns(shptable::AG.IFeatureLayer) :: Dict{String, Vector}

Find all properties of features in shptable where entries are all unique and either integers or strings (types whose isequal is well-defined).

readlist(path::AbstractString) :: Vector

Read any list of vector from file at path.

writelist(path::AbstractString, list::AbstractVector) :: Nothing

Write any list or vector to file at path.

readlayers(filenames::Vector{<:AbstractString}) :: RasterStack
readlayers(dir::AbstractString; extset=nothing) :: RasterStack

Read all raster layers from the directory dir as a RasterStack.

extset describes possible extensions of raster files (e.g., Set(".tif"), or [".tiff"]; see also readshape). By setting extset to nothing, the extension filtering is not processed, i.e., all files are regarded as raster files.

writelayer(path::AbstractString, layer::Raster) :: Nothing

Write layer to the disk at path. Alias for GeoArrays.write!.

writelayers(paths::AbstractVector{<:AbstractString}, 
	layers::RasterStack) :: Nothing
writelayers(pathformula::AbstractString, layers::RasterStack) :: Nothing

Write layers to paths respondingly, or a series of paths generated by the pathformula where an asterisk is used for wildcard and replaced by numbers.

sortfilenames!(filenames::AbstractVector{<:AbstractString})

Sort filenames in place according to the order of the distinctive parts among them. If all of the distinctive parts are decimal numerals, they are sorted as integers.

Examples

julia> sortfilenames!(["bio_9.tif", "bio_10.tif", "bio_1.tif"])
[ Info: 3 files "bio_*.tif" recognized in the directory, where * = 1, 9, 10.
3-element Array{String,1}:
 "bio_1.tif"
 "bio_9.tif"
 "bio_10.tif"

julia> sortfilenames!(["bio_09.tif", "bio_10.tif", "bio_01.tif"])
[ Info: 3 files "bio_*.tif" recognized in the directory, where * = 01, 09, 10.
3-element Array{String,1}:
 "bio_01.tif"
 "bio_09.tif"
 "bio_10.tif"

allsame(a::AbstractVector) :: Bool

Return true if all elements from a are identical, or otherwise false. An error is thrown if the vector a is empty.

Examples

julia> allsame([1, 1, 2])
false

julia> allsame([1, 1, 1])
true

julia> allsame([1])
true

julia> allsame([])
ERROR: BoundsError: attempt to access 0-element Array{Any,1} at index [1]
Stacktrace:
 [1] getindex at .\array.jl:787 [inlined]
 [2] allsame(::Array{Any,1}) at .\REPL[9]:1
 [3] top-level scope at REPL[20]:1

readfield(path::AbstractString) :: MikrubiField

Read a Mikrubi field from file at path.

writefield(path::AbstractString, field::MikrubiField) :: Nothing

Write a Mikrubi field to file at path.

readmodel(path::AbstractString) :: MikrubiModel

Read a Mikrubi model from file at path.

writemodel(path::AbstractString, model::MikrubiModel) :: Nothing

Write a Mikrubi model to file at path.

rasterize(geoms, layer::Raster) :: CtPixels
rasterize(shptable::AG.IFeatureLayer, layer::Raster) :: CtPixels

For a collection of (multi)polygons, rasterize each of them and write the results in a CtPixels.

CtPixels

CtPixels(indices::Raster{Int})

Collector for county-specific rasterization results, whose list contains county-pixel tuples. Can only be instantiated from an index raster (see indicate).

getpixels(ctpixels::CtPixels) :: Vector{Int}

Get pixel indices from ctpixels.

getcounties(ctpixels::CtPixels) :: Vector{Int}

Get county indices from ctpixels.

getpixel(ctpixels::CtPixels, i::Int) :: Int

Get the pixel index of the i-th county-pixel tuple in ctpixels.

getcounty(ctpixels::CtPixels, i::Int) :: Int

Get the county index of the i-th county-pixel tuple in ctpixels.

indicate(layer::Raster) :: Raster{Int}

Build an index raster indices from layer. The value of an array element in indices is either (1) 0 for missing, if the corresponding element in layer is missing; or (2) the integer index of the array element, otherwise.

register!(ctpixels::CtPixels, ct::Int, pixel::Int) :: Int

Push a county-pixel tuple into ctpixels, if pixel is not zero. For convenience, the value of pixel is returned.

register!(ctpixels::CtPixels, ct::Int) :: Function

Create a function that accepts a pixel, pushes the county-pixel tuple into ctpixels, and finally returns the value of pixel.

ispoly(geom) :: Bool

Check if geom is a polygon or a multipolygon.

makefield(layers::RasterStack, shptable; 
	config=DimLowerConfig(rabsthres=0.8, nprincomp=3))
		:: Tuple{MikrubiField, RasterStack}

Create a MikrubiField as well as processed variable layers from layers and shptable, by

1. masking the layers with ctpixels (using Mikrubi.masklayers!),
2. extracting non-missing pixels from layers (using Mikrubi.extractlayers),
3. selecting less correlated variables (using Mikrubi.selectvars), and
4. doing the principal component analysis (using Mikrubi.princompvars).

Configuration including rabsthres and nprincomp can be passed in as a keyword argument; see DimLowerConfig.

A less detailed version of yieldfield.

yieldfield(layers::RasterStack, ctpixels::CtPixels, 
	dimlowerorconfig=DimLowerConfig(rabsthres=0.8, nprincomp=3)) :: 
		Tuple{MikrubiField, RasterStack, DimLower}
yieldfield(layers::RasterStack, shptable, 
	dimlowerorconfig=DimLowerConfig(rabsthres=0.8, nprincomp=3)) :: 
		Tuple{MikrubiField, RasterStack, DimLower}

Return a MikrubiField, processed variable layers, and the DimLower.

A more detailed version of makefield.

DimLowerConfig

DimLowerConfig(; rabsthres=0.8, nprincomp=3)

A type for configuration for dimensionality reduction.

Keyword arguments

• rabsthres: threshold of collinearity.

Absolute value of Pearson correlation efficient greater than this threshold is identified as collinearity and the two variables are thus incompatible.

• nprincomp: expected number of principal components of the variables.

colmatrix(vector::AbstractVector) :: AbstractMatrix
colmatrix(matrix::AbstractMatrix) :: AbstractMatrix

Return a one-column matrix if the argument is a vector, or the matrix itself if the argument is already a matrix.

masklayers!(layers::RasterStack, ctpixels::CtPixels) :: RasterStack

Mask the layers in a way that only pixels present in ctpixels are kept, while all other uncovered pixels are set to a missing value.

extractlayers(layers::RasterStack) :: Tuple{Matrix, Vector{Int}}

Extract the non-missing pixels from layers, and combine them into a matrix, whose rows representing pixels and columns representing variables.

extractlayers is the inverse function of makelayers.

emptylayer!(grid::Raster) :: Raster

Fill the grid with missing values in place.

emptylayer(grid::Raster) :: Raster

Create a new Raster full of missing values from the shape of grid.

emptylayers(grid::Raster, m::Int) :: RasterStack

Create a RasterStack with m empty Rasters (full of missing values) from the shape of grid.

makelayer(vector::AbstractVector, idx::AbstractVector, grid::Raster) 
	:: Raster

Make a Raster from the grid and values in vector.

For making a RasterStack from a matrix, see makelayers.

makelayers(matrix::AbstractMatrix, idx::AbstractVector, grid::Raster) 
	:: RasterStack

Make a RasterStack from the grid and values in columns of matrix.

For making a Raster from a column vector, see makelayer.

makelayers is the inverse function of extractlayers.

dftraverse!(beststate, bestscore, state, score, depth, maxdepth, 
	incompat, scoremat) :: Nothing

Find the index combination that

• firstly containing as many indices as possible, and
• secondly with the lowest pairwise sum from submatrix of scoremat,

such that no indices i and j coexist as long as incompat[i][j] == true.

The result is stored as the only element of beststate, with its score decided by the two criteria above stored as the only element of bestscore.

Example

julia> beststate = Vector(undef, 1);

julia> bestscore = [(0, 0.0)];

julia> dftraverse!(beststate, bestscore, Int[], (0, 0.0), 1, 3,
           Bool[0 0 1; 0 0 0; 1 0 0],
           [0.0 0.6 0.3; 0.6 0.0 0.9; 0.3 0.9 0.0]);

julia> beststate
1-element Array{Any,1}:
 [1, 2]

julia> bestscore
1-element Array{Tuple{Int64,Float64},1}:
 (2, -0.6)

selectvars(matrix::Matrix, rabsthres=0.8) :: Vector{Int}

Select as many variables as possible from matrix such that no pairwise Pearson coefficient among them exceeds rabsthres and their sum is minimal.

Example

julia> selectvars([1. 4. 7.; 2. 5. 8.; 3. 9. 27.], rabsthres=0.9)
2-element Array{Int64,1}:
 1
 3

princompvars(smatrix::Matrix; nprincomp=3) :: Tuple{Vector, Matrix}

Perform principal component analysis on smatrix whose columns represents variables, and combines the nprincomp principal components into a matrix, and returns the result matrix as well as the affine transformation (colmean, projwstd), such that the result matrix == (smatrix .- colmean) * projwstd.

DimLower

DimLower{T<:AbstractFloat}(n::Int, colid::Vector{Int}, 
	colmean::Matrix{T}, projwstd::Matrix{T})
DimLower(n::Integer, colid::AbstractVector{<:Integer}, 
	colmean::AbstractMatrix{<:Real}, projwstd::AbstractMatrix{<:Real})

A container for transformation parameters used in makefield.

dimpoints(grid::Raster) :: DimPoints

Create a DimensionalData.DimPoints from grid after shifting all its dimension loci to Center(). Similar to GeoArrays.coords.

centercoords(dp::DimPoints, ci::CartesianIndices, idx::Int) 
	:: Tuple{AbstractFloat, AbstractFloat}

Get center coordinates of a grid cell indexed by idx in a Raster.

buildfield(ctpixels::CtPixels, idx::Vector, 
	projmat::Matrix, grid::Raster) :: MikrubiField

Construct a MikrubiField from ctpixels, idx, projmat, and grid. Used in makefield.

MikrubiField{T, U <: Real, V <: AbstractFloat}

MikrubiField(ctids, locs, vars)

Construct a Mikrubi field containing a number of pixels or points, using the arguments which should always have the same number of rows

• ctids::Vector: a vector containing the county identifiers
• locs::Array{<:Real}: an array of geographic coordinates
• vars::Matrix{<:AbstractFloat}: an array of environmental coordinates

MikrubiModel{V <: AbstractFloat}

MikrubiModel(dvar::Int, params::Vector{<:AbstractFloat})

Construct a Mikrubi Model from a dimensionality dvar and a parameter vector params. The equation must hold for dvar2dparam(dvar) == length(params).

Mikrubi Models can be obtained from the function fit, and can be used in the function predict.

fit(field::MikrubiField, counties, coords=zeros(0, 0); 
	optresult=[], iterations=3_000_000, kwargs...) :: MikrubiModel

Numerically find the Mikrubi model maximizing the likelihood that the occupied counties as well as the occupied coordinates are sampled in the given Mikrubi field. The optimization result is stored in the container optresult for debugging.

predict(matrix::AbstractMatrix, model::MikrubiModel) :: Vector
predict(layers::RasterStack, model::MikrubiModel) :: Raster
predict(field::MikrubiField, model::MikrubiModel) 
	:: Dict{<:Any, <:Vector{<:Tuple{Vector{<:Real}, AbstractFloat}}}

Predict the probability of presence according to processed climatic factors (matrix / layers) or on the Mikrubi field.

predictcounty(field::MikrubiField, model::MikrubiModel, county) 
	:: Vector{<:Tuple{Vector{<:Real}, AbstractFloat}}

Return the geographic coordinates of pixels in the county sorted by the likeliness of being occupied.

probcounties(field::MikrubiField, model::MikrubiModel) 
	:: Dict{<:Any, <:AbstractFloat}
probcounties(::Type{<:Logistic}, field::MikrubiField, model::MikrubiModel) 
	:: Dict{<:Any, <:Logistic}

Compute the probability for every county to be occupied in the field.

samplecounties(field::MikrubiField, model::MikrubiModel) :: Vector

Sample counties according to their probability of being occupied.

lipschitz(model::MikrubiModel, field::MikrubiField; wholespace=false) 
	:: AbstractFloat

Calculate the maximum gradient (in norm) of the probability of presence over the field. When wholespace=false (default), the maximum is taken among the points contained in field; otherwise it is taken around the whole space.

dvar2dparam(dvar::Int) :: Int

Convert dimensionality of an environmental space to the dimensionality of the induced parameter space, i.e., compute the degrees of freedom for positive-definite quadratic functions mapping a dvar-dimensional linear space into real numbers.

Examples

julia> dvar2dparam(1)
3

julia> dvar2dparam(3)
10

decomparams(p::AbstractVector, d::Int) :: Tuple{Matrix, Vector, Any}
decomparams(model::MikrubiModel) :: Tuple{Matrix, Vector, Any}

Return parameter decomposition At, b, c, where

• At is a lower triangular matrix of size (d, d),
• b is a column vector of size d, and
• c is a scalar.

WARNING: The vector p must have length dvar2dparam(d).

Example

julia> decomparams(collect(1:10), 3)
([1 0 0; 2 3 0; 4 5 6], [7, 8, 9], 10)

pabsence(vars::AbstractMatrix, params::AbstractVector) :: Logistic
pabsence(field::MikrubiField, params::AbstractVector) :: Logistic

Compute the probability of absence at pixels given vars/field and params.

ppresence(vars::AbstractMatrix, params::AbstractVector) :: Logistic
ppresence(field::MikrubiField, params::AbstractVector) :: Logistic

Compute the probability of presence at pixels given vars/field and params.

mlogL(field::MikrubiField, counties, params::AbstractVector)
	:: AbstractFloat
mlogL(vars::AbstractMatrix, params::AbstractVector) :: AbstractFloat

Compute the opposite log-likelihood that the occupied counties or occupied coordinates are sampled. The opposite is taken for optimization.

probpixels(field::MikrubiField, model::MikrubiModel) 
	:: Vector{<:AbstractFloat}

Compute the probability for every pixel to be occupied in the field.

findnearest(loc::AbstractVecOrMat{<:Real}, field::MikrubiField) :: Int

Return the row index in field.locs which is the nearest to the given coordinates.

findnearests(loc::AbstractVector{<:AbstractVecOrMat}, field::MikrubiField) 
	:: Vector{Int}
findnearests(loc::AbstractMatrix{<:Real}, field::MikrubiField) 
	:: Vector{Int}

Return the row indices in field.locs which are the nearest to each of the given coordinates. Duplicate results are reduced to one.

loglipschitz(model::MikrubiModel, field::MikrubiField; wholespace=false) 
	:: AbstractFloat

Calculate the (logarithmic) maximum gradient (in norm) of the probability of presence over the field. When wholespace=false (default), the maximum is taken among the points contained in field; otherwise it is taken around the whole space.

textwrap(str::AbstractString) :: String

Gobble all linefeeds ("\n") inside str and replaces them with spaces (""), so long strings can be wrapped to multiple lines in the codes, like the Python package "textwrap". See also tw.

@tw_str :: String

Macro version of textwrap, without interpolation and unescaping.