still finalizing v 1.0.0

jdbcode · Jul 29, 2015 · 70cfc0f · 70cfc0f
1 parent 7dfde04
commit 70cfc0f
Show file tree

Hide file tree

Showing 18 changed files with 60 additions and 43 deletions.
diff --git a/.Rprofile b/.Rprofile
diff --git a/R/MSScvm.r b/R/MSScvm.r
@@ -1,11 +1,17 @@
-#' Create a cloud and cloud shadow mask for Landsat MSS imagery
+#' Landsat MSS cloud and cloud shadow masking
 #' 
-#' Create a cloud and cloud shadow mask for Landsat MSS imagery
+#' Creates a cloud and cloud shadow mask for Landsat MSS imagery.
 #' @param imgDir directory name (character). Full path to a MSS image directory produced by the \code{\link{MSSunpack}} function.
 #' @param demFile filename (character). Full path to image-corresponding DEM file.
-#' @param classify logical. If TRUE clouds, cloud shadows, and clear pixels have unique values. If FALSE obscured pixels are value 0 and clear are 1.
-#' @details bla
-#' @return A binary raster with the same dimensions as the MSS image where pixels with value 1 represent clear pixel and 0 as obsured by either cloud or cloud shadow
+#' @param classify logical. If TRUE clouds, cloud shadows, and clear pixels have unique values (0 = clear, 1 = cloud shadow, 2 = cloud). 
+#' If FALSE obscured pixles = 0 and clear = 1.
+#' @details It is important that the input DEM file, specified by the 'demFile' parameter, be the same projection and pixel resolution as the
+#' input image. It must also be >= in spatial extent, relative to the image. The program will check for these attributes and throw an error message if 
+#' there is a violation. There are two helper functions to prepare a suitable DEM. Use the \code{\link{reprojectDEM}} function to ensure proper projection
+#' and pixel resolution of an exisiting DEM, and the \code{\link{mosaicDEMs}} function to create a mosaic from several DEMs to ensure proper extent, projection, 
+#' and pixel resolution. 
+#' @return A GeoTIFF raster image file with the same dimensions as the MSS image. The file will be placed in the
+#' 'imgDir' directory with the name equal to the image ID followed by '_msscvm'.
 #' @examples 
 #' \dontrun{
 #' 

diff --git a/R/MSSdn2rad.r b/R/MSSdn2rad.r
@@ -1,6 +1,6 @@
 #' Convert MSS DN values to TOA radiance
 #'
-#' Convert MSS DN values to TOA radiance
+#' Convert MSS DN values to TOA radiance.
 #' @param imgFile filename (character). Full path to *dn.tif image file produced by the \code{\link{MSSunpack}} function.
 #' @details The equation used to convert DN to TOA radiance can be found \href{http://landsat.usgs.gov/how_is_radiance_calculated.php}{here}.
 #' @return A 4-band Landsat MSS GeoTIFF raster image file in units of top-of-atmosphere (TOA) radiance. The file will be placed in

diff --git a/R/MSSdn2refl.r b/R/MSSdn2refl.r
@@ -1,6 +1,6 @@
-#' Convert DN values to TOA reflectance
+#' Convert MSS DN values to TOA reflectance
 #'
-#' Convert DN values to TOA reflectance
+#' Convert MSS DN values to TOA reflectance.
 #' @param imgFile filename (character). Full path to *dn.tif image file produced by the \code{\link{MSSunpack}} function.  
 #' @details DN values are first converted to top-of-atmosphere (TOA) radiance using the equation found \href{http://landsat.usgs.gov/how_is_radiance_calculated.php}{here}.
 #' Then TOA radiance is converted to TOA reflectance using the equation found \href{http://landsathandbook.gsfc.nasa.gov/data_prod/prog_sect11_3.html}{here}.

diff --git a/R/MSSunpack.r b/R/MSSunpack.r
@@ -11,8 +11,8 @@
 #' This mitigates a problem caused by bad columns on the east and west edge of images when mosaicing adjacent images together.  
 #' @return A 4-band Landsat MSS GeoTIFF raster image file in DN units. If optional 'toaRad' and/or 'toaRefl' 
 #' parameters are set to TRUE, then similar TOA radiance and reflectance image files will created. The files will be places in
