crindt / chts-book Goto Github PK

# Source Overview

This distribution contains the complete source code and documentation
for the "Enhancing the Value of the 2010-12 California Household
Travel Survey (CHTS)" contract completed by the Institute of
Transportation Studies at Irvine (ITS).

# Organization

The source code and documentation are designed to be processed by the
R language and associated packages.  Most of the development in this
project used the [RStudio](http://www.rstudio.com) toolset, though use
of `RStudio` is not required to work with the code.


```{bash eval=FALSE}
README.md        # These instructions
chts-book.Rproj  # The RStudio project file
doc/             # directory holding the documentation
data/            # directory holding input and temporary output data
R/               # directory holding R source code used in the analysis
output/          # directory holding output data (e.g., CSV tables)
```

# Building the Documentation

Once you clone or unzip the source, you can build the documentation in
two ways.  Both assume you have installed the packages listed above in
your `R` environment, either using the `RStudio` package installation
interface or directly using interactive `R` shell.  Also, the
top-level directory of the book source code must start with the
text "chts-book".  If you clone repository or unzip the downloaded
file, this will be the case.

## Using `RStudio`

To generate the document using `RStudio`, you simply load run the
`RStudio` program, choose `File => Open Project` from the menu, and in
the file dialogue select the `chts-book.Rproj` file at the top-level
of the source directory (which should be called `chts-book`).  Once
you have done that, open the `doc/chts-book.Rmd` file using the
`files` tab.  Then, you should click the `Knit PDF` button.  This will
process the source code, re-running the R commands, and weave the
results into the book you are reading.  The process will generate the
`chts_book.pdf` file in the `doc` subdirectory.  You can see the
results of the processing the `RMarkdown` tab.  Producing the final
document will take anywhere from several to tens of minutes depending
on your hardware because the program is performing all of the
statistical calculations necessary to produce the results described in
the book.


## Using the Interactive R Shell 

For `R` purists, you may generate the documentation by opening a
command shell and changing into the `doc` subdirectory.  From there,
assuming that the R executable is installed and in your current PATH,
you can generate the document by issuing the following command:

```{bash eval=FALSE}
R --vanilla -e 'rmarkdown::render("chts_book.Rmd")'
```

Note, the above command is exactly what is executed in the background
when you click the `Knit PDF` button within `RStudio`.  `RStudio`
simply hides these details from the user to simplify things.  As with
the `RStudio` approach, the results of the processing will be printed
to the command line and the processing will take quite some time as
computations are performed.