RBIF111MarkdownIntroduction

Okay, in this video, we're going to cover some aspects of our markdown and how to create markdown files in our studio. So, what you see on the screen here is, on the left-hand side, you see a, uh, I have a folder here, it's just "new folder," and saved in that folder, I have a markdown file. This case, it's just the "markdown example" that we're using in this course. Now, all markdown files end with an .rmd ending to them, and so that designates them as a markdown file.

Now, on the right-hand side of the screen here, what you see is an open R studio session, and in this session, I have that same markdown file loaded. So, you can see "6r markdown example.rmd" is here, and that corresponds to the markdown file shown in this folder here.

Now, to take a step back, if you wanted to load a markdown file or create a new one, alls you need to do is click on this plus button to create a new file, and then click on "R Markdown" shown here. When you do that, it'll prompt you to enter a title, you'll put your name in here as the author, whoever you'd like the author to be, and then you'd select a primary output format that's either an HTML, PDF, or Word document. Um, and then after that, you click "OK."

There are a couple of other different types of files you create. You can click on "Presentation" in this case, so we create slides, create PowerPoint slides, PDF slides, HTML slides, and so on and so forth. Um, or you can actually create a "Shiny" document. Um, and we won't be using any of these extra features within this course. The one that you'll primarily be using is this, this "Document" um designation shown here. So, if we just use it as the HTML file as recommended, then, then that should be good enough, and then we'll click "OK."

And here, um, what happens is that a markdown file is automatically opened. And so, you notice there's some structure to the markdown file. In the top here, there's a little bit of information about how this markdown file is put together, and I'll go over that in a little bit more detail in a minute. But for now, what you see is that you have the title of the slide that we created, as well as the name and the date. Um, this would be the date that's entered, um, the time that the document is run, and then the output. In this case, we selected "HTML document," but it could also have been a PDF document. And then there's a setup chunk, and you can include various options in this setup chunk. And then after that, there's some information about this markdown file. Um, there are some different functionalities that can be utilized. Um, so let me get, get into that here in this, this example here.

So, in this example that I have put together for, for you guys, I have a little bit more information on, um, in, in this setup portion of the document, um, such that, um, it still has a title, still has the author, and we have the date. In this case, it just entered the last update, and then include the style of format in which we want to, um, present the date in the format of the document, and then the output. First comes the HTML document, and I've included a number of additional arguments here. In this case, the TOC stands for Table of Contents, um, and then some different aspects of the table of contents, and then we want to include figure captions, and then also in this particular, um, type of document, we can include, um, code folding, hiding, or, or showing, displaying. And I'll get into that here in a second. And then, uh, we can also number the sections for each, uh, each code chunk. And then, uh, down below this HTML document, the first one would be the default, first line indicating HTML document, default to actually create the HTML document, it's knitted together. The second one would be a PDF document. Now, here I've shown that "table of contents is true," although if you're going to knit a PDF document, you can't include a table of contents in the PDF document. It'll fail at the time because it doesn't have the, the HTML, um, support to be able to support a table of contents in a PDF document. So, you'd have to comment, um, uh, this information out in order to actually knit this, this document in a PDF format. And then there's just some, um, additional information here, um, about the, the document. You can include various aspects of text, um, within this, this document called a vignette. Also, you can change the font size. This would be the default font size. And then, um, then we're going to, you know, edit this and export it to the console. And there's different aspects of style that can be, um, uh, created here in this section of the markdown document.

So, um, this would be, say, um, a code chunk, a code that's section of code that's designated here. And within those, those two brackets is, um, greater than or less than sign style, and then slash style ending here. We can include additional information about how we want the text to be configured. So, in this case, what I'm doing is I'm just setting up the text to justify to the left-hand side of the screen and right-hand side of the screen to make it kind of square when the document is actually knitted together. Okay, so in this section up here, this is about the setup of the markdown document.

