# Package objective:

To provide a simple interface for calculating survey areas of nonlinear plots used in environmental monitoring . The same can be achieved using GIS software, but this typically involves manual processing and can be time consuming and/or error prone when processing multiple plots. parcelareadev enables calculations across multiple plots, removing the need to manually process individual plots.

# Package functions:

parcelareadev includes R functions for users.
In brief, these functions use compass bearings and distances recorded during plot installation to process, calculate areas and export results in user friendly formats. Specifically, the functions in parcelareadev:
1) Derive coordinates and calculate the survey area of nonlinear plots
2) Export .pdf files showing plots
3) Export calculated areas as .csv
4) Export plot midlines as shapefiles and .kml

# Package guide:

parcelareadev is available from github https://github.com/darrennorris/parcelareadev. This guide uses data provided in the package. Once installed, load the package:

library(parcelareadev)

Then load data with compass bearings and length of plot sections. The br319 dataset includes values from 5 plots along the BR319 in Brazil. For more details of these surveys see: https://ppbio.inpa.gov.br/sitios/br319/ .
We can look at the structure of the br319 data:

data("br319")
str(br319)
## 'data.frame':    138 obs. of  6 variables:
##  $aid : int 1 2 3 4 5 6 7 8 9 10 ... ##$ plot_id : Factor w/ 119 levels "M01_TN_0500",..: 1 1 1 1 1 1 1 1 1 1 ...
##  $azimute : num 166 152 143 158 163 157 151 159 166 168 ... ##$ segmento: num  10 9.8 9.88 9.98 10 10.2 9.94 9.92 9.86 10 ...
##  $remove : int 0 0 0 0 0 0 0 0 0 0 ... ##$ seg_id  : int  1 2 3 4 5 6 7 8 9 10 ...

br319 has 138 rows and 6 columns:
“aid” : Unique row id, used for data checking.
“plot_id” : ID code unique for each plot.
“azimute” : Compass bearing of section recorded during plot installation. Used for area calculations. Should not be null.
“segmento” : Length in meters of each section. Used for area calculations. Should not be null.
“remove” : Flag. Should segment be removed from analysis. Numeric (1 = yes, 0 = no). Typically indicates sections that cross the main trail.
“seg_id” : Numeric ID for sections. Unique within plot, should be sequential (e.g. 1,2,3 etc) as is used for ordering in area calculations.

To run their own data, users must provide a data.frame following the format of the example data i.e. columns with same names, in same order, with same data type (number, character etc as appropriate). Help to see detals of input data:

?br319

The function area_calc takes the data.frame as input, runs several processes and generates a list with a data.frame, spatial lines and spatial polygons for each plot. As the start locations (geographic coordinates) of the plots are unknown and unnecessary at this stage, the start coordinates of each plot are set to 0 (zero). The list and objects produced are for checking and to obtain calculations, but are not for geographic representation. The task of shifting the plots to geographic coordiantes comes later (function exp_results ) when exporting to shapefiles and .kml files (note to self - fine for points and lines, probably not so clever for polygons…).

# Generate midlines and polygons for specified widths
faixa_dist = c(0.5, 1, 3,12, 10, 20, 21, 22),
faixa_lado = c(0.5, 1, 3,12, 10, 20, 21, 22),
area_epsg = 3395
)

The list (“list_res”) created by the function area_calc holds all the data and objects necessary for calculations and further processing. Users can access the list elements to generate a wide variety of summaries and figures.
To help users, parcelareadev provides functions that automatically generate summaries to meet a variety of needs. The function area_results calculates the survey area of nonlinear plots and exports three representations of the plots in .pdf files. The calculated area values are available in a data.frame (df.resumo) and a copy is also exported to the R working directory as a text file “resumo_parcelas.csv” .

# Calculate area and export results
make_shape = FALSE)

## Output

### .pdfs

To enable checking of calculations, the function area_results exports three representations of the survey plots in .pdf files. The .pdf files are saved in the R working directory.
1. “check_linha_test.pdf” shows the plot midline with sections that should be discarded
2. “check_area_test.pdf” shows the area used in calculations
3. “check_lado_test.pdf” shows the area used in calculations for left and right sides

