cwpk-14-markdown-notebook-file.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "CWPK \\#14: Markdown and Anatomy of a Notebook File\n",
    "==================================================\n",
    "\n",
    "Eventually, You May Need to Know How to Dissect a Notebook Page\n",
    "---------------------------------------------------------------\n",
    "\n",
    "<div style=\"float: left; width: 305px; margin-right: 10px;\">\n",
    "\n",
    "<img src=\"http://kbpedia.org/cwpk-files/cooking-with-kbpedia-305.png\" title=\"Cooking with KBpedia\" width=\"305\" />\n",
    "\n",
    "</div>\n",
    "\n",
    "We discussed in the [**CWPK \\#10**](https://www.mkbergman.com/2337/cwpk-10-installing-a-project-notebook/) installment of this [*Cooking with Python\n",
    "and KBpedia*](https://www.mkbergman.com/cooking-with-python-and-kbpedia/) series the role of\n",
    "[Jupyter Notebook](https://en.wikipedia.org/wiki/Project_Jupyter) pages\n",
    "to document this entire plan. The reason we are using [electronic\n",
    "notebooks](https://en.wikipedia.org/wiki/Notebook_interface) is because,\n",
    "from this point forward, we will be following the discipline of\n",
    "[literate\n",
    "programming](https://en.wikipedia.org/wiki/Literate_programming).\n",
    "Literate programming is a style of coding introduced by [Donald\n",
    "Knuth](https://en.wikipedia.org/wiki/Donald_Knuth) to combine coding\n",
    "statements with language narratives about what the code is doing and how\n",
    "it works. The paradigm, and thus electronic notebooks, is popular with\n",
    "data scientists because activities like [machine\n",
    "learning](https://en.wikipedia.org/wiki/Machine_learning) also require\n",
    "data processing or cleaning and multiple tests with varying parameters\n",
    "in order to dial-in resulting models. The interactive notebook paradigm,\n",
    "combined with the idea of the scientist's lab notebook, is a powerful\n",
    "way to instruct programming and data science.\n",
    "\n",
    "In this installment we will dissect a Jupyter Notebook page and how we\n",
    "write the narrative portions in a [lightweight mark-up\n",
    "language](https://en.wikipedia.org/wiki/Lightweight_markup_language)\n",
    "known as [Markdown](https://en.wikipedia.org/wiki/Markdown). Actually,\n",
    "Markdown is more of a loose affiliation of related formats, with lack of\n",
    "standardization posing some challenges to its use. In the next\n",
    "installment we will provide recipes for keeping your Markdown clean and\n",
    "for integrating notebook pages into your workflows and directory\n",
    "structures.\n",
    "\n",
    "We first showed a Jupyter Notebook page in <span\n",
    "style=\"font-style: italic;\">Figure 5</span> of [**CWPK \\#10**](https://www.mkbergman.com/2337/cwpk-10-installing-a-project-notebook/). Review that\n",
    "installment now, make sure you have a CWPK notebook page (`*.ipynb`)\n",
    "somewhere on your machine, go to the directory where it is stored\n",
    "(remember that needs to be beneath the root directory you set in\n",
    "[**CWPK \\#10**](https://www.mkbergman.com/2337/cwpk-10-installing-a-project-notebook/)), and then bring up a command window. We'll start up Jupyter\n",
    "Notebook first:\n",
    "\n",
    "    $ jupyter notebook\n",
    "[**CWPK \\#10**](https://www.mkbergman.com/2337/cwpk-10-installing-a-project-notebook/)\n",
    "Assuming your are using this current notebook page as your example, your\n",
    "screen should look like this one. To confirm our notebook is active,\n",
    "type in our earlier '`Hello KBpedia!`' statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print (\"Hello KBpedia!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, scroll up to the top of this page and double-click anywhere in the\n",
    "area where the intro narrative is. You should get a screen like the one\n",
    "below, which I have annotated to point out some aspects of the\n",
    "interactive notebook page:\n",
    "\n",
    "<div style=\"margin: 10px auto; display: table;\">\n",
    "\n",
    "<img src=\"files/markdown-notebook-1.png\" title=\"Example Markdown Cell in Edit Mode\" width=\"800\" alt=\"Example Markdown Cell in Edit Mode\" />\n",
    "\n",
    "</div>\n",
    "\n",
    "<div style=\"margin: 10px auto; display: table; font-style: italic;\">\n",
    "\n",
    "Figure 1: Example Markdown Cell in Edit Mode\n",
    "\n",
    "</div>\n",
    "\n",
    "We can see that the active area on the page, what is known as a \"cell\"\n",
    "contains plain text (<span style=\"font-weight: bold;\">1</span>). Also\n",
    "note that the dropdown menu in the header (<span\n",
    "style=\"font-weight: bold;\">1</span>) tells us the cell is of the\n",
    "'Markdown' type. There are multiple types of cells, but throughout this\n",
    "series we will be concentrating on the two main ones: Markdown for\n",
    "formatting narratives, and Code for entering and testing our scripts.\n",
    "Recall that Markdown uses plain text rather than embedded tags (as in\n",
    "HTML, for example) (<span style=\"font-weight: bold;\">2</span>). We have\n",
    "conventions for designating headings (<span\n",
    "style=\"font-weight: bold;\">2</span>) or links with URLs and link text\n",
    "(<span style=\"font-weight: bold;\">2</span>). Most common page or text\n",
    "formatting such as bullets or italics or emphasized text or images have\n",
    "a plain text convention associated with them. In this instance, we are\n",
    "using the Pandoc flavor of Markdown. But, also notice, that we can mix\n",
    "many HTML elements (<span style=\"font-weight: bold;\">3</span>) into our\n",
    "Markdown text to accomplish more nuanced markup. In this case, we as\n",
    "using the HTML `<div>` tag to convey style and placement information for\n",
    "our header with its logo.\n",
    "\n",
    "As we open or close cells, new cells appear for entry at the bottom of\n",
    "our page. We can also manage these cells by inserting above or below or\n",
    "deleting them via two of the menu options (<span\n",
    "style=\"font-weight: bold;\">4</span>). To edit, we either double-click in\n",
    "a Markdown cell or enter directly into a Code cell. When have finished\n",
    "our changes, we can see the effect via the Run button (<span\n",
    "style=\"font-weight: bold;\">5</span>) or Cell option (<span\n",
    "style=\"font-weight: bold;\">4</span>), including to run all cells (the\n",
    "complete page) or selected cells. But be careful! While we can do much\n",
    "entry and modifications with Markdown cells, this application is not\n",
    "like a standard text editor. We can get instant feedback on our\n",
    "modifications, but it is different to Save files as checkpoints (<span\n",
    "style=\"font-weight: bold;\">6</span>) and changing file names is not\n",
    "possible from within the notebook, where we must use the file system. We\n",
    "can also have multiple cells unevaluated at a given time (<span\n",
    "style=\"font-weight: bold;\">7</span>). We may also choose among multiple\n",
    "kernals (different languages or versions, including R and others). Many\n",
    "of these features we will not use in this series; the resources at the\n",
    "end of this article provide additional links to learn more about\n",
    "notebooks.\n",
    "\n",
    "To learn more about Markdown, let me recommend two terrific resources.\n",
    "The first is directly relevant to Jupyter Notebook, the second is for a\n",
    "very useful Markdown format:\n",
    "\n",
    "-   [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)\n",
    "    (GFM)\n",
    "-   [The Ultimate Markdown Guide (for Jupyter\n",
    "    Notebook)](https://medium.com/analytics-vidhya/the-ultimate-markdown-guide-for-jupyter-notebook-d5e5abf728fd).\n",
    "\n",
    "When you are done working on your notebook, you can save the notebook\n",
    "using Widgets → Save Notebook Widgets State OR File → Save and\n",
    "Checkpoint and then File → Close and Halt. (You may also Logout (<span\n",
    "style=\"font-weight: bold;\">8</span>), but make sure you have saved in\n",
    "advance.) Depending on your sequence, you may exit to the command\n",
    "window. If so, and the system is still running in the background, pick\n",
    "`Ctrl+c` to quit the application and return to the command window\n",
    "prompt.\n",
    "\n",
    "Should you want to convert your notebook to a Web page (`*.html`), you\n",
    "may use nbconvert at the command prompt when you are out of Jupyter\n",
    "Notebook. For the notebook file we have been using for this example, the\n",
    "command is (assuming you are in the same directory as the notebook\n",
    "file):  \n",
    "\n",
    "      $ jupyter nbconvert --to html cwpk-14-markdown-notebook-file.ipynb\n",
    "\n",
    "This command will write out a large HTML page (large because it embeds\n",
    "all style information). This version pretty faithfully captures the\n",
    "exact look of the application on screen. See the [nbconvert\n",
    "documentation](https://nbconvert.readthedocs.io/en/latest/index.html)\n",
    "for further details. Alternatively, you may export the notebook directly by picking File → Download as → HTML (.html). Then, save to your standard download location. \n",
    "\n",
    "We will learn more about these saving options and ways to improve file\n",
    "size and faithful rendering in the next installment.\n",
    "\n",
    "<div style=\"background-color:#ffc; border:1px dotted #ff0; vertical-align:middle; margin:15px 60px; padding:8px;\"><span style=\"font-weight: bold;\">Important note:</span> as of this <strong>CWPK</strong>\n",
    "installment, we have begun to distribute Jupyter Notebook files with the\n",
    "publication of each installment. Further, even though early installments\n",
    "in this series had no interactivity, we also are beginning to re-published them with\n",
    "notebook files. From this point forward all new installments will\n",
    "include a Notebook file.</div>\n",
    "\n",
    "### More Resources\n",
    "\n",
    "-   <span style=\"font-weight: normal;\">[Jupyter Notebook Users\n",
    "    Manual](https://jupyter.brynmawr.edu/services/public/dblank/Jupyter%20Notebook%20Users%20Manual.ipynb)\n",
    "    from Bryn Mawr College (nice `*.ipynb` version)</span>\n",
    "-   [The Ultimate User's Guide to Jupyter\n",
    "    Notebooks](https://medium.com/velotio-perspectives/the-ultimate-beginners-guide-to-jupyter-notebooks-6b00846ed2af)\n",
    "-   [Tutorial: Advanced Jupyter\n",
    "    Notebooks](https://www.dataquest.io/blog/advanced-jupyter-notebooks-tutorial/)\n",
    "-   [Jupyter Notebook\n",
    "    Extensions](https://github.com/ipython/ipython/wiki/Extensions-Index)\n",
    "-   [Advanced Jupyter Notebook Tricks — Part\n",
    "    I](https://blog.dominodatalab.com/lesser-known-ways-of-using-notebooks/)\n",
    "-   [Jupiter Notebook Tips &\n",
    "    Tricks](https://stephanosterburg.gitbook.io/scrapbook/data-science/jupiter-notebook-tips-and-tricks)\n",
    "-   [Making Publication-ready Python\n",
    "    Notebooks](http://blog.juliusschulz.de/blog/ultimate-ipython-notebook).\n",
    "    \n",
    "\n",
    "  <div style=\"background-color:#efefff; border:1px dotted #ceceff; vertical-align:middle; margin:15px 60px; padding:8px;\"> \n",
    "  <span style=\"font-weight: bold;\">NOTE:</span> This article is part of the <a href=\"https://www.mkbergman.com/cooking-with-python-and-kbpedia/\" style=\"font-style: italic;\">Cooking with Python and KBpedia</a> series. See the <a href=\"https://www.mkbergman.com/cooking-with-python-and-kbpedia/\"><strong>CWPK</strong> listing</a> for other articles in the series. <a href=\"http://kbpedia.org/\">KBpedia</a> has its own Web site.\n",
    "  </div>\n",
    "\n",
    "<div style=\"background-color:#ebf8e2; border:1px dotted #71c837; vertical-align:middle; margin:15px 60px; padding:8px;\"> \n",
    "\n",
    "<span style=\"font-weight: bold;\">NOTE:</span> This <strong>CWPK \n",
    "installment</strong> is available both as an online interactive\n",
    "file <a href=\"https://mybinder.org/v2/gh/Cognonto/CWPK/master\" ><img src=\"https://mybinder.org/badge_logo.svg\" style=\"display:inline-block; vertical-align: middle;\" /></a> or as a <a href=\"https://github.com/Cognonto/CWPK\" title=\"CWPK notebook\" alt=\"CWPK notebook\">direct download</a> to use locally. Make sure and pick the correct installment number. For the online interactive option, pick the <code>*.ipynb</code> file. It may take a bit of time for the interactive option to load.</div>\n",
    "\n",
    "<div style=\"background-color:#feeedc; border:1px dotted #f7941d; vertical-align:middle; margin:15px 60px; padding:8px;\"> \n",
    "<div style=\"float: left; margin-right: 5px;\"><img src=\"http://kbpedia.org/cwpk-files/warning.png\" title=\"Caution!\" width=\"32\" /></div>I am at best an amateur with Python. There are likely more efficient methods for coding these steps than what I provide. I encourage you to experiment -- which is part of the fun of Python -- and to <a href=\"mailto:mike@mkbergman.com\">notify me</a> should you make improvements.    \n",
    "\n",
    "</div>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.8"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}