 I believe you can answer your own data analysis questions. Do you? You should. Stick around for another episode of Code Club. I'm your host, Pat Schloss, and my goal is to help you to grow in confidence to ask and answer questions about the world around us using data. A text file is just that, a file with only text. Thinking about a document you might write in Microsoft Word, well, there's the text, but there's also formatting, fonts, layouts, and more. A text file is only the text. Often that's limiting because some amount of formatting is actually helpful to help us organize our text. In today's episode, we'll learn how to use a language called Markdown to apply light formatting to our readme and other text files. You may have noticed that our readme files are actually called readme.md, that md extension is short for markdown. Some people prefer to use markdown as the extension. Markdown may not seem like a big deal right now, but as we proceed with this project, we'll see how we can blend code that we want executed with text using a tool called our Markdown. In this episode, we'll also introduce a new text editor as an alternative to Nano which is called Atom. Atom is developed to be compatible with GitHub and has the ability to show us what our Markdown formatting would look like when viewed on GitHub. Today's episode may not seem like it's advancing us very far towards answering our question of how inter and intra genomic variation affects the ability to interpret Amplicon sequence variants or ASVs, but it is a significant departure from how most people approach documenting their work. Please take the time to watch today's episode. Follow along on your own computer and attempt the exercises. Don't worry if you're not sure how to solve the exercises at the end, I'll provide solutions. The notes below this video is a link to a blog post for today's episode that includes installation instructions, reference notes, and links. They are a supplement to the material in the video. Don't forget to like and subscribe the Ruffimona's channel and click on the bell icon when you subscribe so that you're notified when the next episode is released. So we're here at our Issue Tracker and as you can see we currently have these two issues lingering. We're not going to work on them today. Although we will see perhaps how we could improve the formatting of our resource list. But I'm going to open up a new issue and this will be Issue 7, I believe. And what I'm going to put in here is Format, Read Me, Files to make use of Markdown Formatting. And I think that's pretty self-explanatory. I don't know that we need to really put a comment in here. But what I would like to do is maybe use this space to illustrate a few different topics with Markdown. And so again, Markdown provides a very light level of formatting to our code so that it's still text but we can use these different types of characters and this different formatting syntax to give it some more structure and some basic formatting, okay? So the first thing to think about are headings. And so we can define a heading in Markdown with a pound. So we can say pound, this is a top level heading. We can use two pounds to say this is a second level heading and then this is a third. Okay, I think there's something like six or seven different levels that you can use. Now, I'm doing this here in this issue tracker because what I'm writing here is Markdown. Now, if I click on the preview tab, I can see what these different heading levels look like, okay? Excellent. Beyond headings, another useful tool is to be able to bold and italicize our text. So we could say, I like learning about Markdown. I will try to write my next conference abstract in Markdown, okay? And so maybe I'll put like in bold and so to put things in bold, we use two stars around the word around the text. So again, if I go to preview, I see that like is now bolded. Again, like I said, I could put a phrase inside those stars, look at preview and see like learning is now bolded. I can italicize something with a single star. And so you can see now that Markdown is italicized. Well, I'll put, I can bold and italicize with three, right? So you can think of this as nesting a bold and set it inside of an italics. And so we could say it next conference is now bolded and italicized. And so the point isn't so much what it renders like here in the issue tracker, but it's a level of emphasis, right? So if you have one star, that's like light emphasis, like italics, right? Two stars is bolded. Three stars, well, that's really important. That's bold and italics. And again, you can read this and it's still text. What you're using to denote emphasis isn't really obstructive, right? It's not in the way. And so you could read this and it will look nice. What we have to go on top of that then is stuff like GitHub and other tools that take that Markdown and convert it to, in this case, like HTML output, but you can also output it to Microsoft Word or to a PDF. And we'll talk about that in the future. So another useful tool would be to include links. And so I'll write the sentence, GitHub has its own flavor of Markdown called GitHub Flavored Markdown. So Markdown is fairly simple at its core, but different flavors of Markdown add different features. And so what I'm going to do is I'm going to put square brackets around GitHub Flavored Markdown and then an open close parentheses. So square brackets and in that is the text. And then what goes in the parentheses actually will be the address of the link that we want to put in there. And so what I'm going to do is open up a new browser and I'll do GitHub Flavored Markdown. I'll Google that. And the first link is the spec. That's not what I want. I want this one that's guides.github.com Mastering Markdown. And so this is a nice cheat sheet that shows you different things that you can do with Markdown inside of GitHub. And for this example of looking at links, I'm going to copy that, put that into the parentheses. So now GitHub Flavored Markdown, as you can see in the bottom left of my screen here, now has that link that it would then go to and it would open up Mastering Markdown. Very good. So again, we're still writing out this issue as it were. So that's a link. So we've looked at headings, emphasis, and links. We can also make lists. So a few of my things. And so I can make a list, an unordered list, using stars, so like a star and a space. And that star needs to be the first character of the line. And so I'll say favorite things. I'll say Chicago Cubs. I guess I should put my kids first, right? My family. Don't tell them I didn't think about them before the Cubs. Microbiology, Sheep, okay. So again, you can look at this and see that it is a list, right? That that star is there. Now what GitHub does is it then renders that into a bulleted list, which is pretty slick. This lets an unordered list. I can also make an ordered list. So let me think. Let me put my favorite universities. And my first, I'll put University of Michigan. I get paid to say that. I think that's like a sponsored thing, right? I'll put Cornell University, where I went to undergrad and grad school. I'll put University of Wisconsin. So I did my postdoc and that's pretty good. So if I preview that now, I now see that I have an ordered list. Now something that's pretty slick about this is that I could say, well, perhaps in here I should also put Michigan Tech. That's this hat. That's where my daughter goes to school. So I'll put Michigan Technological University. Now the challenge, the problem with these lists then is that I have to update all the numbers. Well, you don't with Markdown. That you can see that it automatically updated the ordering of the list for me. And in fact, I could make all of these one, oops. Make all of these one, and it would get the ordering right, right? So those are a couple of different types of lists that we can make. You've seen me talk about this before in our readme files or in some of the issue trackers that we've done is that we can format code to look a certain way. And so we could say my home directory is in, and I'll use a back tick tilde. Okay, so single back ticks. And that is the character you don't usually use a lot, but it's above the tab. It's on the same key as the tilde. So if you then look at the preview, you see that that tilde is put into what's called like code format. And whereas this is kind of like an aerial font, this is much more of like a courier monospace font. So that's an inline code. I can also make a code chunk by using a pair of three back ticks. And so in here, I can then put code and it will be then rendered looking like a code chunk. And so you can see here, there's this gray box that kind of tells you that code is coming, right? So I could say first name, pat, last name, Schloss, and then name. I could then do paste, first name, last name. And so because it's in these sets of back ticks, it tells me that this is a code chunk, right? Now, when it renders it, it renders that as code and it makes it nicely formatted, okay? So if you go to this link for GitHub Flavored Markdown, you'll see there's other things you can do with Markdown. Like I've said before, and what I'm showing you is 95% of what I use are thinking about headings, emphasis, links, unordered lists, ordered lists, code chunks inline as well as code chunks. You could also insert pictures. There's a lot you can do with this. And again, the point is that you're writing it as text and it's really stripped down and that you could read this, right? And the formatting doesn't get in the way. Your emphasis isn't on the formatting or the spacing or things like that. Your emphasis is writing text, okay? So we're going to format our readme files now to make use of this Markdown formatting. And this will give us an opportunity to practice with these different aspects of Markdown. And so again, this is issue seven. So I'm in my home directory. I'll change to my project root directory to get status to make sure I'm on the master branch. Everything's up to date. Do an LS, make sure everything looks good. Last time we talked about git log. So I can see the last commit message was to download files using the command line. It was a great episode. And so now we're going to create a new branch. So I'll do git branch issue seven. And I see I've created that issue seven. I'll do then get checkout issue seven. It says I've switched to the branch double check. I'm on branch issue seven, okay? Very good. So what we'd like to do now is to edit a readme file to put it into Markdown. Now again, I could do nano readme.md and this shows me my file. And I could edit in here but it's going to be pretty tedious, right? So what I'm going to do instead is I've got Atom installed in the blog post that accompanies today's video. There's instructions on installing Atom for Windows and Mac. There's a link to get there. So if you haven't done that already, go ahead and pause the video, go install it and then press play. So I can open Atom for my project directory tree by typing Atom and then a space period. And this will open up Atom and you'll see my directory tree over here on the left. I can close these different directories. And so this is effectively what my project root directory looks like. If I open up the readme.md file, I see my text. And so this looks a lot like, say, Microsoft Word, right? It's very clean and it's text. And I can highlight a word and delete it or whatever. It's much easier to work with and say something like Nano. One of the things that comes with Atom are a series of packages. I guess it doesn't come with them, but they're extensions onto Atom. Atom comes with a lot of features, but if you come up to this packages menu, you'll notice that I might have a bunch of different packages that you don't have. That's fine. The main package we're interested in is Markdown Preview. So there's a keystroke on a Mac. It's Control-Shift-M. And you can also toggle GitHub style. So if we go ahead and click on that, that creates a separate window. And I noticed that when I started this, that you saw that it had an error message. I'm sorry I didn't comment on it when I did that. What I did, I came over here and I just hit, I did Command-S to save my file and that seemed to resolve the problem over here. So again, I'm looking at my text and it's going to be updated on the right as GitHub would render it. And I could actually do Markdown Preview, toggle GitHub style. It's a little bit different. I don't know that makes a big difference. So what I'm gonna do is I'm gonna add some Markdown formatting to this. Read me to write it in Markdown, okay? So I'm gonna make the title of my project a top level heading with a single pound. And this seems to be going on a separate line. So I'm gonna go ahead and clean this up a little bit. And you'll notice that Adam actually is putting my top level heading in red text, which is pretty nice. It's also putting in a horizontal line underneath, which is nice. For author, I'm gonna put that in bold and that's good. And so then this is the description developed over a series of Code Club episodes led by Patch Loss, blah, blah, blah, blah. That's pretty nice. So one thing you'll notice is that over here, this text is written as like three different lines, whereas over here, it's a single line. And so Markdown ignores white space. If I were to put two spaces at the end of a line, so you see where my cursor is after answer, if I put two spaces in, you'll notice that it put an important question, blah, blah, blah, on a separate line. I could also force the line break by putting in an extra line there, okay? So I'm gonna make this all one line, makes it look nice. Dependencies, you can see here that it's putting dependencies and mother on one line because again, we don't have a line break imposed. And so we can add that again by putting two spaces after dependencies. That works. I can then also put a pound, I'm sorry, a star at the front of that line to start a listing of dependencies. I can also make a link to this and with the square braces around the text that I wanna show and then the curved parentheses with the URL for where it's gonna go. And I'm going to go to github.com slash mother and it's mother and then, let's see, I've already got a newer release than what I'm working on. I think we found some bugs along the way. If I go to releases and I'm talking about 44.1, I can click on this tag over here, copy that link, come back to Adam, put that in there, save it. And now I've got a link, okay? Maybe CodeClub, I'll put that in italics. So again, we've inserted a decent amount of formatting here. Maybe dependencies I'll put on a third level heading. It seems that the second level and the first level, they put a line underneath it. So I'll make that three, what's four look like? You can see as I add pound signs, it gets smaller and smaller. So I'll make it a third level heading. And as we go through the project, we'll flesh this out some more, very good. So again, what we've done is we've applied some light formatting to our readme file. We haven't really added any text. The only text I added was the URL to this version of mother. So again, markdown is meant to be a simple way to add formatting to a text file. So that when you read the text file, the formatting isn't, it's not obstructive. It's not in the way, right? So I'm gonna have you work through a few exercises. The first is to look at the GitHub-flavored markdown reference materials that we included in our issue and recreate the sentence. And you'll notice that this sentence has a strike through of Microsoft Word. Next, I want you to create a checklist written in GitHub-flavored markdown that actually has checkboxes. This could be really useful for an issue, right? So if you have an issue where you have to do five different things, then maybe you wanna have a checkbox for each of those five things you have to do for that issue. Well, with GitHub-flavored markdown, you can do that. Finally, I want you to finish and push issue seven of your version to your repository on GitHub. So I want you to go back to the readme files for data raw and data references to clean those up a little bit. You don't have to do a lot of formatting, but just clean those up a little bit so that they look nice. Maybe the code should go inside of a code chunk. So go ahead, pause the video, go work on those exercises. When you're done, press play and we'll come back and I'll show you how I would work through those exercises. So for the first exercise, I have a sentence that I want you to format. And so the sentence is I will write my documents in Microsoft Word Markdown. And Microsoft Word should be struct out. Again, if we go to this link for GitHub-flavored markdown, we can scroll through here to look at the different things. We've talked about headers, emphasis, different types of lists. We didn't talk about images, links. You can make block quotes, inline code, code chunks. There's some stuff you can do here with different languages. Task lists, we'll come back to this in a minute. You can make tables, all sorts of great stuff. Strike through, any word or phrase wrapped with two Tildas will appear crossed out. Very good. So if I come back here, I can put two Tildas around Microsoft Word. And if I preview, now it's been checked off. It's been crossed off. So for the second question, it was to make a checklist of things to work on. So we'll say, for this issue, we need to clean up three readme.md files. Because it's a file, if something's a file, I wanna put it in inline code. But I'm gonna make a checklist. And so as we saw from this mastering markdown, where was it? This task list, that if we use a hyphen space, open bracket, space, close bracket, that that will create a task list. So hyphen, bracket, and I have a space between the two brackets. I'll say readme.md, I'll do data, raw, readme.md, data references, readme.md. And I can preview that. And I can see that I've got these checklists. So we already did this readme one. So when we submit that comment, we can then check it off. Now, something I wanna try is, can we put this as inline code? And sure enough, we can. And so I'll go ahead and put these as inline code. Preview it to make sure it looks good. And then comment. So we've already done this readme.md. And something you can notice also perhaps, so you can change the order of these things. That's pretty slick. So we're gonna now go through issue seven and clean up the data, raw, readme and the data references, readme. And I will go to data, raw, readme. And maybe at the top here, I'll put readme as the title and I'll close this. And so this is the preview for readme.md. So again, if I come here, if I find my cursor in my readme.md file, I do control shift M that then updates what is seen on the right side. And I'll change this to say update, uploaded file, obtained files from the RNDB. And I will then put that into square braces and then parentheses to make it a link. And you can say, you can see that. And so I will then say, gonna edit this just a little bit to say version 5.6 released in 2019. So we automated up downloading and extracting the TSV file with Wget and Unzip. I'm gonna say RRNDB files with that. And then I'll go ahead and put this into a code block like so, right? So it doesn't have to be anything fancy that with our formatting. But again, this then formats it into a nice code block that makes it easier to read. Excellent. So I'm gonna save that and then we'll go to data references and the readme there. We'll go ahead and close this out. And again, I'm gonna make a top level heading readme. And I will then save that. And over here, or I'll do control shift M to get that. And I will get rid of that. And I'm gonna change this to go to the mother wiki page. And I will do mother.org wiki. And I know that the file is silver reference files. Mother.org wiki silver underscore reference underscore files, I'll copy that. I will then come into here and plop that URL down. So I've got the link there. And then I can again format this as code block. And you can kind of see on the right side then how it gets converted into this code block. I'll go ahead and put the directory that it's getting saved to as an inline code as well as these different commands. If something is a command or a program name or a directory or it's code, I always put that to format those things as code. Very good. So that's a very simple formatting of this readme. Makes it look nice. And I think we're closed with this issue. I'm going to remember to include closes issue seven in my commit message today. So get status. We've changed these three readme files. I'll do get add readme.md data raw readme.md data references readme.md. It's going to complain as we've seen before because we're ignoring things in data. So I'll do add space hyphen f get status. Those are ready to be committed. And I can do get commit dash m apply markdown formatting. Closes number seven. Get status. I'm on my branch. And I'll do get check out master. Master. Get merge issues seven. Great. It's brought those over. And now I'm on again. I'm on the master branch. And if I do nano readme, I see that I've got all my nice formatting. Very good. And I can now do get push. And if I come back to my issue tracker, I see that I closed this in ACD 9053. And as I mentioned in the previous episode where I forgot to include the issue number in my commit message, if I come back to my commit up here where I did get commit issue seven, ACD 9053. That's a special identifier of the commit message. When you're doing it on your computer, you're going to get a different identifier than what I get. That's something called a SHA code, S-H-A. And again, we had done raw references. We cleared the issue. So again, we come back to our issue tracker and we're back to these two issues that kind of persist as we go along. Thanks again for joining me for this week's episode of Code Club. Be sure that you spend time going through the exercises on your own to help reinforce your new skills. Even better, it would be for you to take the ideas we've worked through today and think about how they relate to your current projects. Perhaps you could experiment with taking notes using Markdown rather than something like Microsoft Word. You might also look at the preference window for Adam and see how you can customize its appearance. I'd love to see what you're adapting that I have covered in this and other Code Club episodes into your own work. Also, please let me know what types of data analysis questions you have and I'll do my best to answer them in a future Code Club. It'd be great to see more of this type of feedback in the comments below each of our videos. Be sure to tell your friends about Code Club and to like this video, subscribe to the Riffimona's channel and click on the bell so you know when the next Code Club video is released. Keep practicing and we'll see you next time for another episode of Code Club.