Help for package proxirr

Type:

Package

Title:

Alpha and Beta Proximity to Irreplaceability

Date:

2024-01-25

Version:

0.4

Description:

Functions to measure Alpha and Beta Proximity to Irreplaceability. The methods for Alpha and Beta irreplaceability were first described in: Baisero D., Schuster R. & Plumptre A.J. Redefining and Mapping Global Irreplaceability. Conservation Biology 2021;1-11. <doi:10.1111/cobi.13806>.

License:

MIT + file LICENSE

Encoding:

UTF-8

Suggests:

testthat (≥ 3.0.0), utils

RoxygenNote:

7.3.1

Config/testthat/edition:

NeedsCompilation:

Packaged:

2024-01-26 15:35:05 UTC; redlist

Author:

Daniele Baisero

[aut, cre, cph]

Maintainer:

Daniele Baisero <daniele.baisero@gmail.com>

Repository:

CRAN

Date/Publication:

2024-01-26 15:50:02 UTC

Calculate Alpha Irreplaceability

Description

This function calculates Alpha Irreplaceability for a single feature.

Usage

.alpha(local, global, target, triage = FALSE, na.allow = FALSE)

Arguments

local

numeric - The feature's local representation at the site.

global

numeric - The feature's globally available representation.

target

numeric - The feature's target.

triage

logical - Should features with unachievable targets be ignored? Defaults to FALSE. If FALSE, these species will be always assigned an Alpha irreplaceability of 1 wherever they occur. If TRUE, these species will always be assigned an Alpha irreplaceabiltiy of 0.

na.allow

logical - Return NA if NA values are found in the inputs?

Details

If na.allow is TRUE and any of the required values is NA, returns NA.

If triage is set to TRUE, alpha irreplaceability is set to 0 if the target cannot be achieved (i.e., if the target is greater than the global value), and calculated normally otherwise.

Value

A number between 0 and 1.

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

References

doi:10.1111/cobi.13806

Examples

.alpha(local=0,    global=100,  target=50)
.alpha(local=15,   global=100,  target=50)
.alpha(local=35,   global=100,  target=50)
.alpha(local=49.5, global=100,  target=50)
.alpha(local=55,   global=100,  target=50)
.alpha(local=100,  global=100,  target=0)
.alpha(local=5,    global=100,  target=110)
.alpha(local=5,    global=100,  target=110, triage=TRUE)
.alpha(local=32,   global=100,  target=NA, na.allow = TRUE)

Calculate Beta Irreplaceability

Description

This function calculates Beta Irreplaceability from a vector of Alpha Irreplaceability values. Alpha Irreplaceability values can be calculated using .alpha().

Usage

.beta(alphas, na.rm = FALSE)

Arguments

alphas

vector - A vector of numbers between 0-1.

na.rm

logical - Should missing values (NA) be removed?

Value

A number between 0 and 1.

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

References

doi:10.1111/cobi.13806

Examples

.beta(alphas=c(0.1,0.32,0.5))
.beta(alphas=c(0.1,0.32,0.9))
.beta(alphas=c(0.1,0.32,1))
.beta(alphas=c(0.1,0.32,NA), na.rm=TRUE)

Marxan feature alpha irreplaceability parameters

Description

Returns a feature's target and global representation

Usage

.marxan_alpha_parameters(spec, puvspr, spid)

Arguments

spec

data.frame - The spec.dat as a data.frame.

puvspr

data.frame - The puvspr.dat as a data.frame.

spid

integer - The species ID.

Value

A list

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

## Not run: 
.marxan_alpha_parameters(spec_dataframe, puvsp_dataframe, 17)

## End(Not run)

Marxan data reader

Description

Reads a marxan spec.dat or puvsp.dat file.

Usage

.marxan_data_reader(input, datafile)

Arguments

input

string - The address of a Marxan input.dat file.

datafile

string - The file to read. either 'spec' or 'puvspr'.

Value

A data.frame

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

## Not run: 
.marxan_data_reader('/data/marxan/analysis01/input.dat', 'spec')
.marxan_data_reader('/data/marxan/analysis01/input.dat', 'puvspr')
.marxan_data_reader('/data/marxan/analysis01/input.dat', 'pu')

## End(Not run)

Marxan input.dat parameter reader

Description

Reads a marxan input.dat file and returns a single parameter.

Usage

.marxan_input_parameter(input, parameter)

Arguments

input

string - The address of a Marxan input.dat file.

parameter

string - The name of the parameter to read.

Value

A string.

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

## Not run: 
.marxan_read_input('/data/marxan/analysis01/input.dat', 'INPUTDIR')

## End(Not run)

Calculate Alpha Irreplaceability

Description

This function calculates Alpha irreplaceability. Inputs can be single parameter values needed to calculate Alpha, vectors of parameter values to calculate a vector of Alpha values, or a data.frame with columns containing parameters needed to calculate a vector of Alpha values.

Single Alpha measurement: If local, global and target are numeric, it calculates and returns Alpha irreplaceability.
Vectorized Alpha measurement: If local, global and target are vectors of the same length, a vector of Alpha irreplaceability values will be calculated and returned.
Dataframe Alpha measurement: If df is provided and local, global and target are strings representing field names in df, a vector of Alpha irreplaceability values will be caluclated and returned. Optionally: If alpha_col is also provided, a data.frame identical to df will be returned with the calculated Alpha values in the alpha_col column.

Usage