Okay, now down below, um, what we're showing is some different functionalities of the document. So, if I include a comment sign here, that would create a large header. Sign, and I'll go into this in a little bit more detail in a minute after I knit the document together. If, if I have a double comment sign, then that would have a smaller header. If I have a triple comment sign, that'll have a smaller header, and a quadruple, uh, comment sign, that would create even a smaller header. And then I just included a header one here again, um, for illustration purposes. After I knit this document together, if you want to create a list, you just use this, uh, dash sign here, and you can just have list element one, list element two, list element three, so on and so forth. You want to create italics, it's just a star symbol, and then whatever you want to write, and then another star symbol, and that'll italicize that portion of text. This break, this, um, this break symbol that you see here, that's so that this next line here will start on the next line when you knit it together, as opposed to moving this portion of the text up next to the italics, um, text shown here.

So, then I just, um, show you an illustration of how to create bold. In this case, the, um, in order to create a bold symbol, you just have two star signs, and then in between the, the two sections of two star signs, whatever text is in between those two, um, double star signs would be bolded. If you want to emphasize some text, that would, you just use this backtick, uh, mark, um, that's usually located in the upper left-hand corner of a keyboard, and then write whatever you'd like to write, and then, uh, create this backtick mark again, and then notice that this text is highlighted in blue, and whatever that highlighted section would be would be sort of highlighted and emphasized. For those of you who are familiar with LaTeX, if you wanted to add a formula, and you wanted it to be centered in the middle of the page, just use a double dollar sign, and then what's ever is encased in between these two double dollar signs would be, uh, included in a LaTeX format in the center of the page. If you wanted to include that inline within the text, then you just use a single dollar sign shown here.

So, now within this document, one of the nice aspects of these markdown documents is that you can write text and include code, um, within this document together. And so, whatever you write, um, whatever you write, you know, within this document will be rendered, uh, automatically, um, as a normal document. Now, if you want to render some code, you can. The arguments for, for indicating a section of the document is, is, is code that you want to execute, is using these double, these backtick marks. Put three of them in a row, then include curly braces, type R, and then comma, and there's a bunch of arguments, and then close the curly braces, and then further on down the road, you include, uh, three double tick marks again. Then notice that this section of the document here is highlighted in a light gray color, and that's because this section of the document is indicated as actually being, um, executable code that'll be executing.

Now, within these code chunks, you could name them. So, for example, I'll just call this "code chunk name one," or you can also leave them unnamed, as shown here, um, and in which case, there's nothing after the R and before the comma. Then after the comma, designate, oh, and one other thing is that all the, the code chunks have to have a unique name if you choose to include a name here. If two code chunks have the same name, that will generate an error, and, um, the document actually won't knit or create the final HTML document.

Okay, so then after the comma sign with R, there's a bunch of arguments you can include. Um, I've just included the most common ones that I think you'll probably need here, and that's, uh, eval. If you include this, if you, if you create, if you designate this as true, then whatever is in this code chunk will be evaluated. If you want that evaluation to be printed out, you include "true" here. If you would like that to not be displayed in the final markdown file, then you put "false" here. So, let's say you, you wrote some code, and that code executes and prints something out. If you don't want that to be printed out to the final document, then put "echo = false" here. Most of the time, you'll need it to be printed, so the echo would be "true." If there are any messages or warnings that are generated in the code itself, you can turn those off. So, you say "message = false" here, "warning = false" here. If you, if you switch those to true, then anything that is, um, any code that generates a warning within this code chunk would actually be printed out in the, in the final knitted version of this markdown file.

Then another argument that's more specific to this document is this "class.source = f-show." And the reason why I've included that is because up here in our settings about this document, we've included a table of contents and we've included a code, a code folding designation here. And so, um, so what we're, what we're designating up here in this portion of, of the document is the option to actually be able to generate a button to show the code or, or not show the code at the same time. And I'll get into that in a little bit more detail after we knit this document together. Um, so then the, the next portion, next arguments would be the "fig.height" and the "fig.width." Change the numbers that are associated with these, it'll change the actual height and width of any figures that are generated from this, uh, code. And then the "results," obviously, we want to show them. And if we want to "cache" this code chunk, it would save a small folder in our directory over here in which the results of this were cached in case there was a long run time and we didn't want to run that, that over and over and over again. This case, we'll just say it's "false" because we don't want to cache the results.

