Merge pull request #340 from UBC-DSCI/dev

Dev

Author: trevorcampbell

.gitignore

@@ -7,3 +7,6 @@
 _bookdown_files
 **.ipynb_checkpoints
 .rstudio/*
+pdf/_book
+pdf/_bookdown_files
+pdf/*.log

LICENSE.md

@@ -1,23 +1,21 @@
-**CC BY 2.5 CA**
+# License
 
-An Introduction to Data Science is
-made available under the **Attribution-NonCommercial-ShareAlike 4.0 International** ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)). 
+This textbook is made available under the **Attribution-NonCommercial-ShareAlike 4.0 International** ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)). 
 
 This is a human-readable summary of (and not a substitute for) the [license](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode).
 
 ## You are free to:
-**Share** — copy and redistribute the material in any medium or format
-**Adapt** — remix, transform, and build upon the material for any purpose, even commercially.
+
+- **Share** — copy and redistribute the material in any medium or format
+- **Adapt** — remix, transform, and build upon the material
 
 The licensor cannot revoke these freedoms as long as you follow the license terms.
 
 ## Under the following terms:
 
-**Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
-
-**NonCommercial** — You may not use the material for commercial purposes.
-
-**ShareAlike** — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
+- **Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+- **NonCommercial** — You may not use the material for commercial purposes.
+- **ShareAlike** — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
 
 **No additional restrictions** — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
 

README.md

@@ -1,5 +1,11 @@
-## Introduction to Data Science
-This is the source for the Introduction to Data Science textbook.
+## Data Science: A First Introduction 
+This is the source for the *Data Science: A First Introduction* textbook.
+
+## License Information
+
+This textbook is offered under 
+the [Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+See [the license file](LICENSE.md) for more information. 
 
 ## Setup and Build
 
@@ -20,22 +26,19 @@ We provide instructions for both methods here.
 
 To build the **html version** of the book, navigate to the repository root folder and run
 ```
-./build.sh
+./build_html.sh
 ``` 
 from the command line. This command automatically spawns a docker container
-with the `ubcdsci/intro-to-ds` image, runs the script `build.R` from within the container,
-and then stops the container. It may ask you for a password; this is the password for the
-`sudo` command on your computer. Typically this is just your usual computer user account password.
-But if your setup doesn't require you to use `sudo` to start a docker container, you can just
-open `build.sh` and delete the word `sudo` at the start of the script.
+with the `ubcdsci/intro-to-ds` image, runs the script `_build_html.r` from within the container,
+and then stops the container. 
 
 To build the **PDF version** of the book, instead run
 ```
-./pdfbuild.sh
+./build_pdf.sh
 ```
-The same comments regarding passwords and `sudo` as above apply here.
+This command again spawns a docker container and runs `pdf/_build_pdf.r` inside the container.
 
-### With RStudio
+### With RStudio (HTML only)
 
 1. Run RStudio inside the `ubcdsci/intro-to-ds` docker container:
     - in terminal, navigate to the root of this project repo
@@ -120,23 +123,39 @@ bookdown::gitbook:
 - when saying that students will do things in code, always say "in R"
 - "you will be able to" (not "students will be able to", "the reader will be able to")
 
+#### Captions
+- captions should be sentence formatted and end with a period
+- If you have special characters (particularly underscores, quotation marks, plus signs, other LaTeX math symbols) make sure to separate
+  the caption out of the code chunk like so
+  ```
+  (ref:blah)
+  
+  \`\`\`
+  {r blah, other_options}
+  code here
+  \`\`\`
+  ```
+
 #### Equations
 - make sure all equations get capitalized labels ("Equation \\@ref(blah)", not "equation below" or "equation above")
 
 #### Figures
 - make sure all figures get (capitalized) labels ("Figure \\@ref(blah)", not "figure below" or "figure above")
 - make sure all figures get captions
 - specify image widths in terms of linewidth percent (e.g. `out.width="70%"`)
-- center align all images
+- center align all images via `fig.align = "center"`
 - make sure we have permission for every figure/logo that we use
 - Make sure all figures follow the visualization principles in Chapter 4
 - Make sure axes are set appropriately to not inflate/deflate differences artificially *where it does not compromise clarity* (e.g. in the classification
   chapter there are a few examples where zoomed-in accuracy axes are better than using the full range 0 to 1)
+- 
 
 #### Tables
 - make sure all tables get capitalized labels ("Table \\@ref(blah)", not "table below" or "table above")
 - make sure all tables get captions
 - make sure the row + column spacing is reasonable
+- Do not put links in table captions, it breaks pdf rendering
+- Do not put underscores in table captions, it breaks pdf rendering
 
 #### Note boxes
 - note boxes should be typeset as quote boxes using `>` and start with **Note:**
@@ -178,6 +197,10 @@ Generally the book uses American spelling. Some common British vs American and C
 - c vs s: defense (not defence)
 - er vs re: center (not centre)
 
+#### Whitespace
+We need a line of whitespace before and after code fences (code surrounded by three backticks above and below). This is for readability, 
+and it is essential for figure captions.
+
 #### PDF Output
 These are absolute last steps when rendering the PDF output:
 - Look for and fix bad line breaks (e.g. with only one word on the next line, orphans, and widows)
@@ -211,6 +234,3 @@ docker run --rm -it -p 8888:8888 -v $PWD:/home/rstudio/introduction-to-datascien
 - `data/` stores datasets processed during compile
 - `docs/.nojekyll` tells github's static site builder not to run [Jekyll](https://jekyllrb.com/). This avoids Jekyll deleting the folder `docs/_main_files` (as it starts with an underscore)
 
-## License Information
-
-[Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/)

_build.R renamed to _build_html.r

@@ -0,0 +1,2 @@
+# Acknowledgments {-}
+

_pdfbuild.R

@@ -0,0 +1,9 @@
+# About the authors {-}
+
+Tiffany Timbers is an Assistant Professor of Teaching in the Department of Statistics and Co-Director for the Master of Data Science program (Vancouver Option) at the University of British Columbia. In these roles she teaches and develops curriculum around the responsible application of Data Science to solve real-world problems. One of her favorite courses she teaches is a graduate course on collaborative software development, which focuses on teaching how to create R and Python packages using modern tools and workflows.
+
+
+Trevor Campbell is an Assistant Professor in the Department of Statistics at the University of British Columbia. His research focuses on automated, scalable Bayesian inference algorithms, Bayesian nonparametrics, streaming data, and Bayesian theory. He was previously a postdoctoral associate advised by Tamara Broderick in the Computer Science and Artificial Intelligence Laboratory (CSAIL) and Institute for Data, Systems, and Society (IDSS) at MIT, a Ph.D. candidate under Jonathan How in the Laboratory for Information and Decision Systems (LIDS) at MIT, and before that he was in the Engineering Science program at the University of Toronto.
+
+
+Melissa Lee is an Assistant Professor of Teaching in the Department of Statistics at the University of British Columbia. She teaches and develops curriculum for undergraduate statistics and data science courses. Her work focuses on student-centered approaches to teaching, developing and assessing open educational resources, and promoting equity, diversity, and inclusion initiatives.

acknowledgements.Rmd

@@ -0,0 +1,2 @@
+# Script to generate HTML book
+docker run --rm -m 5g -v $(pwd):/home/rstudio/introduction-to-datascience ubcdsci/intro-to-ds:v0.12.0 /bin/bash -c "cd /home/rstudio/introduction-to-datascience; Rscript _build_html.r"

authors.Rmd

@@ -0,0 +1,46 @@
+# Script to generate PDF book
+
+# Copy files
+cp references.bib pdf/
+cp preface-text.Rmd pdf/
+cp intro.Rmd pdf/
+cp reading.Rmd pdf/
+cp wrangling.Rmd pdf/
+cp viz.Rmd pdf/
+cp classification1.Rmd pdf/
+cp classification2.Rmd pdf/
+cp regression1.Rmd pdf/
+cp regression2.Rmd pdf/
+cp clustering.Rmd pdf/
+cp inference.Rmd pdf/
+cp jupyter.Rmd pdf/
+cp version-control.Rmd pdf/
+cp setup.Rmd pdf/
+cp references.Rmd pdf/
+cp printindex.tex pdf/
+cp -r data/ pdf/data
+cp -r img/ pdf/img
+
+# Build the book with bookdown
+docker run --rm -m 5g -v $(pwd):/home/rstudio/introduction-to-datascience ubcdsci/intro-to-ds:v0.12.0 /bin/bash -c "cd /home/rstudio/introduction-to-datascience/pdf; Rscript _build_pdf.r"
+
+# clean files in pdf dir
+rm -rf pdf/references.bib
+rm -rf pdf/preface-text.Rmd 
+rm -rf pdf/intro.Rmd 
+rm -rf pdf/reading.Rmd 
+rm -rf pdf/wrangling.Rmd 
+rm -rf pdf/viz.Rmd 
+rm -rf pdf/classification1.Rmd 
+rm -rf pdf/classification2.Rmd 
+rm -rf pdf/regression1.Rmd 
+rm -rf pdf/regression2.Rmd 
+rm -rf pdf/clustering.Rmd 
+rm -rf pdf/inference.Rmd 
+rm -rf pdf/jupyter.Rmd 
+rm -rf pdf/version-control.Rmd 
+rm -rf pdf/setup.Rmd 
+rm -rf pdf/references.Rmd 
+rm -rf pdf/printindex.tex
+rm -rf pdf/data pdf/img
+