The file “check_linha_test.pdf” has one page for each plot. An example of the figure produced in the file is shown below. The midline of the plot is shown, along with the sections to be discarded from analysis that cross the main trail (solid black line) or have angle less than or equal to 70 degrees (solid red line).

The second file (“check_area_test.pdf”) again has one page per plot, but this time shows the area used in calculations. There are four seperate figures for each plot. These are for four cases, where the plot may have different length and shape

1. All sections;

2. Discarding sections that cross the main trail;

3. Discarding sections with an angle less than or equal to 70 degrees;

4. Discarding all from “2” and “3”.

An example of the figure produced for each plot is shown below.

The third file “check_lado_test.pdf” shows the area used in calculations seperated for left and right sides of the midline. There are again four seperate figures for each plot, showing the four different cases. Left and right are defined following the direction start (distance 0) to end along the plot.

### .csv

The principal objective of all three .pdf files is to enable the area used in the calculations to be visually checked and validated. The calculated values are available to users in the data.frame df.resumo . A copy of this data.frame is also exported to the working directory in a .csv called “resumo_parcelas.csv”.
More examples of obtaining calculations from this data.frame can be seen here: http://rpubs.com/darren75/parcelareadevEx01Eng .

This data.frame has 8 columns:
“.id” : Plot ID code, unique for each plot.
“variable” : Indicates which segments were used (4 cases).
“lado” : Indicates which side was used for area calculations.
“faixa_id” : ID used in width calculation.
“area_m2” : Calculated area in m2.
“seg_count” : How many sections were used in the area calculation.
“faixa_tipo” : ID for grouping calculation types.
“faixa_dist” : Indicates buffer width used in area calculations.

str(df.resumo)
## 'data.frame':    480 obs. of  8 variables:
##  $.id : chr "M01_TN_0500" "M01_TN_0500" "M01_TN_0500" "M01_TN_0500" ... ##$ variable  : Factor w/ 4 levels "All","Remove_Trilha",..: 1 1 1 1 1 1 1 1 2 2 ...
##  $lado : Factor w/ 3 levels "ambos","left",..: 1 1 1 1 1 1 1 1 1 1 ... ##$ faixa_id  : Factor w/ 16 levels "buf_0.5m","buf_10m",..: 1 2 3 4 5 6 7 8 1 2 ...
##  $area_m2 : num 248 4958 5948 496 9900 ... ##$ seg_count : int  25 25 25 25 25 25 25 25 25 25 ...
##  $faixa_tipo: chr "buf" "buf" "buf" "buf" ... ##$ faixa_dist: chr  "0.5m" "10m" "12m" "1m" ...

### Shapefiles and .kml

To check that the calculations are sensible, users should compare the visual outputs in the .pdf files with the calculated values in df.resumo. Users can also export as shapefiles and/or .kml files to check that the midlines are aligned and located correctly in geographic space.
To locate (shift) the coordinates we need to provide the real world geographic coordinates for the starting point of each plot. Fuction exp_results uses the results list (list_res) and combines output with geographic coordinates provided in a data.frame. An example of the coordinate data.frame is provided with the package dataset br319coords.

data("br319coords")
str(br319coords)
## 'data.frame':    5 obs. of  3 variables:
##  $PLOT_ID: chr "M02_TN_2500" "M01_TN_0500" "M03_TN_1500" "M03_TN_2500" ... ##$ LONG   : num  -60.3 -59.9 -60.7 -60.7 -60.3
##  \$ LAT    : num  -3.68 -3.35 -4.14 -4.14 -3.69

With the coordinate data.frame (br319coords) it is then possible to generate geographically correct midlines. The identification code for plots must be the same as provided for the original input data for area calculations (e.g. br319 and br319coords have identical plot IDs). The function can export the plot midlines in two formats: .shp and .kml. The function exp_results creates new folders in the working directory for the shapefiles and .kml files. The shapefiles and .kml files can then be visualized in googleearth and a wide variety of GIS software.

# Now shift central line to geographic coordinates
# and export as shapefiles and KML for visualization and checking
data("br319coords")
pc <- br319coords
pcoords = pc, exp_KML = TRUE)