Okay, and then down here, so, um, the next thing is I want to point out is, um, when you're, when you're writing code in these, don't include any "install packages" arguments, um, within the, the file itself. If you do that, it'll oftentimes generate an error. So, all the packages that you're going to use that, that are required for a document to be knitted, need to be pre-loaded or, or pre-compiled. Now, you can load packages in, um, in a file, and that's okay. You just can't, you just can't install them.

Okay, so then I just give you an example here. I just print out the numbers one to four, and then I also plot one to four in this separate code chunk.

Now, once you, once you configure this document and you're ready to actually knit it together, there's a couple ways to do that. One is that you could execute, um, this line of code, um, within the, the console itself. Um, or another way to do is if you're in R studio is if you scroll up here to the top of the screen and you see that there, there's this "Knit" button here, um, you can, you can click on this down arrow and it'll show "Knit to HTML," or "Knit to PDF," or "Knit to Word," whatever you'd like to do. In this case, the default is to an HTML document. In fact, it'll fail if I knit a PDF document because of all these additional arguments. Um, so I'm just going to click "Knit" because "Knit to HTML" is the default. And now you'll see what's happening here is, is that this markdown process is rendering. It'll scroll through the entire code chunk, and then what you'll see is that there's an additional HTML file that's created here.

Okay, and then an example of this, and the automatic popup screen comes up here. And so, um, in these additional arguments that we've specified up here, one of them, and this is called a, this is called a Bioc style template, but one of the arguments is including this table of contents. And so, anywhere I've included a, a single, um, hashtag or single comment sign header here, designates a new drop-down menu here. So, here you see header two is shown here. So, if I click on header two, it'll scroll down to that section of the document. Click header one here, then what happens is it not only pulls, scrolls to the section of the document which header one starts, but it'll also list additional headers that are included underneath this, this document, and you can scroll to those headers as, as needed.

Okay, now the next thing that you see is the, the list elements. You see those bullet points shown here. We see the italics, the bold, and that emphasized, um, um, designations or styles of writing, um, shown here. You can add, we see that the formula was actually added to the center of the page. We designated this double dollar sign here, and then you can see that the formula was added inline when you use, when we use the single dollar sign shown here.

Now, within this code chunk, um, as I was indicating earlier, when we, so "class.source = fold-show," what that indicates is that instead of having this actually shown, you can set it up to to hide it. Now, by by designating "fold-show" here, what we're doing is we're showing this code. But if you designated "fold-hide" here, then, um, when you knitted the document, it would not show that portion of code, and you would simply need to click on this button here in order to be able to see the code. Most of the time, we're knitting documents, though, I like to show the code. I think it makes it nice and manageable and, and easy to, to read and understand. So, we have these executable sort of buttons here that allow us to, to show and, and hide the code.

Now, what you'll notice here is that in the code chunk that I've, I've included some code in, we see that although this is included in one code chunk, um, the documents that are, the or the results that are printed out to this knitted file are done so in order. So, you see this "one to four" um section of code that's, that's automatically printed is shown here, and it has its own hide and, and show, um, button. Then the next portion of code that's printed out is shown here, and also here, and it has its own separate, um, windows. If I did not print this "one to four" out to the screen, then obviously there would only be one, um, um, section of code, um, designation shown in the markdown document, as is shown up here in this first, um, knitted example. You have any results that are, um, also rendered to the screen, any graphs that are shown here. And again, you can change the figure width and height of these figures by changing these designations shown here, and that "fig.height" and "fig.width" um arguments.

Okay, so I think that should give you guys a pretty good rundown of how to utilize, um, markdowns. Um, feel, feel free to explore this as, as you would like. There's a wealth of information about markdown documents online. All right, thanks for your time.