|
| 1 | +--- |
| 2 | +title: "Segmentation Overview" |
| 3 | +author: "Rob Fowler" |
| 4 | +date: "`r Sys.Date()`" |
| 5 | +output: rmarkdown::html_vignette |
| 6 | +vignette: > |
| 7 | + %\VignetteIndexEntry{Segmentation Overview} |
| 8 | + %\VignetteEngine{knitr::rmarkdown} |
| 9 | + %\VignetteEncoding{UTF-8} |
| 10 | +--- |
| 11 | + |
| 12 | +```{r setup, include = FALSE} |
| 13 | +knitr::opts_chunk$set( |
| 14 | + collapse = TRUE, |
| 15 | + comment = "#>" |
| 16 | +) |
| 17 | +``` |
| 18 | + |
| 19 | + |
| 20 | +```{r include=FALSE} |
| 21 | +library(nwasc) |
| 22 | +``` |
| 23 | + |
| 24 | +# Introduction |
| 25 | +The goal of nwasc is to segment survey data from the [Northwest Atlantic |
| 26 | +Seabird Catalog |
| 27 | +(NWASC)](https://github.com/USFWS/AMAPPS/tree/master/NWASC). This webpage serves as an overview of the nwasc package. The nwasc r-pack is located at https://github.com/robgf/nwasc. |
| 28 | + |
| 29 | +To attach (install) the nwasc package to your library use the following code: |
| 30 | + |
| 31 | +```{r echo=TRUE, eval=FALSE} |
| 32 | +devtools::install_github("robgf/nwasc") |
| 33 | +``` |
| 34 | + |
| 35 | +Please consider creating a fork to this repository. Requests for fixes or enhancements should be documented with a filled issue at https://github.com/robgf/nwasc/issues. |
| 36 | + |
| 37 | +Plans are to relocate this repository within the U.S. FWS GitHub This site and accompanying documentation will be updated at that time. |
| 38 | + |
| 39 | +# Guiding Principles |
| 40 | +The goal of this package is to have a |
| 41 | + |
| 42 | +- Simple |
| 43 | +- Well documented |
| 44 | + |
| 45 | +code with: |
| 46 | + |
| 47 | +- Reproducible results |
| 48 | + |
| 49 | +for segmenting the transect and observation data contained in the [NWASC](https://github.com/USFWS/AMAPPS/tree/master/NWASC)]. Request or submissions of data from the NWASC should be made following the directions on the NWASC website. |
| 50 | + |
| 51 | + |
| 52 | +# Organization |
| 53 | +There are four (4) exported functions. All with prefix "nwasc_" to avoid any conflicts with other packages already installed by the user. The two segmentation functions nwasc_segmentCTS() and nwasc_segmentDTS() are wrapper functions for the family of segmentation internal functions which can be found in the `R/` directory of the repo. |
| 54 | +The other exported functions aid in the finalization of the segmented data. In practice there are three segmented data frames, 1) Continuous Time Survey (CTS) data segmented from phase 2 of the NWASC, 2) CTS data segmented from phase 1 of the NWASC and 3) Discrete Time Survey (DTS) data segmented from phase 1 of the NWASC. We do not expect to receive any further DTS as modern surveys use GPS systems during collection active. |
| 55 | + |
| 56 | +The nwasc_segmentCTS() requires queries from three of the NWASC tables. |
| 57 | +From the `obsevations` table the following columns need to be pulled: |
| 58 | +```{r observation namas } |
| 59 | +names(nwasc.ph2.obs.pre) |
| 60 | +``` |
| 61 | + |
| 62 | +From the `tracks` table: |
| 63 | +```{r track names} |
| 64 | +names(nwasc.ph2.shp.pre) |
| 65 | +``` |
| 66 | + |
| 67 | +From the `transect` table" |
| 68 | +```{r transect names} |
| 69 | +names(nwasc.ph2.cts.dat) |
| 70 | +``` |
| 71 | + |
| 72 | +**Note:** `source_transect_id` is renamed `segmented_transect_id` in the query. |
| 73 | + |
| 74 | +As the location of the NWASC and version of the Catalog vary the precise SQL query will depend on the present circumstances. If the Catalog becomes static this page can be updated with example SQL query. |
| 75 | + |
| 76 | +Example of clean data (circa Summer 2017) included in package (35MB) `.rda` files are stored in `data/` |
| 77 | + |
| 78 | +# Documentation |
| 79 | +## Short form |
| 80 | +* All functions internal and exported of the package are documented using ROxygen2 |
| 81 | +* Function parameters an returns documented along with example usage |
| 82 | +* Allows for standard R help: |
| 83 | +```{r echo=TRUE, eval=FALSE} |
| 84 | +?nwasc |
| 85 | +?nwasc_SegmentCTS |
| 86 | +``` |
| 87 | +* compiled manuals are located in `man/` folder. |
| 88 | + |
| 89 | +## Long form vignette |
| 90 | +Presently this package has one vignette. `segmentation_overview_example` an html and pdf copy are contained in the `doc/` folder. |
| 91 | + |
| 92 | + |
| 93 | +# Running code |
| 94 | +Running the code in this package requires queries from the NWASC as described above. Example data that was used for NOAA's mapping project are located in the `data/` folder and can be called by name when this package is loaded, see below. |
| 95 | + |
| 96 | +**NOTE!** Due to the size of the NWASC this takes a while (Coffee Break Time) |
| 97 | + |
| 98 | +As of the data query used as an example in this package the NWASC consisted of two phases with CTS data in both phases and DTS data in the phase 1. The steps to segment the catalog are: |
| 99 | +1. segment the CTS and DTS data by phase (historically from separate database locations) |
| 100 | +2. Combine the separate dataframes (note: since tibbles inherit from class 'data.frame' data frame and tibble are use interchangeably here.) |
| 101 | +3. Write a data stamped .csv for sharing |
| 102 | + |
| 103 | +Example run: |
| 104 | + |
| 105 | +```{r echo=TRUE, eval=FALSE} |
| 106 | +#load nwasc paskage (see attaching directions above) |
| 107 | +library(nwasc) |
| 108 | +seg.dat.phase2 = nwasc_segmentCTS(nwasc.ph2.obs.pre, |
| 109 | + nwasc.ph2.shp.pre, |
| 110 | + nwasc.ph2.cts.dat, |
| 111 | +
|
| 112 | +seg.dat.phase1.cts = nwasc_segmentCTS(nwasc.ph1.obs.pre, |
| 113 | + nwasc.ph1.shp.pre, |
| 114 | + nwasc.ph1.cts.dat, |
| 115 | +
|
| 116 | +seg.dat.phase1.dts = nwasc_segmentDTS(nwasc.ph1.dts.obs.dat, |
| 117 | + nwasc.ph1.dts.dat) |
| 118 | +
|
| 119 | +segmented_seabird_catalogs <- nwasc_bind_phases(seg.dat.phase2, seg.dat.phase1.cts, seg.dat.phase1.dts) |
| 120 | +nwasc_write_segmented_csv(segmented_seabird_catalogs) |
| 121 | +zip("segmented_results", file = "segmented_seabird_catalog-2018-09-27-combined_transects_3 .csv") |
| 122 | +
|
| 123 | +``` |
| 124 | + |
0 commit comments