Merge branch 'release/0.2.1'

.gitignore

@@ -2,3 +2,4 @@
 .Rhistory
 .RData
 tcadr.Rproj
+*.o

.travis.yml

@@ -0,0 +1,29 @@
+# Sample .travis.yml for R projects.
+#
+# See the r-travis repo and its wiki 
+#     https://github.com/craigcitro/r-travis/
+#     https://github.com/eddelbuettel/r-travis/
+
+language: c
+
+sudo: required
+
+before_install:
+  ## r-travis by Craig Citro et al
+  - curl -OL http://raw.github.com/craigcitro/r-travis/master/scripts/travis-tool.sh
+  - chmod 755 ./travis-tool.sh
+  - ./travis-tool.sh bootstrap
+
+install:
+  - ./travis-tool.sh install_aptget r-cran-rcpp r-cran-runit
+
+script: 
+  - ./travis-tool.sh run_tests
+
+after_failure:
+  - ./travis-tool.sh dump_logs
+
+notifications:
+  email:
+    on_success: change
+    on_failure: change

DESCRIPTION

@@ -1,18 +1,26 @@
 Package: tcadr
 Type: Package
 Title: Import TransCAD Objects to R
-Version: 0.0.2.2
-Date: 2015-09-25
+Version: 0.2.1
+Date: 2016-02-29
 Authors@R: c(
     person("Gregory", "Macfarlane", email = "[email protected]", role = c("aut", "cre")),
     person("Amar", "Sarvepalli", email = "[email protected]", role = c("aut"))
     )
 Description: Caliper's TransCAD application and GISDK language are widely used
     in travel demand modeling applications. However, it can be difficult to conduct
     complex analyses with these tools, because the file formats are unique and/or
-    non-standard. This package contains helper scripts to read TransCAD files for use
-    in R.
+    non-standard. This package contains helper scripts to read TransCAD files for
+    use in R.
 License: MIT + file LICENSE
 LazyData: TRUE
 LinkingTo: Rcpp
-Imports: Rcpp, dplyr, data.table
+Imports:
+    Rcpp,
+    dplyr,
+    data.table
+RoxygenNote: 5.0.1
+Suggests:
+    testthat
+Depends:
+    R (>= 3.2.2)

R/RcppExports.R

@@ -24,55 +24,30 @@ get_df_from_binary <- function(bin_file, name, type, start, width, row_length) {
     .Call('tcadr_get_df_from_binary', PACKAGE = 'tcadr', bin_file, name, type, start, width, row_length)
 }
 
-#' @title get columns
-#' @name getColumns
-#' @details To get number of dataframe columns
-#' @param df DataFrame object
-#' @return ncols number of columns
-#'
-getColumns <- function(df) {
-    .Call('tcadr_getColumns', PACKAGE = 'tcadr', df)
-}
-
-#' @title get rows
-#' @name getRows
-#' @details To get number of dataframe rows
-#' @param df DataFrame object
-#' @return nrows number of rows
+#' Get the dimensions of a data frame
 #'
-getRows <- function(df) {
-    .Call('tcadr_getRows', PACKAGE = 'tcadr', df)
-}
-
-#' @title get dimensions
-#' @name getDims
 #' @param df DataFrame object
 #' @details To get number of dataframe dimensions
-#' @return nrowcol array of rows and columns (r x c)
+#' @return Array with the number of rows and columns (r x c)
+#' @name getDims
 #'
-getDims <- function(df) {
-    .Call('tcadr_getDims', PACKAGE = 'tcadr', df)
-}
+NULL
 
-#' @title get field names
-#' @name getNames
+#' Get the names of the field headers
+#'
 #' @param df DataFrame object
-#' @details Method to extract dataframe column names
 #' @return names field names
+#' @name getNames
 #'
-getNames <- function(df) {
-    .Call('tcadr_getNames', PACKAGE = 'tcadr', df)
-}
+NULL
 
-#' @title get field width
-#' @name get_width
-#' @details Method to get column width
+#' Get the field width in bytes
+#'
 #' @param s character field
 #' @return element_width width of the column
