
#####title: Calculate % C4 cover at TERN plots
#####author: Dr Samantha Munroe, TERN, University of Adeliade 


#This code presents an example of how to calculate % C4 and C3 plant cover at TERN plots by combining % species cover determined using the TERN R package *ausplotsR*,
#and *The photosynthetic pathways of plant species surveyed in TERN Ecosystem Surveillance plots* data set described by 
#'The photosynthetic pathways of plant species surveyed in Australia's national terrestrial monitoring network'
#'
#'This code also provides an example of how to extract site-specific environmental data for TERN plot locations from rasters that can be regressed against total C4 and C3 cover

###############################
###########What is TERN?#######
###############################

#The Terrestrial Ecosystem Research Network (TERN) is Australia's national land ecosystem monitoring program.
#TERN measures a range of critical environmental attributes from local to continental scale and generates quality data for research and land management. 
#Since 2011, TERN has performed standardized field surveys and sampling across a national plot network. 
#At each plot, TERN collects data on vegetation structure, composition and diversity, soil characteristics, as well as plant and soil samples for analysis.
#TERN plots are surveyed using the 'AusPlots' Rangelands method, which is composed of modules designed to collect soil and vegetation data (Sparrow et al. 2020).
#Vegetation cover is calculated using a point-intercept method


#*ausplotsR* is an R package for the R statistical computing environment that provides a user-friendly interface to rapidly import, visualize, and analyze TERN plot survey data. 
#*Functions extract the data and compile data tables that can be incorporated into a variety of statistical analysis.


######################################
##What is covered in the tutorial?####
######################################
#In this tutorial, you will learn:
 #- how to extract TERN plot vegetation point-intercept data
 #- calculate species cover at each TERN plot
 #- combine species cover data with TERN photosynthetic pathway data set
 #- calculate total C4 and C3 cover at each TERN plot 
 #- extract site-specific environmental data for TERN plot locations from rasters that can be regressed against total C4 and C3 cover

#Before beginning this tutorial, we encourage users to familiarize themselves with the *ausplotsR* package manual. 
#There is also a short report describing the package here (add link once in pre-print)

###################################################
##########How to calculate % C4 cover at TERN plots
###################################################


#Begin by loading the necessary packages:
  

#load packages 
library(ausplotsR)
library(reshape2)
library(plyr)
library(tidyverse)
library(data.table)
library(raster)
library(sp)


##Next, use the function 'get_ausplots' to extract TERN plot data. 
#ausplotsR sources its data via a dedicated server stack that is running inside a Virtual Machine in the Australian Research Data Common's (ARDC's) NECTAR research cloud. 
#By default, get_ausplots extracts a list of data tables for the point-intercept (veg.PI) and vegetation voucher (veg.vouchers) modules. 
#Because the TERN plot database is very large, this process may take a several minutes.


#extract TERN ausplots data
ausplots_data<-get_ausplots()

#inspect structure
str(ausplots_data)

#ausplots_data is a list of data tables, the description for each can be found in the ausplotsR manual. 
#The data table $veg.PI is a data frame with individual point-intercept data. 
#This data table can be used in the downstream ausplotsR function 'species_table', which will calculate species cover. 
#In this case, we will calculate % species cover, although other options include presence/absence and frequency. 

#In this example, we will also specify the species name designation we want to use to calculate species cover. 
#Users can select the preferred species name option from herbarium_determination, standardised_name (the default), or genus_species. 
#If species_name="HD", the function will use the "herbarium_determination" provided by state herbaria to identify unique species. 
#"herbarium_determination" are made to the lowest possible taxonomic rank, which may be the family, genus, species, subspecies or variety. 
#If species_name="SN", the default, the function will use the the "standardised_name" to identify unique species. 
#Values are based on the veg.PI$herbarium_determination but have been edited to match the most commonly used or widely accepted scientific name. 
#If species_name="GS", only the standardised genus species rank ("genus_species" in the veg.PI input table) is used to identify species. 
#For this example, we will use species_name="GS" because the photosynthetic pathway dataset lists species at the  the standardised genus species rank. 


species_cover<-species_table(ausplots_data$veg.PI, m_kind="percent_cover", species_name="GS")


#The result is a matrix with species as columns and plots as rows. 
#Plots are distinguished by their "site_unique", an alphanumeric code that identifies each unique plot (location) and survey (visit). 

#Next, to combine the species cover data with the photosynthetic pathway data, we need to reshape the species_cover matrix to be grouped by "site_unique". 
#This requires converting the matrix to a data frame and melting the data frame by site_unique.
#We can also assign some clear column names to make things easier to follow going forward.


#modify species cover matrix and convert to data frame
names(species_cover)<-gsub('[.]', '_', names(species_cover))#first convert all periods to _
species_data_frame<-setDT(species_cover, keep.rownames = TRUE) #convert to a data frame
names(species_data_frame)[1]<-paste("site_unique") #change column name
species_cover_list <- reshape::melt(species_data_frame, id=(c("site_unique"))) #reshape data frame 
names(species_cover_list)[2]<-paste("Species.name") #change column name
names(species_cover_list)[3]<-paste("species_cover_value") #change column name


#This generates a new data frame which lists each plot visit (site_unique), each species (Species.name), and % species cover for each species at each plot (species_cover_value)


