jl.prep: Prepare and bundle input CIRCUITSCAPE model parameters to run...

In wpeterman/ResistanceGA: Optimize resistance surfaces using genetic algorithms

Prepare and bundle input CIRCUITSCAPE model parameters to run in Julia

Description

This function will prepare objects needed for running optimization functions

Usage

jl.prep(n.Pops, 
               response = NULL, 
               CS_Point.File, 
               covariates = NULL,
               formula = NULL,
               JULIA_HOME = NULL,
               Neighbor.Connect = 8, 
               pairs_to_include = NULL, 
               pop2ind = NULL,
               nb = NULL,
               parallel = FALSE, 
               cores = NULL,
               cholmod = TRUE,
               precision = FALSE, 
               run_test = TRUE,
               write.files = NULL,
               write.criteria = NULL,
               silent = TRUE,
               Julia_link = 'JuliaCall',
               scratch = NULL,
               rm.files = TRUE)

Arguments

n.Pops	The number of populations that are being assessed
response	Vector of pairwise genetic distances (lower half of pairwise matrix). Not necessary if only executing Julia run. If optimizing with select points only (see pairs_to_include below), still provide the full vector for the lower half of the square matrix. This will automatically be trimmed down based on the selected pairs to include.
CS_Point.File	Provide a SpatialPoints object containing sample locations. Alternatively, specify the path to the Circuitscape formatted point file. See Circuitscape documentation for help.
covariates	Data frame of additional covariates that you want included in the MLPE model during opitmization.
formula	If covariates are included in the model, specify the R formula for the fixed effects portion of the MLPE model.
JULIA_HOME	Path to the folder containing the Julia binary (See Details)
Neighbor.Connect	Select 4 or 8 to designate the connection scheme to use in CIRCUITSCAPE (Default = 8)
pairs_to_include	Default is NULL. If you wish to use the advanced CIRCUITSCAPE setting mode to include or exclude certain pairs of sample locations, provide a vector consisting of 1 (keep) or 0 (drop) for each pairwise observation (see example). This is an option if you do not want to assess all pairiwse observations in the MLPE model.
pop2ind	Default is NULL. A vector with length equivalent to the number of populations sapled. Each value of the vector indicates the number of samples from each respective population.
nb	Default is NULL. Optionally, specify a distance between points that should be considered as part of the same group or neighborhood. See Details.
parallel	(Logical; Default = FALSE) Do you want to run CIRCUITSCAPE in parallel?
cores	If 'parallel = TRUE', how many cores should be used for parallel processing?
cholmod	(Logical; Default = TRUE). Should the cholmod solver be used? See details.
precision	(Logical; Default = FALSE). Should experimental single precision method be used? See details.
run_test	(Logical; Default = TRUE). Should a test of Julia Circuitscape be conducted? (This can take several seconds to complete)
write.files	(Default = NULL). If a directory is specified, then the .ini and .asc files used in the CS.jl run will be exported.
write.criteria	Criteria for writing .ini and .asc files. If a time in seconds is not specified, then all files will be written if a write.files directory is specified.
silent	(Default = TRUE) No updates or logging of CIRCUITSCAPE will occur. May be useful to set to FALSE to debug.
Julia_link	Specify whether R should connect to Julia using the 'JuliaCall' package (Default), or the 'XRJulia' package
scratch	Scratch directory for use if write access is limited.
rm.files	Should all temporary files be removed after Julia run (Default = TRUE)

Details

This function requires that Julia is properly installed on your system. Upon first running of this function, the Circuitscape.jl library will be downloaded and tested. (see https://github.com/Circuitscape/Circuitscape.jl for more details). This may take some time.

Using cholmod (see https://github.com/Circuitscape/Circuitscape.jl) "The cholesky decomposition is a direct solver method, unlike the algebraic multigrid method used by default in both the old and the new version. The advantage with this new direct method is that it can be much faster than the iterative solution, within a particular problem size. Word of caution: The cholesky decomposition is not practical to use beyond a certain problem size because of phenomenon called fill-in, which results in loss of sparsity and large memory consumption." The cholmod solver can only be used when precision '= FALSE' (double precision).

If precision is TRUE, then the EXPERIMENTAL single precision method will be used. Single precision usually uses less memory, but is likely to reduce accuracy. NOTE: Preliminary testing of single precision mode in a Windows pc resulted in extremely slow runs.

JULIA_HOME is where the Julia binary files are stored. Usually in a 'bin' directory within the Julia install directory.

When specifying a formula, provide it as: response ~ covariate. the formula response will use the vector of values specified for the response parameter. Make sure that covariate names match variable names provided in covariates

If nb is specified, this indicates the maximum distance (in units of your CS_Point.File SpatialPoints object) that locations are considered to be part of the same neighborhood.

Value

An R object that is a required input into optimization functions

Author(s)

Bill Peterman <[e-mail]>

Examples

 
## Not run:
## *** TO BE COMPLETED *** ##

## End (Not run)

wpeterman/ResistanceGA documentation built on Nov. 20, 2023, 11:50 p.m.