+#' @name get_width
 #'
-get_width <- function(s) {
-    .Call('tcadr_get_width', PACKAGE = 'tcadr', s)
-}
+NULL
 
 #' @title parse line by comma deliminated
 #' @name name_split
@@ -81,32 +56,32 @@ get_width <- function(s) {
 #' @param delim delimter can be anything
 #' @return fields elements of string line
 #'
-name_split <- function(line, delim) {
-    .Call('tcadr_name_split', PACKAGE = 'tcadr', line, delim)
-}
+NULL
 
-#' @title write dictionary file
+#' Write a TransCAD Dictionary File
+#'
 #' @name write_dcb
-#' @param df DataFrame object
-#' @param file_name name of the file
-#' @details internal function dcb info 
-#' @details doesn't return anything
+#' @param df Data frame
+#' @param file Name and path to the \code{.DCB} file.
 #'
-write_dcb <- function(df, file_name) {
-    invisible(.Call('tcadr_write_dcb', PACKAGE = 'tcadr', df, file_name))
+write_dcb <- function(df, file) {
+    invisible(.Call('tcadr_write_dcb', PACKAGE = 'tcadr', df, file))
 }
 
-#' @title write binary file
+#' Write a binary TransCAD file from an R data frame.
+#'
+#' This is a C++ implementation written by Amar Sarvepalli and adapted for
+#' Rcpp by Greg Macfarlane.
+#' @param df List of variables (or a \code{data.frame}) that need to be
+#'   written out to TransCAD.
+#' @param file A character string giving the output file name and path.
+#' @param field_types A character vector giving the data types of each column.
 #' @name write_df_to_binary
-#' @param df DataFrame object
-#' @param file_name output filename
-#' @param field_types datatypes
-#' @details Method to export data from dataframe to binary file. 
-#' @details This exports only 3 datatypes: Character, Integer and Double 
-#' @details Writes the *.dcb file along with *.bin file
-#' @return new_dcb_info_df prints dictionary file to console
 #'
-write_df_to_binary <- function(df, file_name, field_types) {
-    .Call('tcadr_write_df_to_binary', PACKAGE = 'tcadr', df, file_name, field_types)
+#' @details Currently this function only exports only 3 datatypes: Character,
+#'   Integer and Double.
+#'
+write_df_to_binary <- function(df, file, field_types) {
+    invisible(.Call('tcadr_write_df_to_binary', PACKAGE = 'tcadr', df, file, field_types))
 }
 

R/assignment.R

@@ -0,0 +1,27 @@
+#' Read in TransCAD assignment file
+#'
+#' @description TransCAD returns fairly uniform assignment results containing
+#'   times, speeds, volumes, etc. by direction. This function returns the flow
+#'   information as a tidy data frame
+#'
+#' @param file Path to assignment binary file.
+#' @param field The name of the field to collect; if \code{NULL} (default), then
+#'   will return all fields.
+#'
+#' @import dplyr tidyr
+#'
+#' @export
+#' 
+read_assignment <- function(file, field = NULL){
+  a <- read_tcad(file) %>% 
+    rename(linkid = ID1)
+
+  # select chosen fields if any 
+  if(!is.null(field)){
+    a <- select(a, linkid, matches(field))
+  }
+
+  a %>%
+    gather(field, value, -linkid)  %>%
+    separate(field, c("dir", "field"), extra = "merge")
+}

R/read_tcad.R

@@ -5,8 +5,10 @@
 #' @param file The path and name of the binary data file, e.g.
 #'   \code{data/foo.bin}. The \code{DCB} dictionary file should be in the same
 #'   folder.
-#' @param df_only Should the function return a `data.frame` or a list with
-#' the descriptions appended? \code{default = TRUE}
+#' @param df_only Should the function return a `data.frame` or a list with the
+#'   descriptions appended? \code{default = TRUE}
+#' @param strip_whitespace Should excess whitespace be stripped from character 
+#'   variables? \code{default = TRUE}
 #' 
 #' @details If any variable descriptions are available in the dictionary file, 
 #'   then they will be appended to the \code{attr(*, "label")} attribute (and 
@@ -20,7 +22,7 @@
 #' @importFrom data.table setattr
 #' @importFrom dplyr data_frame mutate_each_ tbl_df
 #'
-read_tcad_bin <- function(file, df_only = TRUE){
+read_tcad <- function(file, df_only = TRUE, strip_whitespace = TRUE){
 
 
   # Get file string for the DCB file.
@@ -37,14 +39,21 @@ read_tcad_bin <- function(file, df_only = TRUE){
   df <- dplyr::tbl_df(as.data.frame(
     get_df_from_binary(path.expand(file), 
                        dcb$name, dcb$type,
-                       dcb$start, dcb$width,
+                       dcb$start, dcb$d_width,
                        row_length),
     stringsAsFactors = FALSE)
     )
 
-  # strip white space from character strings
-  character_vars <- names(df)[sapply(df, is.character)]
-  df <- dplyr::mutate_each_(df, dplyr::funs(trim), character_vars)
+  # strip white space from character strings; 
+  if(strip_whitespace){
+    character_vars <- names(df)[sapply(df, is.character)]
+
+    # only trim if character variables exist in the data.
+    if(length(character_vars > 0)){
+      df <- dplyr::mutate_each_(df, dplyr::funs(trim), character_vars)
+    }
+
+  }
 
   # add labels to data frame if they exist.
   if(any(!is.na(dcb$description))){

R/write_tcad.R

@@ -1,21 +1,23 @@
-#' @title Write a TransCAD binary file
+#' Write a TransCAD binary file
 #'
-#' @description Write a TransCAD \code{.bin} binary data file fromt the workspace.
+#' @description Write a TransCAD \code{.bin} binary data file from the workspace.
 #'
 #' @param df workspace dataframe object
 #'
-#' @param file_name The path and name of the binary data file, e.g.
+#' @param file The path and name of the binary data file, e.g.
 #'   \code{data/foo.bin}.
 #'
-#' @details If any factors exist in the data frame, then those fields are writern 
-#'   out with factor level (instead of actualvalue). Remove dataframe factors.
 #' @details This version doesn't work well with NA's in the dataframe. 
 #'
-#' @return The \code{DCB} dictionary file will be writern to the same
-#'   folder. Prints dcb file contents to console.Need to make it a user defined 
-#'   option.
+#' @return The \code{DCB} dictionary file will be written to the same
+#'   folder as the \code{.bin} file. 
 #'
-write_bin <-  function(df,file_name){
-    typs <- sapply(df,typeof)
-    write_df_to_binary(df,file_name,typs)
+write_tcad <- function(df, file){
+
+  i <- sapply(df, is.factor) # which variables are factors?
+  df[i] <- lapply(df[i], as.character) # convert them to char strings
+
+  typs <- sapply(df, typeof)
+  write_df_to_binary(df, path.expand(file), typs)
+
 }

README.md

@@ -3,24 +3,32 @@ tcadr
 
 This is a library of functions that can be used to read native TransCAD files
 directly into R without intermediate conversion to `.csv` or `.dbf`. Currently 
-the package will read binary data tables (including network attributes), but I 
-hope to extend the package to cover shape data and networks in the future.
+the package will read and write binary data tables (including network
+attributes), but I hope to extend the package to cover shape data and networks
+in the future.
 
 Installation
 --------------
-The package is not (yet) on CRAN. The easiest way to install it is with
+The package is not (yet) on CRAN. The easiest way to install the latest stable
+version is with
 
     devtools::install_github("pbsag/tcadr")
 
 Using the [devtools](https://github.com/hadley/devtools) library will require you
 to install RTools and Rccp, among other things. RStudio should make this mostly
 automatic.
 
+Alternatively, you may download the source code from the links on the right and
+install with 
+
+    R CMD INSTALL tcadr.zip
+
 Use
 --------------
 
     library(tcadr)
-    ?read_tcad_bin()
+    ?read_tcad()
+    ?write_tcad()
 
 
 This package is under active development, and any contribution is welcome.