-#' directory in the same location as the 'imgFile' with the name equal to the image ID. The files contain the image ID with
-#' descriptors 'dn' (digital number), 'toa_radiance' (TOA radiance), and 'toa_reflectance' (TOA reflectance).
+#' the same location as the 'imgFile' with the name equal to the image ID plus an appended descriptor. Descriptors
+#' include 'dn' (digital number), 'toa_radiance' (TOA radiance), and 'toa_reflectance' (TOA reflectance).
 #' @seealso \code{\link{MSSdn2rad}}, \code{\link{MSSdn2refl}}
 #' @examples 
 #' \dontrun{

diff --git a/R/eudist.r b/R/eudist.r
@@ -1,7 +1,8 @@
 #' Earth-Sun distance by day-of-year
 #'
-#' Retrieve the Earth-Sun distance by day-of-year
-#' @param doy integer. image day-of-year
+#' Retrieve the Earth-Sun distance by day-of-year. It is helper function used
+#' by the \code{\link{MSSdn2refl}} and \code{\link{MSScvm}} functions when calculating TOA reflectance.
+#' @param doy integer. image day-of-year.
 #' @details The function returns the Earth-sun distance for a specific day-of-year as defined
 #' \href{http://landsathandbook.gsfc.nasa.gov/data_prod/prog_sect11_3.html}{here}.
 #' @examples dist = eudist(215)

diff --git a/R/getMetadata.r b/R/getMetadata.r
@@ -1,7 +1,7 @@
 #' Retrieve Landsat image metadata
 #' 
 #' Uses the image file name to find the corresponding *MTL.txt image metadata file provided with LPSG Landsat images
-#' and returns a dataframe with image information
+#' and returns a data.frame with image information.
 #' @param imgFile filename (character). Full path to a Landast LPGS MSS file that includes the 
 #' original image ID as the first block of characters. 
 #' @return data.frame with image information.

diff --git a/R/mosaicDEMs.r b/R/mosaicDEMs.r
@@ -1,10 +1,10 @@
 #' Create a DEM mosaic from a direcory of DEM's
 #'
-#' A helper function to create the large-extent DEM file required by the 'MSScvm' function.
+#' A helper function to create the large-extent DEM file required by the \code{\link{MSScvm}} function.
 #' @param dir directory name (character). Full path to a directory containing digital elevation model (DEM) files to be mosaiced.
-#' @param projRef filename (character). Full path to an image file produced by the \code{\link{MSSunpack}} function.
-#' @param srcNodata numeric. What is the background value of the DEM files in the directory. If there is no background value, use NA (default) 
-#' @param dstNodata numeric. Specify the value to represent background pixels in the mosaic DEM. -32768 is the default
+#' @param projRef filename (character). Full path to an image file produced by the \code{\link{MSSunpack}} function to be used as the projection reference.
+#' @param srcNodata numeric. Specify the background value of the DEM files in the directory. If there is no background value, use NA (default) .
+#' @param dstNodata numeric. Specify the value to represent background pixels in the mosaic DEM. -32768 is the default.
 #' @details The provided directory path should only contain decompressed digital elevation files from the same source (SRTM, NED, GTOPO, etc).
 #' The function will search the directory and include all files found in the mosaic. It is important that each file have the same background value
 #' and that it is correctly assigned to the 'srcNodata' parameter, if not, intersection between DEMs could have unexpected results. 

diff --git a/R/reprojectDEM.r b/R/reprojectDEM.r
@@ -1,13 +1,13 @@
 #' Reproject a DEM file
 #'
 #' Reproject a DEM file to match the projection and pixel resolution of an image file. A helper function to make a DEM
-#' conform to the properties of an image file prior to using it as an input to the 'MSScvm' masking function
+#' conform to the properties of an image file prior to using it as an input to the \code{\link{MSScvm}} masking function.
 #' @param demFile filename (character). Full path to DEM file.
 #' @param projRef filename (character). Full path to an image file produced by the \code{\link{MSSunpack}} function.
-#' @param srcNodata numeric. Specify the background value in the input DEM. If there is no background value, use NA (default)
-#' @param dstNodata numeric. Specify the value to represent background pixels in the reprojected DEM. -32768 is the default
+#' @param srcNodata numeric. Specify the background value in the input DEM. If there is no background value, use NA (default).
+#' @param dstNodata numeric. Specify the value to represent background pixels in the reprojected DEM. -32768 is the default.
 #' @details The DEM file will be adjusted to match the projection and pixel resolution of the 'proRef' image.
-#' @return A GeoTIFF raster file with '_reprojected.tif' replacing the last 4 characters of the input DEM filename
+#' @return A GeoTIFF raster file with '_reprojected.tif' replacing the last 4 characters of the input DEM filename.
 #' @seealso \code{\link{mosaicDEMs}}
 #' @examples \dontrun{
 #' 