alpha(
  local,
  global,
  target,
  df = NULL,
  alpha_col = NULL,
  triage = FALSE,
  na.allow = NULL,
  overwrite = FALSE
)

Arguments

local

number, vector or string - The feature's representation at the site, or the name of the column containing the feature's representation at the site.

global

number, vector or string - The feature's globally available representation, or the name of the column containing the feature's globally available representation.

target

number, vector or string - The feature's target, or the name of the column containing the feature's target.

df

data.frame - Optional; an input data.frame.

alpha_col

string - The name of the column where to write alpha values. If both df and alpha_col are provided, the output will be the input dataframe with the additional column.

triage

logical - Should features with unachievable targets be ignored? Defaults to FALSE. If FALSE, these species will be always assigned an Alpha irreplaceability of 1 wherever they occur. If TRUE, these species will always be assigned an Alpha irreplaceabiltiy of 0.

na.allow

logical - Allaw NA values in input? If TRUE, NA values in local, global or target walues will result in NA being returned, otherwise an error will be raised. Defaults to FALSE for single Alpha calculations, and to TRUE for calculations over vectors or data.frames.

overwrite

logical - Should alpha_col be overwritten if it already exists?

Value

A number, vector or data.frame

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

alpha(1, 100, 45)
alpha(c(1,25,45), c(100,100,100), c(50,50,50))
dtfrm = data.frame(
  loc = c(1,25,45),
  glob = c(100,100,100),
  targ = c(50,50,50)
)
alpha('loc', 'glob', 'targ', df = dtfrm)

Calculate Beta Irreplaceability

Description

This function calculates Beta irreplaceability. Inputs can be either a vector of Alpha values, or a data.frame containing all necessary parameters needed to calculate Alpha values on a row-by-row basis.

Vector Beta measurement: If data is a vector of Alpha irreplaceability values, a single Beta value will be calculated and returned.
Dataframe Beta measurement: If data is a data.frame and local, global and target are strings representing field names in data, a vector of Alpha irreplaceability values will be caluclated using these fields, and a Beta irreplaceability value will be calculated on these, and returned.

Usage

beta(
  data,
  local = NULL,
  global = NULL,
  target = NULL,
  triage = FALSE,
  na.rm = TRUE
)

Arguments

data

vector or data.frame - The input over which to calculate Beta.

local

string - The name of the column containing the feature's representation at the site. Needed if data is a data.frame

global

string - The name of the column containing the feature's total available representation. Needed if data is a data.frame

target

string - The name of the column containing the feature's target. Needed if data is a data.frame

triage

na.rm

logical - Should lines with missing values (NA) be ignored? If data is a vector, NA values will be removed when calculating Beta. If data is a data.frame, Alpha values will be calculated using alpha with na.allow set to TRUE, and then Beta calculated ignoring NA values.

Value

A number

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

beta(c(0.01, 0.5, 0.5))
dtfrm = data.frame(
  loc = c(1,25,45),
  glob = c(100,100,100),
  targ = c(50,50,50)
)
beta(dtfrm, local = 'loc', global = 'glob', target = 'targ')

Marxan: Alpha irreplaceabilities

Description

Given a valid Marxan input.dat file, it returns a copy of the PUVSPRNAME file (puvspr.dat), with additional columns containing the feature's global value, target value, and alpha irreplaceability.

Usage

marxan_alphas(input, triage = FALSE)

Arguments

input

string - The address of the input.dat file.

triage

logical - Should features with unachievable targets be given an irreplaceability of 0? See alpha.

Details

The global value is obtained as the sum of the feature's "amount" column in PUVSPRNAME.

The target value is obtained from the SPECNAME file (spec.dat), either as the proportion of the global value (if the "prop" column is present in SPECNAME), or as the "target" value in SPECNAME (otherwise). This behaviour mirrors Marxan's default behaviour.

Value

A data.frame

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

## Not run: 
marxan_alphas('/data/marxan/analysis01/input.dat')
marxan_alphas('C:\data\marxan\analysis01\input.dat')

## End(Not run)

Marxan: Beta irreplaceabilities

Description

Given a valid Marxan input.dat file, returns a copy of the PUNAME file (pu.dat), with an additional column containing the planning unit's beta irreplaceability.

Usage

marxan_betas(input, triage = FALSE)

Arguments

input

string - The address of the input.dat file.

triage

logical - Should features with unachievable targets be given an irreplaceability of 0? See beta.

Value

A data.frame

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

## Not run: 
marxan_betas('/data/marxan/analysis01/input.dat')
marxan_betas('C:\data\marxan\analysis01\input.dat')

## End(Not run)

Marxan: Save Alpha and Beta Irreplaceabilities

Description

Saves the outputs of marxan_alphas and marxan_betas in the marxan output folder.

Usage

marxan_run(input, alphas = TRUE, betas = TRUE, triage = FALSE)

Arguments

input

string - The address of the input.dat file.

alphas

logical - Should the Alpha Irreplaceability output be saved?

betas

logical - Should the Beta Irreplaceability output be saved?

triage

logical - Should features with unachievable targets be given an irreplaceability of 0? See alpha and beta.

Details

Two files ('_proxirr_alphas.csv', '_proxirr_betas.csv') will be created prefixed with the scenario name indicated in 'input.dat' ('SCENNAME').

Value

TRUE

Author(s)

Daniele Baisero, daniele.baisero@gmail.com

Examples

## Not run: 
marxan_run('/data/marxan/analysis01/input.dat')
marxan_run('C:\data\marxan\analysis01\input.dat')

## End(Not run)