#Now, we bring in the photosynthetic pathway dataset, which lists all species in the TERN database, and its photosynthetic pathway.
#This can be downloaded from the TERN Geospatial Catalogue and imported into R (https://portal.tern.org.au/photosynthetic-pathways-plant-surveillance-plots/21821).   

#import photosynthetic pathway data set
#setwd() #set your working directory 
Pathway_data <- read.csv("Photosynthetic pathways of plant species in TERN plots.csv") 


#Now it is a simple matter of merging the two data sets based on the species name 


#merge data tables
Pathway_assignment <- merge(species_cover_list, Pathway_data, by='Species.name')


#This new data frame has now matched each species in the TERN data base with its photosynthetic pathway, and % cover at each TERN plot and survey.

#Now we can use this new Pathway_assignment data frame to perform various analysis. 
#In this example, we will calculate the % cover of C3 and C4 species at each TERN plot.

#In the photosynthetic pathway dataset, there are three columns that define the photosynthetic pathway of plants

#- Photosynthetic.pathway (confirmed using data from literature or TERN stable isotope analysis)
#- Photosynthetic.pathway (inferred from lineage)
#- Photosynthetic pathway (combined)

#This final column combines information from the previous two columns to create the most complete list of photosynthetic pathways.
#Therefore, we will use this column to calculate C3 and C4 cover. 

#First, we will subset all the species assigned as C3 and C4, excluding CAM or CAM-facultative species.
#Then, we can use a simple summarize function to calculate the C3 and C4 cover for each plot


C3_C4 <- subset(Pathway_assignment, Pathway_assignment$Photosynthetic.pathway..combined. %in% c('C3','C4')) 
C3_C4_cover<-plyr::ddply(C3_C4, c("site_unique", "Photosynthetic.pathway..combined."), summarise, Total_Cover = sum(species_cover_value, na.rm = T))
names(C3_C4_cover)[2]<-paste("Photosynthetic_pathway")
head(C3_C4_cover)


#The resulting table C3_C4_cover provides the % C3 and % C4 cover for each TERN plot.

##########################################
###########################################
###Extract Environmental Data for TERN Plots 
############################################
############################################

#In this example, we will look at how to swiftly extract site-specific environmental information for TERN plots
#and how to create data tables that could be used to regress C4 cover against any number of environmental variables 


#To collect soil, landscape, and/or climate information for each plot, we can take advantage of external data sources 
#Most national, high resolution environmental data are available as rasters, which can be imported into R using the 'raster' package
#Climate and soil rasters are available from a wide range of sources. 
#One potential Australia-wide option for climate data is '9s climatology for continental Australia 1976-2005' 
#provided by the Commonwealth Scientific and Industrial Research Organisation (CSIRO)
#available from https://data.csiro.au/dap/landingpage?pid=csiro%3A32093
#TERN soil and landscape rasters are available from the Soil and Landscape Grid of Australia https://www.clw.csiro.au/aclep/soilandlandscapegrid/index.html
#The Soil and Landscape Grid provides a range of soil and landscape attribute products.


#In this example, we will extract the predicted value for soil sand content (%) for the the top 0-30 cm at each TERN plot 
#we will do this using a sand content (%) raster provided by the Soil and Landscape Grid of Australia and CSIRO which can be accessed here https://data.csiro.au/collections/collection/CIcsiro:31613
#However, these code could be easily applied to other environmental rasters. 


#first, we need to combine each unique plot and survey with its latitude and longitude coordinates 
#plot coordinates are recorded in the $site.info table that is generated by get_ausplots()

longlat <- ausplots_data$site.info %>%
  select(site_unique,longitude, latitude) #extract longitude, latitude, and site unique from the site.info table

cover_siteinfo<-left_join(C3_C4_cover,longlat, by="site_unique") #combine the longlat coordinates with our C4 and C3 cover calculations
head(cover_siteinfo)


#Next, import the raster of your choice, in this case, it is sand content (%)

SND <- raster("~/SND.flt")


#next we extract the longlat values for the plots
myvars <- c("longitude", "latitude")
plot_locations <- cover_siteinfo[myvars]
plots<-SpatialPoints(plot_locations) #and convert them to spatial points
crs(plots) <- "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs+ towgs84=0,0,0" #assign the appropriate projection to the coordinates
SND<- raster::extract(SND, plots, method='simple', df=T) #and extract the soil sand content (%) values for each location
#depending on the number of points, this process may take a few minutes 

#lastly, these new sand content data can be combined to our originally C4 data frame
cover_siteinfo<-cbind(cover_siteinfo,SND$SND) 
colnames(cover_siteinfo)[6]<-"SND"


# the resulting table is now ready to be added to any number of statistical analysis, such as glm, gam, or PCA.



#All TERN data in this example has been released under a CC-BY Creative Commons license (https://creativecommons.org/licenses/by/4.0/), which allows reuse with attribution.
#Any work or publications using TERN ausplotsR or the photosynthetic data set should cite the package and data sources. 
#A suggested citation for TERN plot cover data is generated when the data is imported. 
#The photosynthetic pathway dataset can be cited using the data descriptor in Scientific Data
#The citation for ausplotsR can be generated using the citation function

citation('ausplotsR')

##################################################
###################END############################
##################################################


#References 

#Sparrow, B. D. et al. A vegetation and soil survey method for surveillance monitoring of rangeland environments. Front. Ecol. Evol. 8, doi:10.3389/fevo.2020.00157 (2020)

