In markanewman/stormdown: PhD dissertation template for Harrisburg University in R Markdown

packages <- c(
  'knitr',
  'kableExtra',
  'devtools',
  'dplyr',
  'ggpubr')
packages_unloaded <- c(
  'rmarkdown',
  'pagedown',
  'bookdown')
lapply(packages, require, character.only = T)

knitr::write_bib(c(packages, packages_unloaded), 'packages.bib')
knitr::knit_hooks$set(inline = function(x) { prettyNum(x, big.mark = ',') })
knitr::opts_chunk$set(echo = F, fig.align = 'center')

Introduction {#introduction .chapter}

Explain your work as a whole.

This document is HUGE

Dissertations are long. This is the nature of the beast. However, this single file can be split up into many files using child documents. I recommend breaking the document into children at the start of the process and at the chapter level.

I need help

Try the references below. They were how I learned this and should help you as well.

1. R Markdown: The Definitive Guide [@rmarkdown2018]
2. R Markdown Cookbook [@rmarkdown2020]
3. bookdown: Authoring Books and Technical Documents with R Markdown [@bookdown2016]
4. pagedown: Paginate the HTML Output of R Markdown with CSS for Print [@R-pagedown]
5. $\TeX$ symbols

The rest of the dissertation portfolio is outlined as follows. A review of the overall literature is presented in Chapter \@ref(literature-review). Three personal works are then presented following the normal layout.

• Title of work A. Chapter \@ref(a-title) Sections \@ref(a-introduction) through \@ref(a-conclusion)
• Title of work B. Chapter \@ref(b-title) Sections \@ref(b-introduction) through \@ref(b-conclusion)
• Title of work C. Chapter \@ref(c-title) Sections \@ref(c-introduction) through \@ref(c-conclusion)

Chapter \@ref(conclusion) concludes the dissertation portfolio and provides insights to how the three works fit together as a cohesive whole.

Literature Review {#literature-review .chapter}

Here is a brief introduction into using R Markdown. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. R Markdown provides the flexibility of Markdown with the implementation of R input and output. For more details on using R Markdown see http://rmarkdown.rstudio.com.

Be careful with your spacing in Markdown documents. While whitespace largely is ignored, it does at times give Markdown signals as to how to proceed. As a habit, try to keep everything left aligned whenever possible, especially as you type a new paragraph. In other words, there is no need to indent basic text in the Rmd document (in fact, it might cause your text to do funny things if you do).

Numbers

big_num <- 1234567890

This is an inline number: r big_num

Lists

It's easy to create a list. It can be unordered like

• Item 1
• Item 2

or it can be ordered like

1. Item 1
2. Item 2

Notice that I intentionally mislabeled Item 2 as number 4. Markdown automatically figures this out! You can put any numbers in the list and it will create the list. Check it out below.

To create a sublist, just indent the values a bit (at least four spaces or a tab). (Here's one case where indentation is key!)

1. Item 1
2. Item 2
3. Item 3
   • Item 3a
   • Item 3b

Line breaks

Make sure to add white space between lines if you'd like to start a new paragraph.

The correct way:

Here is the first sentence. Here is another sentence. Here is the last sentence to end the paragraph.

This should be a new paragraph.

Scholary Work A {#a-title .chapter}

Introduction {#a-introduction}

Welcome to the R Markdown dissertation template. This template is based on (and in many places copied directly from) the HU LaTeX template, but hopefully it will provide a nicer interface for those that have never used TeX or LaTeX before. Using R Markdown will also allow you to easily keep track of your analyses in R chunks of code, with the resulting plots and output included as well. The hope is this R Markdown template gets you in the habit of doing reproducible research, which benefits you long-term as a researcher, but also will greatly help anyone that is trying to reproduce or build onto your results down the road.

Hopefully, you won't have much of a learning period to go through and you will reap the benefits of a nicely formatted dissertation. The use of LaTeX in combination with Markdown is more consistent than the output of a word processor, much less prone to corruption or crashing, and the resulting file is smaller than a Word file. While you may have never had problems using Word in the past, your dissertation is likely going to be at least twice as large and complex as anything you've written before, taxing Word's capabilities. After working with Markdown and R together for a few weeks, we are confident this will be your reporting style of choice going forward.

Related Works {#a-related-works}

R chunks {#a-r-chunks}

When you click the Knit button above a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this (cars is a built-in R dataset):

summary(cars)

Inline code

If you'd like to put the results of your analysis directly into your discussion, add inline code like this:

The cos of $2 \pi$ is r cos(2*pi).

Another example would be the direct calculation of the standard deviation:

The standard deviation of speed in cars is r sd(cars$speed).

One last neat feature is the use of the ifelse conditional statement which can be used to output text depending on the result of an R calculation:

r ifelse(sd(cars$speed) < 6, "The standard deviation is less than 6.", "The standard deviation is equal to or greater than 6.")

Note the use of > here, which signifies a quotation environment that will be indented.

As you see with $2 \pi$ above, mathematics can be added by surrounding the mathematical text with dollar signs. More examples of this are in [Mathematics and Science] if you uncomment the code in [Math].

Method and Materials {#a-method-and-materials}

Math

$\TeX$ is the best way to typeset mathematics. Donald Knuth designed $\TeX$ when he got frustrated at how long it was taking the typesetters to finish his book, which contained a lot of mathematics. One nice feature of R Markdown is its ability to read LaTeX code directly.

Be very careful with your formulas. $\TeX$ is heavily dependent on symbols and will give unhelpful errors when doing a final knit. Just because it renders up real nicely in RStudio does not mean it will compile to PDF. "Undefined control sequence" and "" are good examples of $\TeX$ going awry. Consult this handy reference guide for help.

$$ \sum_{j=1}^n (\delta\theta_j)^2 \leq \frac{\beta_i^2}{\delta_i^2 + \rho_i^2} \left[ 2\rho_i^2 + \frac{\delta_i^2\beta_i^2}{\delta_i^2 + \rho_i^2} \right] \equiv \omega_i^2 $$

Results {#a-results}

Tables {#a-tables}

By far the easiest way to present tables in your thesis is to store the contents of the table in a CSV or Excel file, then read that file in to your R Markdown document as a data frame. Then you can style the table with the kable function, or functions in the kableExtra package. NOTE: there is currently a known issue with kableExtra and pagedown. Please be advised to not use the fancy formatting options yet.

In addition to the tables that can be automatically generated from a data frame in R that you saw in [R Markdown Basics] using the kable function, you can also create tables using pandoc. (More information is available at http://pandoc.org/README.html#tables.) This might be useful if you don't have values specifically stored in R, but you'd like to display them in table form. Below is an example. Pay careful attention to the alignment in the table and hyphens to create the rows and columns. Generally I don't recommend this approach of typing the table directly into your R Markdown document.

---

Factors Correlation between Parents & Child Inherited

---

Education -0.49 Yes

Socio-Economic Status 0.28 Slight

Income 0.08 No

Family Size 0.18 Slight

Occupational Prestige 0.21 Slight

---

Table: (#tab:inher) Correlation of Inheritance Factors for Parents and Child

We can also create a link to the table by doing the following: Table \@ref(tab:inher). If you go back to [Loading and exploring data] and look at the kable table, we can create a reference to this max delays table too: Table \@ref(tab:a-maxdelays). The addition of the (\#tab:inher) option to the end of the table caption allows us to then make a reference to Table \@ref(tab:label). Note that this reference could appear anywhere throughout the document after the table has appeared.

\clearpage

Conclusion {#a-conclusion}

And here's some other random info: the first paragraph after a chapter title or section head shouldn't be indented, because indents are to tell the reader that you're starting a new paragraph. Since that's obvious after a chapter or section title, proper typesetting doesn't add an indent there.

Scholary Work B {#b-title .chapter}

Introduction {#b-introduction}

Why use it?

R Markdown creates a simple and straightforward way to interface with the beauty of LaTeX. Packages have been written in R to work directly with LaTeX to produce nicely formatting tables and paragraphs. In addition to creating a user friendly interface to LaTeX, R Markdown also allows you to read in your data, to analyze it and to visualize it using R functions, and also to provide the documentation and commentary on the results of your project. Further, it allows for R results to be passed inline to the commentary of your results. You'll see more on this later.

Related Works {#b-related-works}

Including plots

You can also embed plots. For example, here is a way to use the base R graphics package to produce a plot using the built-in pressure dataset:

plot(pressure)

Note that the echo=FALSE parameter was added to the code chunk to prevent printing of the R code that generated the plot. There are plenty of other ways to add chunk options. More information is available at http://yihui.name/knitr/options/.

Another useful chunk option is the setting of cache=TRUE as you see here. If document rendering becomes time consuming due to long computations or plots that are expensive to generate you can use knitr caching to improve performance. Later in this file, you'll see a way to reference plots created in R or external figures.

Method and Materials {#b-method-and-materials}

Math

A matrix:

$$ \det\begin{vmatrix} c_0 & c_1 & c_2 & \ldots & c_n\ c_1 & c_2 & c_3 & \ldots & c_{n+1}\ c_2 & c_3 & c_4 & \ldots & c_{n+2} \ \vdots & \vdots & \vdots & \vdots & \vdots \ c_n & c_{n+1} & c_{n+2} & \ldots & c_{2n} \ \end{vmatrix} < 0 $$

Results {#b-results}

Figures

If your dissertation has a lot of figures, R Markdown might behave better for you than that other word processor. One perk is that it will automatically number the figures accordingly in each chapter. You'll also be able to create a label for each figure, add a caption, and then reference the figure in a way similar to what we saw with tables earlier. If you label your figures, you can move the figures around and R Markdown will automatically adjust the numbering for you. No need for you to remember! So that you don't have to get too far into LaTeX to do this, a couple R functions have been created for you to assist. You'll see their use below.

In the R chunk below, we will load in a picture stored as hu-100px.png in our main directory. We then give it the caption of "HU logo", the label of "hulogo", and specify that this is a figure. Make note of the different R chunk options that are given in the R Markdown file (not shown in the knitted document).

knitr::include_graphics(path = "figure/hu-100px.png")

Here is a reference to the HU logo: Figure \@ref(fig:hulogo). Note the use of the fig: code here. By naming the R chunk that contains the figure, we can then reference that figure later as done in the first sentence here. We can also specify the caption for the figure via the R chunk option fig.cap.

\clearpage

Below we will investigate how to save the output of an R plot and label it in a way similar to that done above. Recall the flights dataset from Chapter \@ref(literature-review). (Note that we've shown a different way to reference a section or chapter here.) We will next explore a bar graph with the mean flight departure delays by airline from Portland for 2014. Note also the use of the scale parameter which is discussed on the next page.

flights <- read.csv("data/flights.csv")
flights %>%
  group_by(carrier) %>%
  summarize(mean_dep_delay = mean(dep_delay)) %>%
  ggbarplot(
    x = 'carrier',
    y = 'mean_dep_delay',
    color = 'carrier') %>%
  ggpar(
    xlab = 'Carrier',
    ylab = 'Mean Delay',
    legend = 'right',
    legend.title = 'Carrier')

Here is a reference to this image: Figure \@ref(fig:delaysboxplot).

A table linking these carrier codes to airline names is available at https://github.com/ismayc/pnwflights14/blob/master/data/airlines.csv.

Conclusion {#b-conclusion}

And here's some other random info: the first paragraph after a chapter title or section head shouldn't be indented, because indents are to tell the reader that you're starting a new paragraph. Since that's obvious after a chapter or section title, proper typesetting doesn't add an indent there.

Scholary Work C {#c-title .chapter}

Introduction {#c-introduction}

Who should use it?

Anyone who needs to use data analysis, math, tables, a lot of figures, complex cross-references, or who just cares about the final appearance of their document should use R Markdown. Of particular use should be anyone in the sciences, but the user-friendly nature of Markdown and its ability to keep track of and easily include figures, automatically generate a table of contents, index, references, table of figures, etc. should make it of great benefit to nearly anyone writing a dissertation project.

Related Works {#c-related-works}

Loading and exploring data

Included in this template is a file called flights.csv. This file includes a subset of the larger dataset of information about all flights that departed from Seattle and Portland in 2014. More information about this dataset and its R package is available at http://github.com/ismayc/pnwflights14. This subset includes only Portland flights and only rows that were complete with no missing values. Merges were also done with the airports and airlines data sets in the pnwflights14 package to get more descriptive airport and airline names.

We can load in this data set using the following command:

flights <- read.csv("data/flights.csv")

The data is now stored in the data frame called flights in R. To get a better feel for the variables included in this dataset we can use a variety of functions. Here we can see the dimensions (rows by columns) and also the names of the columns.

dim(flights)
names(flights)

Another good idea is to take a look at the dataset in table form. With this dataset having more than 50,000 rows, we won't explicitly show the results of the command here. I recommend you enter the command into the Console after you have run the R chunks above to load the data into R.

View(flights)

While not required, it is highly recommended you use the dplyr package to manipulate and summarize your data set as needed. It uses a syntax that is easy to understand using chaining operations. Below I've created a few examples of using dplyr to get information about the Portland flights in 2014. You will also see the use of the ggpubr package, which produces beautiful, high-quality academic visuals.

\clearpage

The example we show here does the following:

• Selects only the carrier_name and arr_delay from the flights dataset and then assigns this subset to a new variable called flights2.
• Using flights2, we determine the largest arrival delay for each of the carriers.

flights2 <-
  flights %>% 
  select(carrier_name, arr_delay)
max_delays <-
  flights2 %>% 
  group_by(carrier_name) %>%
  summarize(max_arr_delay = max(arr_delay, na.rm = TRUE))

A useful function in the knitr package for making nice tables in R Markdown is called kable. It is much easier to use than manually entering values into a table by copying and pasting values into Excel or LaTeX. This again goes to show how nice reproducible documents can be! The caption.short argument is used to include a shorter title to appear in the List of Tables.

max_delays %>%
  kable(
    col.names = c("Airline", "Max Arrival Delay"),
    caption = "Maximum Delays by Airline",
    caption.short = "Max Delays by Airline",
    longtable = TRUE,
    booktabs = TRUE) %>%
  kable_styling()  

The last two options make the table a little easier-to-read.

We can further look into the properties of the largest value here for American Airlines Inc. To do so, we can isolate the row corresponding to the arrival delay of 1539 minutes for American in our original flights dataset.

flights %>% 
  filter(arr_delay == 1539, 
         carrier_name == "American Airlines Inc.") %>%
  select(-c(month, day, carrier, dest_name, hour, 
            minute, carrier_name, arr_delay))

We see that the flight occurred on March 3rd and departed a little after 2 PM on its way to Dallas/Fort Worth. Lastly, we show how we can visualize the arrival delay of all departing flights from Portland on March 3rd against time of departure.

flights %>% 
  filter(month == 3, day == 3) %>%
  ggscatter(
    x = 'dep_time', 
    y = 'arr_delay') %>%
  ggpar(
    xlab = 'Departure Time',
    ylab = 'Arrival Delay')

Additional resources

• Markdown Cheatsheet^markdown
• R Markdown Reference Guide^rmarkdown
• Introduction to dplyr^dplyr
• ggpubr Documentation^ggpubr

Method and Materials {#c-method-and-materials}

Math

Lapidus and Pindar, Numerical Solution of Partial Differential Equations in Science and Engineering. Page 54

$$ \int_t\left{\sum_{j=1}^3 T_j \left(\frac{d\phi_j}{ dt}+k\phi_j\right)-kT_e\right}w_i(t)\ dt=0,v \qquad i=1,2,3. $$

L\&P Galerkin method weighting functions. Page 55

$$ \sum_{j=1}^3 T_j\int_0^1\left{\frac{d\phi_j}{dt} + k\phi_j\right} \phi_i\ dt = \int_{0}^1k\,T_e\phi_idt, \qquad i=1,2,3 $$

Another L\&P (p145)

$$ \int_{-1}^1!\int_{-1}^1!\int_{-1}^1 f\big(\xi,\eta,\zeta\big) = \sum_{k=1}^n\sum_{j=1}^n\sum_{i=1}^n w_i w_j w_k f\big(\xi,\eta,\zeta\big). $$

Another L\&P (p126)

$$ \int_{A_e} (\,\cdot\,) dx dy = \int_{-1}^1!\int_{-1}^1 (\,\cdot\,) \det[J] d\xi d\eta. $$

Results {#c-results}

Footnotes and Endnotes

You might want to footnote something. ^[footnote text] The footnote will be in a smaller font and placed appropriately. Endnotes work in much the same way.

Cross-referencing chapters and sections

The bookdown documentation is an excellent source for learning how to cross-reference in a bookdown project such as a stormdown document. Here we only cover the most common uses for a typical dissertation. If you want something more complex or fancy, please refer to the bookdown documentation and seek help from the developers of that package.

By default, all of your chapter and section headers will get an auto-generated ID label For example, e.g., # Chapter 1 will have an auto-generated ID chapter-1. Note that the ID label is all lower case, and has no spaces. If you have any kind of punctuation in your header, such as a colon (:), it will not appear in the ID label. Then in your text you can reference chapter one in your Rmd file like this: 'as discussed in Chapter \@ref(chapter-1)', which will print as 'as discussed in Chapter 1'

We strongly recommend that you to manually assign ID labels to your chapter header to make it easy to cross-reference.

Tables, Graphics, References, and Labels {#ref-labels}

### Tables, Graphics, References, and Labels {#ref-labels}

The {#ref-labels} part of this header is the ID label. It doesn't show in the output, but is there for us to use for easy cross-referencing, because it can be short, and we don't need to change it elsewhere our document when we update the chapter header. We can use this custom ID label in our Rmd document like this: 'as discussed in Chapter \@ref(ref-labels)', which will print as 'as discussed in Chapter \@ref(ref-labels)'. If you need to show custom text instead of the chapter number, you use this syntax in your Rmd document: see [my chapter about labels](#ref-labels) for more details which will appear as 'see my chapter about labels for more details'

To cross-reference a specific section in the same chapter, we recommend adding a custom ID label to the section header, and using that to cross-reference. For example, earlier in this chapter we have a section on tables and in the Rmd file we see ## Tables {#tables}. We can cross-reference that in the text like this 'as discussed in the section on [tables](#tables)' which will appear as 'as discussed in the above section on tables'

To cross-reference a section in a different chapter we can use the ID label from that section directly. For example, we can write in our Rmd document as discussed in the section on [R code chunks](#a-r-chunks) in Chapter \@ref(literature-review) which will appear as 'as discussed in the section on R code chunks in Chapter \@ref(literature-review)'.

If you prefer to cross-reference by the section number, we can use custom ID labels in our Rmd document. For example, to refer to a section in our first chapter, we can write in the Rmd document: as discussed in section \@ref(a-r-chunks) in Chapter \@ref(literature-review). This will appear with section and chapter numbers like so: as 'as discussed in section \@ref(a-r-chunks) in Chapter \@ref(literature-review)'.

Bibliographies

Of course you will need to cite things, and you will probably accumulate an armful of sources. There are a variety of tools available for creating a bibliography database (stored with the .bib extension). In addition to BibTeX suggested below, you may want to consider using the free and easy-to-use tool called Zotero. Some Zotero documentation is at http://libguides.reed.edu/citation/zotero. In addition, a tutorial is available from Middlebury College at http://sites.middlebury.edu/zoteromiddlebury/.

R Markdown uses pandoc (http://pandoc.org/) to build its bibliographies. One nice caveat of this is that you won't have to do a second compile to load in references as standard LaTeX requires. To cite references in your dissertation (after creating your bibliography database), place the reference name inside square brackets and precede it by the "at" symbol. For example, here's a reference to a book about worrying: [@molina1994]. This molina1994 entry appears in a file called _refrences.bib. This bibliography database file was created by a program called BibTeX. You can call this file something else if you like (look at the YAML header in the index.Rmd file) and, by default, is to placed in the root.

For more information about BibTeX and bibliographies, see (http://web.reed.edu/cis/help/latex/index.html)^[@reedweb2007]. There are three pages on this topic: bibtex (which talks about using BibTeX, at http://web.reed.edu/cis/help/latex/bibtex.html), bibtexstyles (about how to find and use the bibliography style that best suits your needs, at http://web.reed.edu/cis/help/latex/bibtexstyles.html) and bibman (which covers how to make and maintain a bibliography by hand, without BibTeX, at http://web.reed.edu/cis/help/latex/bibman.html). The last page will not be useful unless you have only a few sources.

Tips for Bibliographies

• Like with dissertation formatting, the sooner you start compiling your bibliography for something as large as dissertation, the better.
• The cite key (a citation's label) needs to be unique from the other entries.
• When you have more than one author or editor, you need to separate each author's name by the word "and" e.g. Author = {Noble, Sam and Youngberg, Jessica},.
• Bibliographies made using BibTeX (whether manually or using a manager) accept LaTeX markup, so you can italicize and add symbols as necessary.
• To force capitalization in an article title or where all lowercase is generally used, bracket the capital letter in curly braces.

Anything else?

If you'd like to see examples of other things in this template, please contact us (email [e-mail]) with your suggestions. We love to see people using R Markdown for their dissertations, and are happy to help.

Conclusion {#c-conclusion}

And here's some other random info: the first paragraph after a chapter title or section head shouldn't be indented, because indents are to tell the reader that you're starting a new paragraph. Since that's obvious after a chapter or section title, proper typesetting doesn't add an indent there.

Conclusion {#conclusion .chapter}

How should all your stand alone works be viewed as a whole unique contribution. This should be a more than the sum of its parts excerise.

References {-}

Appendix I: Scholary Work A {#a-appendix .unnumbered}

This first appendix includes all of the extra stuff from your first paper.

Sub section 1 {.unnumbered}

An appendix usually does not include a sub section, but if the original work required mor than 1 appendix, it may be appropriate here too.

Sub section 2 {.unnumbered}

An appendix usually does not include a sub section, but if the original work required mor than 1 appendix, it may be appropriate here too.

Appendix II: Scholary Work B {#b-appendix .unnumbered}

This second appendix includes all of the extra stuff from your second paper.

Appendix III: Scholary Work C {#c-appendix .unnumbered}

This third appendix includes all of the extra stuff from your third paper.

markanewman/stormdown documentation built on Jan. 1, 2021, 9:18 a.m.