diff --git a/README.md b/README.md
@@ -1,2 +1,6 @@
 # MSScvm
 [![Travis-CI Build Status](https://travis-ci.org/jdbcode/MSScvm.svg?branch=master)](https://travis-ci.org/jdbcode/MSScvm)
+
+An automated cloud and cloud shadow masking system for Landsat MSS imagery. It provides a means of more easily incorporating MSS imagery in large-area and time series analysis by providing an efficient way to prevent cloud and cloud shadow pixels from contaminating mosaics, composites, and time series.
+
+http://www.msscvm.jdbcode.com/
diff --git a/man/MSScvm.Rd b/man/MSScvm.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/MSScvm.r
 \name{MSScvm}
 \alias{MSScvm}
-\title{Create a cloud and cloud shadow mask for Landsat MSS imagery}
+\title{Landsat MSS cloud and cloud shadow masking}
 \usage{
 MSScvm(imgDir, demFile, classify = F)
 }
@@ -11,16 +11,22 @@ MSScvm(imgDir, demFile, classify = F)
 
 \item{demFile}{filename (character). Full path to image-corresponding DEM file.}
 
-\item{classify}{logical. If TRUE clouds, cloud shadows, and clear pixels have unique values. If FALSE obscured pixels are value 0 and clear are 1.}
+\item{classify}{logical. If TRUE clouds, cloud shadows, and clear pixels have unique values (0 = clear, 1 = cloud shadow, 2 = cloud).
+If FALSE obscured pixles = 0 and clear = 1.}
 }
 \value{
-A binary raster with the same dimensions as the MSS image where pixels with value 1 represent clear pixel and 0 as obsured by either cloud or cloud shadow
+A GeoTIFF raster image file with the same dimensions as the MSS image. The file will be placed in the
+'imgDir' directory with the name equal to the image ID followed by '_msscvm'.
 }
 \description{
-Create a cloud and cloud shadow mask for Landsat MSS imagery
+Creates a cloud and cloud shadow mask for Landsat MSS imagery.
 }
 \details{
-bla
+It is important that the input DEM file, specified by the 'demFile' parameter, be the same projection and pixel resolution as the
+input image. It must also be >= in spatial extent, relative to the image. The program will check for these attributes and throw an error message if
+there is a violation. There are two helper functions to prepare a suitable DEM. Use the \code{\link{reprojectDEM}} function to ensure proper projection
+and pixel resolution of an exisiting DEM, and the \code{\link{mosaicDEMs}} function to create a mosaic from several DEMs to ensure proper extent, projection,
+and pixel resolution.
 }
 \examples{
 \dontrun{

diff --git a/man/MSSdn2rad.Rd b/man/MSSdn2rad.Rd
@@ -15,7 +15,7 @@ same directory as the 'imgFile' with the name equal to the image ID followed by
 and rounded to the nearest integer to reduce the file size.
 }
 \description{
-Convert MSS DN values to TOA radiance
+Convert MSS DN values to TOA radiance.
 }
 \details{
 The equation used to convert DN to TOA radiance can be found \href{http://landsat.usgs.gov/how_is_radiance_calculated.php}{here}.

diff --git a/man/MSSdn2refl.Rd b/man/MSSdn2refl.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/MSSdn2refl.r
 \name{MSSdn2refl}
 \alias{MSSdn2refl}
-\title{Convert DN values to TOA reflectance}
+\title{Convert MSS DN values to TOA reflectance}
 \usage{
 MSSdn2refl(imgFile)
 }
@@ -15,7 +15,7 @@ same directory as the 'imgFile' with the name equal to the image ID followed by
 and rounded to the nearest integer to reduce the file size.
 }
 \description{
-Convert DN values to TOA reflectance
+Convert MSS DN values to TOA reflectance.
 }
 \details{
 DN values are first converted to top-of-atmosphere (TOA) radiance using the equation found \href{http://landsat.usgs.gov/how_is_radiance_calculated.php}{here}.

diff --git a/man/MSSunpack.Rd b/man/MSSunpack.Rd
@@ -18,8 +18,8 @@ MSSunpack(imgFile, toaRad = FALSE, toaRefl = FALSE, useL1G = FALSE)
 \value{
 A 4-band Landsat MSS GeoTIFF raster image file in DN units. If optional 'toaRad' and/or 'toaRefl'
 parameters are set to TRUE, then similar TOA radiance and reflectance image files will created. The files will be places in
-directory in the same location as the 'imgFile' with the name equal to the image ID. The files contain the image ID with
-descriptors 'dn' (digital number), 'toa_radiance' (TOA radiance), and 'toa_reflectance' (TOA reflectance).
+the same location as the 'imgFile' with the name equal to the image ID plus an appended descriptor. Descriptors
+include 'dn' (digital number), 'toa_radiance' (TOA radiance), and 'toa_reflectance' (TOA reflectance).
 }
 \description{
 Decompresses and stacks Landsat LPGS MSS images provided by USGS as *.tar.gz files. Optionally

diff --git a/man/eudist.Rd b/man/eudist.Rd
@@ -7,10 +7,11 @@
 eudist(doy)
 }
 \arguments{
-\item{doy}{integer. image day-of-year}
+\item{doy}{integer. image day-of-year.}
 }
 \description{
-Retrieve the Earth-Sun distance by day-of-year
+Retrieve the Earth-Sun distance by day-of-year. It is helper function used
+by the \code{\link{MSSdn2refl}} and \code{\link{MSScvm}} functions when calculating TOA reflectance.
 }
 \details{
 The function returns the Earth-sun distance for a specific day-of-year as defined

diff --git a/man/getMetadata.Rd b/man/getMetadata.Rd
@@ -15,7 +15,7 @@ data.frame with image information.
 }
 \description{
 Uses the image file name to find the corresponding *MTL.txt image metadata file provided with LPSG Landsat images
-and returns a dataframe with image information
+and returns a data.frame with image information.
 }
 \examples{
 \dontrun{

diff --git a/man/mosaicDEMs.Rd b/man/mosaicDEMs.Rd
@@ -9,18 +9,18 @@ mosaicDEMs(dir, projRef, srcNodata = NA, dstNodata = -32768)
 \arguments{
 \item{dir}{directory name (character). Full path to a directory containing digital elevation model (DEM) files to be mosaiced.}
 
-\item{projRef}{filename (character). Full path to an image file produced by the \code{\link{MSSunpack}} function.}
+\item{projRef}{filename (character). Full path to an image file produced by the \code{\link{MSSunpack}} function to be used as the projection reference.}
 
-\item{srcNodata}{numeric. What is the background value of the DEM files in the directory. If there is no background value, use NA (default)}
+\item{srcNodata}{numeric. Specify the background value of the DEM files in the directory. If there is no background value, use NA (default) .}
 
-\item{dstNodata}{numeric. Specify the value to represent background pixels in the mosaic DEM. -32768 is the default}
+\item{dstNodata}{numeric. Specify the value to represent background pixels in the mosaic DEM. -32768 is the default.}
 }
 \value{
 A GeoTIFF raster file representing the union of all individual DEM files found in the provided directory path. The mosaic file will be written to the
 provided directory as "dem_mosaic.tif".
 }
 \description{
-A helper function to create the large-extent DEM file required by the 'MSScvm' function.
+A helper function to create the large-extent DEM file required by the \code{\link{MSScvm}} function.
 }
 \details{
 The provided directory path should only contain decompressed digital elevation files from the same source (SRTM, NED, GTOPO, etc).

diff --git a/man/reprojectDEM.Rd b/man/reprojectDEM.Rd
@@ -11,16 +11,16 @@ reprojectDEM(demFile, projRef, srcNodata = NA, dstNodata = -32768)
 
 \item{projRef}{filename (character). Full path to an image file produced by the \code{\link{MSSunpack}} function.}
 
-\item{srcNodata}{numeric. Specify the background value in the input DEM. If there is no background value, use NA (default)}
+\item{srcNodata}{numeric. Specify the background value in the input DEM. If there is no background value, use NA (default).}
 
-\item{dstNodata}{numeric. Specify the value to represent background pixels in the reprojected DEM. -32768 is the default}
+\item{dstNodata}{numeric. Specify the value to represent background pixels in the reprojected DEM. -32768 is the default.}
 }
 \value{
-A GeoTIFF raster file with '_reprojected.tif' replacing the last 4 characters of the input DEM filename
+A GeoTIFF raster file with '_reprojected.tif' replacing the last 4 characters of the input DEM filename.
 }
 \description{
 Reproject a DEM file to match the projection and pixel resolution of an image file. A helper function to make a DEM
-conform to the properties of an image file prior to using it as an input to the 'MSScvm' masking function
+conform to the properties of an image file prior to using it as an input to the \code{\link{MSScvm}} masking function.
 }
 \details{
 The DEM file will be adjusted to match the projection and pixel resolution of the 'proRef' image.