frescalo | R Documentation |
A function for using Frescalo (Hill, 2011), a tool for analysing occurrence data when
recording effort is not known. This function returns the output from Frescalo to the
R session and saves it to the path specified by sinkdir
. By setting
plot_fres
to TRUE
maps of the results will also be saved. Plotting the
returned object gives a useful summary.
frescalo(
Data,
frespath,
time_periods,
site_col,
sp_col,
year_col = NULL,
start_col = NULL,
end_col = NULL,
species_to_include = NULL,
sinkdir = NULL,
plot_fres = FALSE,
Fres_weights = "LCGB",
non_benchmark_sp = NULL,
fres_site_filter = NULL,
phi = 0.74,
alpha = 0.27,
trend_option = "arithmetic",
NYears = 10,
ignore.ireland = F,
ignore.channelislands = F
)
Data |
A dataframe object. This should consist of rows of observations and columns indicating the species and location as well as either the year of the observation or columns specifying the start and end dates of the observation. It is important that date columns are in a date format. |
frespath |
the path to the frescalo .exe file. This can be downloaded from http://www.brc.ac.uk/biblio/frescalo-computer-program-analyse-your-biological-records. It is currently only available for Windows. The directory where the .exe is saved should be writeable. |
time_periods |
A dataframe object with two columns. The first column contains the start year of each time period and the second column contains the end year of each time period. Time periods should not overlap. |
site_col |
The name of the site column in |
sp_col |
The name of the species column in |
year_col |
The name of the year column in |
start_col |
The name of the start date column in |
end_col |
The name of the end date column in |
species_to_include |
Optionally a character vector listing the names of species to be used. Species not in your list are ignored. This is useful if you are only interested in a subset of species. |
sinkdir |
String giving the output directory for results |
plot_fres |
Logical, if |
Fres_weights |
'LC*' specifies a weights files based on landcover data. The suffix specifies the extend ('LCUK', 'LCNI' or 'LCGB'). 'VP' uses a weights file based on vascular plant data for the UK , both are included in the package. Alternativly a custom weights file can be given as a data.frame. This must have three columns: target cell, neighbour cell, weight. Default is 'LCGB' |
non_benchmark_sp |
a character vector, giving the names of species not to be
used as benchmarks in Frescalo. Default is |
fres_site_filter |
Optionally a character vector giving
the names of sites to be used in the trend analysis. Sites not include in this
list are not used for estimating TFactors. Default is |
phi |
Target frequency of frequency-weighted mean frequency. Default is 0.74 as in
Hill (2011). If set to |
alpha |
the proportion of the expected number of species in a cell to be treated as benchmarks. Default is 0.27 as in Hill (2011). This is limited to 0.08 to 0.50. |
trend_option |
Set the method by which you wish to calculate percentage change. This can currently
be set to either |
NYears |
The number of years over which you want the percentage change to be calculated (i.e. 10 gives a decadal change). Default = 10 |
ignore.ireland |
Logical, if |
ignore.channelislands |
Logical, if |
Results are saved to file and most are returned in a list to R.
The list object returned is comprised of the following:
\bold{$paths} |
This list of file paths provides the locations of the raw data files for $log, $stat, $freq and $trend, in that order |
\bold{$trend} |
This dataframe provides the list of time factors for each species |
- | Species | Name of species |
- | Time | Time period, specified as a class (e.g. 1970); times need not be numeric and are indexed as character strings |
- | TFactor | Time factor, the estimated relative frequency of species at the time |
- | St_Dev | Standard deviation of the time factor, given that spt (defined below) is a weighted sum of binomial variates |
- | X | Number of occurrences of species at the time period |
- | Xspt | Number of occurrences, given reduced weight of locations having very low sampling effort |
- | Xest | Estimated number of occurrences; this should be equal to spt if the algorithm has converged |
- | N>0.00 | Number of locations with non-zero probability of the species occurring |
- | N>0.98 | Number of locations for which the probability of occurrence was estimated as greater than 0.98 |
\bold{$stat} |
Location report |
- | Location | Name of location; in this case locations are hectads of the GB National Grid |
- | Loc_no | Numbering (added) of locations in alphanumeric order |
- | No_spp | Number of species at that location; the actual number which may be zero |
- | Phi_in | Initial value of phi, the frequency-weighted mean frequency |
- | Alpha | Sampling effort multiplier (to achieve standard value of phi) |
- | Wgt_n2 | effective number N2 for the neighbourhood weights; this is small if there are few floristically similar hectads close to the target hectad. It is (sum weights)^2 / (sum weights^2) |
- | Phi_out | Value of phi after rescaling; constant, if the algorithm has converged |
- | Spnum_in | Sum of neighbourhood frequencies before rescaling |
- | Spnum_out | Estimated species richness, i.e. sum of neighbourhood frequencies after rescaling |
- | Iter | Number of iterations for algorithm to converge |
\bold{$freq} |
Listing of rescaled species frequencies |
- | Location | Name of location |
- | Species | Name of species |
- | Pres | Record of species in location (1 = recorded, 0 = not recorded) |
- | Freq | Frequency of species in neighbourhood of location |
- | Freq_1 | Estimated probabilty of occurrence, i.e. frequency of species after rescaling |
- | SD_Frq1 | Standard error of Freq_1, calculated on the assumption that Freq is a binomial variate with standard error sqrt(Freq*(1-Freq)/ Wgt_n2), where Wgt_n2 is as defined for samples.txt in section (b) |
- | Rank | Rank of frequency in neighbourhood of location |
- | Rank_1 | Rescaled rank, defined as Rank/Estimated species richness |
\bold{$log} |
This records all the output sent to the console when running frescalo |
\bold{$lm_stats} |
The results of linear modelling of TFactors |
- | SPECIES | Name of species used internally by frescalo |
- | NAME | Name of species as appears in raw data |
- | b | The slope of the model |
- | a | The intercept |
- | b_std_err | Standard error of the slope |
- | b_tval | t-value for a test of significance of the slope |
- | b_pval | p-value for a test of significance of the slope |
- | a_std_err | Standard error of the intercept |
- | a_tval | t-value for a test of significance of the intercept |
- | a_pval | p-value for a test of significance of the intercept |
- | adj_r2 | Rescaled rank, defined as Rank/Estimated species richness |
- | r2 | t-value for a test of significance of the intercept |
- | F_val | F-value of the model |
- | F_num_df | Degrees of freedom of the model |
- | F_den_df | Denominator degrees of freedom from the F-statistic |
- | Ymin | The earliest year in the dataset |
- | Ymax | The latest year in the dataset |
- | change_... | The percentage change dependent on the values given to trend_option and NYears . |
The following columns are only produced when there are only two time periods
- | Z_VAL | Z-value for the significance test of the trend |
- | SIG_95 | A logical statement indicating if the trend is significant (TRUE) or non-significant (FALSE) |
Hill, Mark. Local frequency as a key to interpreting species occurrence data when recording effort is not known. 2011. Methods in Ecology and Evolution, 3 (1), 195-205.
## Not run:
# Load data
data(unicorns)
fres_out <- frescalo(Data = unicorns,
frespath = file.path(getwd(), "frescalo.exe"),
time_periods = data.frame(start=c(1980,1990),end=c(1989,1999)),
site_col = 'site',
sp_col = 'species',
start_col = 'start_date',
end_col = 'end_date')
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.