CartDist
Code to re-project marine least-cost distances into Cartesian coordinates.
Example workflow 1) assemble coordinates in native geographic coordination, 2) calculate least-cost path accounting for land as barrier, 3) calculate 2 dimensional rescaling using metaMDS, 4) compare distances in 2 dimensional rescaling with least-cost distances. Example locations from Benestan et al. 2016.
Requirement: CartDist requires the installation and availability of the following packages
- CartDist requires the installation and availability of the following packages:
- extracting meta-data:
Make sure marmap version 0.9.6 or higher is installed.
Contributions:
CartDist was coded by Ryan Stanley https://github.com/rystanley and Nick Jeffery https://github.com/NickJeff13
- If you don’t understand something, please let me know: (ryan.stanley at dfo-mpo.gc.ca) or (nick.jeffery at dfo-mpo.gc.ca)
- Any ideas on how to improve the functionality are very much appreciated.
- If you spot a typo, feel free to edit and send a pull request.
Pull request how-to:
- Click the edit this page on the sidebar.
- Make the changes using github’s in-page editor and save.
- Submit a pull request and include a brief description of your changes. (e.g. "spelling errors" or "indexing error").
Citation
A Zenodo DOI is also avaiable for the most recent release of CartDist:
Stanley, R.R.E and N.W. Jeffery 2017. CartDist: Re-projection tool for complex marine systems. DOI 10.5281/zenodo.802875
Installation
CartDist can be sourced into the workspace by cloning this Github directory or by sourcing directly using the web url.
library(RCurl) # if you do not have the package rcurl installed please load from CRAN.
#links for the 'raw' code
Weblink <- c("https://raw.githubusercontent.com/rystanley/CartDist/master/CartDistFunction.R")
#source the 'raw' code links into the local environment
script <- RCurl::getURL(Weblink, ssl.verifypeer = FALSE)
eval(parse(text = script),envir=.GlobalEnv)
rm(script)
Output
The function will return a RData file containing the following objects. Note that the transition object can be used for later analyses within the same domain:
| Object | Description |
|---|---|
| Coords | Geographic and Cartesian coordinates. |
| fit.plot | Realized vs projected distance comparision. |
| mod | Realized vs projected distance model. |
| stress | the stress of the MDS reprojection. |
| trans | A transition object (object from the marmap::trans.mat or the transition object supplied by input parameter 'trans'). |
| lc.dist | Pairwise dissimilarity (km) among locations in the container provided by marmap::lc.dist. |
| bathydata | Bathymetric data calcaulted for region. |
Example use
| Parameter | Input |
|---|---|
| coordinates | This .csv file requires at least 3 columns - "Code","Lat", and "Long". Make sure your points are not on land prior to analysis. |
| min.depth | The minimum depth required to calculate least-cost distances for your species of interest. |
| max.depth | The minimum depth required to calculate least-cost distances for your species of interest. Can be NULL. |
| trans | A transition object (object from the marmap::trans.mat). Defualt is NA and will be calcauted. If this has been calculated already it can be included as a workspace object. |
| gridres | The resolution used during marmap's bathymetry calculations. Ranges from 1-4, with 1 being the highest resolution. Note that higher resolutions will take a longer time. |
| directory | The directory you want your results and figures deposited in. |
| outpath | This is the filepath for the output from the function a .Rdata file. Note this must be a full file path ending in .RData. If no path is provided a timestamped 'Output' .RData file will be created in the current directory. |
Re-project example coordinates into cartesian space accounting for land (>0 depth) as a impermeable barrier to dispersal. Note the data used in this example are available here. Locations are derived from RAD sequencing study on European green crab (Carcinus maenas) available here.
#Run the cartesian reprojection code
coord_cartesian("exampledata/examplecoordinates.csv", min.depth=0,max.depth=NULL, gridres=2, directory="~/Desktop/",outpath="exampledata/output.RData")
Here we can see that the function has stopped because the sample coordinates for the site "SGB" is on land. You will see the site code, longitude, latitude and estimated depth for any coordinates with positive depths.
To fix this issue we will need to bump the coordinate into water.
#read in coordinate file
coords <- read.csv("exampledata/examplecoordinates.csv",stringsAsfactors=F)
#bump the site location into water by moving the longitude west by 1.5 degrees.
coords[coords$Code=="SGB","Long"] <- -59.5
#save the revised file
write.csv("exampledata/examplecoordinates_revised.csv",row.names=F)
Now we can re-run the analysis using the revised coordinates which should all be on land. Note that if the adjustments to the coordinates did not work, a map will be returned.
#Run the cartesian reprojection code. Here we tweaked the analysis to exclude any depths shallower than 5m.
coord_cartesian("exampledata/examplecoordinates_revised.csv", min.depth=-5,max.depth=NULL, gridres=2, directory="~/Desktop/",outpath="exampledata/output.RData")
#load in the results from the last analysis
load("exampledata/output.RData")
#The transition object from the first run can be used again in subsequent runs.
coord_cartesian("exampledata/examplecoordinates_revised.csv", min.depth=-5,max.depth=NULL, gridres=2,trans=trans, directory="~/Desktop/",outpath="exampledata/output2.RData")
An example bathymetry map with points produced by this function using the marmap package Pante and Simon-Bouhet 2013
Example output. Shows a linear model of geographic versus Cartesian least-cost distances among sample sites. A strong positive relationship indicates that that your coordinates were re-projected correctly.
Final output will show your stress (<0.05 is good) and new Cartesian coordinates added to your coordinates input.
"metaMDS reprojection stress = 0.0097"
| Code | Long | Lat | MDS1 | MDS2 |
|---|---|---|---|---|
| BDB | -61.716 | 47.000 | -507.44 | -92.50 |
| BRN | -62.000 | 46.102 | -523.48 | -247.65 |
| CBI | -66.800 | 44.400 | 469.34 | -68.33 |
| CLH | -63.440 | 44.000 | 140.28 | 22.76 |
| KJI | -65.000 | 43.300 | 305.47 | -0.84 |
| MBO | -61.900 | 46.000 | -523.48 | -247.65 |
| NWH | -70.100 | 42.959 | 756.96 | -210.18 |
| PLB | -54.300 | 46.500 | -519.23 | 571.84 |
| SGB | -59.500 | 48.350 | -523.04 | 64.07 |
| SYH | -60.000 | 46.500 | -364.40 | 34.05 |
| TKT | -74.200 | 39.006 | 1289.02 | 174.43 |