{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9bbc92fa",
   "metadata": {},
   "source": [
    "# Guide to Computational Publishing\n",
    "### By [Adam Mazel, Digital Publishing Librarian, Indiana University](https://libraries.indiana.edu/adam-mazel)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5017e609",
   "metadata": {},
   "source": [
    "## What is Computational Publishing?\n",
    "\n",
    "Computational publishing (CP) is a recent (2017-present) and often free means of creating and disseminating digital text and computer code that enhances reader interactivity. It enables you to write and publish on the web human-readable text alongside machine-readable computer code **that can also be run, modified, and created by the reader**. Thus, your reader can do more than just read your code or even run your code--in CP, your reader can also modify your code and even write new code alongside your own. Therefore, CP readers can also be CP writers, particularly of programming languages."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "468dea58",
   "metadata": {},
   "source": [
    "### Examples\n",
    "\n",
    "Examples of Computational Publishing include:\n",
    "\n",
    "1. [_Aesthetic Programming_](https://aesthetic-programming.net/pages/1-getting-started.html) by [Winnie Soon](https://www.siusoon.net/) & [Geoff Cox](https://peoplefinder.lsbu.ac.uk/researcher/87z25/dr-geoff-cox)\n",
    "\n",
    "This digital textbook offers a sidebar to enable reader interactivity: code running, revision, and creation.\n",
    "\n",
    "2. [_Introduction to Colab and Python_](https://colab.research.google.com/github/tensorflow/examples/blob/master/courses/udacity_intro_to_tensorflow_for_deep_learning/l01c01_introduction_to_colab_and_python.ipynb#scrollTo=X9uIpOS2zx7k) by The TensorFlow Authors\n",
    "\n",
    "This guide is created in [Google Colaboratory](https://colab.research.google.com/) (discussed below) to mix human-readable text with machine-readable Python code that can be run, revised, and created by its reader. These actions can modify the original publication (if those privilges are granted to readers).\n",
    "\n",
    "3. [_Python for Computational Science and Engineering_](https://mybinder.org/v2/gh/fangohr/introduction-to-python-for-computational-science-and-engineering/7e40ec1013ecb078e7fc2aa7d3ec06802c76321a) by [Hans Fangohr](https://fangohr.github.io/)\n",
    "\n",
    "This digital textbook uses the software [Binder](https://mybinder.org/) (discussed below) to enable the mixing human-readable text with machine-readable python code that can be run, revised, and created by its reader. These actions cannot modify the original publication.\n",
    "\n",
    "4. [Journal of Digital History](https://journalofdigitalhistory.org)\n",
    "\n",
    "The JDH also uses Binder to publish data-driven scholarship. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11e054e3",
   "metadata": {},
   "source": [
    "### Further Example\n",
    "\n",
    "This guide also uses Binder to exemplify CP:\n",
    "\n",
    "**Reader, run the code cell below by clicking in it and then pressing \"Run\" in the menu above. Then, hange the variable \"a\" to a new number (ex. a = 6), and run the cell again.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "c4445ca2",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5\n"
     ]
    }
   ],
   "source": [
    "a = 10\n",
    "print(a-5)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "305f8521",
   "metadata": {},
   "source": [
    "## Why Computational Publishing?\n",
    "\n",
    "Because one's audience can now execute author-written code to see its result, CP can facilitate evaluations of the data science's reproducibility: readers can now test the writer's code. Moreover, because CP allows readers to modify code (for example, by inputing different queries), CP enables readerly exploration and inquiry. And lastly, because CP allows readers to write their own code--say in response to a prompt by the writer--CP thus is apt for the creation and completion of educational exercises and activities, particularly in code-based instruction, such as in computer and data science fields. CP therefore is an apt medium for both reproducible research and pedagogy.\n",
    "\n",
    "### Computational Publishing for Educational Materials\n",
    "CP can be used to create and web publish interactive, data-driven educational materials, particularly textbooks, assignments / activities, lecture notes, etc. Assignments, for instance, be created, shared, and distributed by faculty; completed and returned by students; and commented on and auto- and manually graded in turn. Moreover, CP can be used to create what are known as **Open Educational Resources (OER)**: educational materials that are free of cost and most copyright restrictions, so others can reuse them and / or create revised versions of them. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18a42fd0",
   "metadata": {},
   "source": [
    "## How is Computational Publishing Done?\n",
    "\n",
    "Computational Publishing can be done with various software. But its software stack is often composed of some combination of:\n",
    "\n",
    "1. [Markdown](https://www.markdownguide.org/) is a markup language for formatting plain text. \n",
    "\n",
    "2. [Jupyter Notebooks](https://jupyter.org/) and [JupyterBook](https://jupyterbook.org/en/stable/intro.html) are software for writing and sharing on the web documents that mix text--formatted via Markdown--with runnable code in over 40 programming languages, including Python and R. The former is for creating and sharing documents of plain text and code, the latter is for creating and sharing books of plain text and code.\n",
    "\n",
    "3. [GitHub](https://github.com/) is a web-based repository and interface for storing and sharing code and files, such as Jupyter Notebooks.\n",
    "\n",
    "4. [Binder](https://mybinder.org/) enables authors and readers to write, run, and share / publish Jupyter Notebooks on the web via GitHub without having to download, install, or run anything. \n",
    "\n",
    "5. [JupyterHub](https://jupyter.org/hub) enables Jupyter Notebooks to be run, modified, and shared / published on the web without the reader having to download, install, or run anything. JupyterHub hosts Jupyter notebooks on a server with multiple users whose access can be controlled via authentication. \n",
    "\n",
    "6. [Google Colaboratory](https://colab.research.google.com/) enables authors and readers to write, run, and share / publish Jupyter Notebooks on the web via Google Drive without having to download, install, or run anything.\n",
    "\n",
    "7. [Microsoft Azure Lab Services](https://learn.microsoft.com/en-us/azure/lab-services/class-type-jupyter-notebook) enables Jupyter Notebooks to be run, modified, and shared / published on the web without the reader having to download, install, or run anything.\n",
    "\n",
    "8. [Docker](https://www.docker.com/) creates the virtual environment that contains / provides all the software and data necessary for the code in the publication to execute so that CP readers can run and write code in computational publications without having to download, install, or run anything. \n",
    "\n",
    "Docker--and Binder, JupyterHub, Colab, and Azure--obviate the need for downloads or installs for code to be executable and writable by readers by providing all of the necessary software and data for the code to run. For example, if the computational publication employs Python, readers do not need to have Python installed on their computer to read, execute, or modify the code in the publication. This provision of software in a virtual environment is what enables readers to interact with the published text and code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c78917cb",
   "metadata": {},
   "source": [
    "### Which Software? Pros / Cons\n",
    "\n",
    "* Binder is free of charge. It ensures [user privacy](https://mybinder.readthedocs.io/en/latest/about/user-guidelines.html#security-and-privacy). It does not (on its own) allow reader changes to be saved. Additional software requirements are loaded via requirements files. It has more of a learning curve. \n",
    "* Google Colab is free of charge. As it is a Google product, user data may be reused or sold.  does allow readers to save and share their changes. Additional software requirements are loaded manually in the environment. It has less of a learning curve. \n",
    "* Microsoft Azure is not free of charge but costs money. It has the highest learning curve. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1152a773",
   "metadata": {},
   "source": [
    "### CP Software Particularly Apt for Classroom Use\n",
    "\n",
    "* Google Colaboratory\n",
    "* JupyterHub \n",
    "* [nbgrader](https://nbgrader.readthedocs.io/en/stable/) is a tool for creating, grading, and commenting on Jupyter Notebook-based assignments\n",
    "\n",
    "#### Overviews of Classroom Tools / Uses\n",
    "* This [Jupyter book](https://jupyter4edu.github.io/jupyter-edu-book/) overviews how Jupyter Notebooks can be used in educational / classroom contexts\n",
    "* This [video](https://youtu.be/OuhtpxGuboY) overviews how JupyterHub and Jupyter Notebooks can be used in educational / classroom contexts.\n",
    "* This [video](https://youtu.be/5WUm0QuJdFw) introduces nbgrader. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "800b29ac",
   "metadata": {},
   "source": [
    "### How to Create a Computational Publication via Binder\n",
    "\n",
    "[Binder How-To Guide](https://the-turing-way.netlify.app/communication/binder/zero-to-binder.html)\n",
    "\n",
    "#### Steps\n",
    "1. Create a Jupyter Notebook (JN) containing both text and code. If you do not already have JN on your computer, install it [here](https://jupyter.org/). \n",
    "\n",
    "2. Go to [GitHub](https://www.github.com) (GH). If you do not have a GH account, create one. If you do (or after you do), create a new repository on GH. The repo should be public, not private, and add a README file. You may wish to update your README with information on how to use your CP. \n",
    "\n",
    "3. Upload your JN into your GH repo by clicking \"Add File\" and committing it to the repo's Main Branch.\n",
    "\n",
    "4. If your JN requires additional software--dependencies, libraries, etc.--to run, you will also need to upload into your repo a [dependency file](https://the-turing-way.netlify.app/communication/binder/zero-to-binder.html#pinning-dependencies).Then commit to the main branch.\n",
    "\n",
    "5. Go to https://mybinder.org. Type your repo's URL into the “GitHub repo or URL” box. It should look like this: \n",
    "\n",
    "`YOUR-USERNAME/YOUR-REPO-NAME`\n",
    "\n",
    "As you type, the webpage generates a link in the “Copy the URL below…” box. It should look like this: \n",
    "\n",
    "`https://mybinder.org/v2/gh/YOUR-USERNAME/YOUR-REPO-NAME/HEAD`\n",
    "\n",
    "To ease sharing your CP, create a Binder badge by coping the Markdown or ReStructured Text snippet into your README.md file. This snippet will render a badge that people can click. Click \"Launch\"\n",
    "\n",
    "6. When complete, visit the URL above. You will see a “spinner” as Binder launches the repo. If everything ran smoothly, you’ll see a JupyterLab interface. Click the Notebook button to open the JN. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cad7834a",
   "metadata": {},
   "source": [
    "### How to Create a Computational Publication via Google Colaboratory\n",
    "\n",
    "[Google Colab How-To Guide](https://colab.research.google.com/#)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c863f03",
   "metadata": {},
   "source": [
    "### How to Create a Computational Publication via Microsoft Azure\n",
    "\n",
    "[Microsoft Azure How-To Guide](https://learn.microsoft.com/en-us/azure/lab-services/class-type-jupyter-notebook)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "86576fe8",
   "metadata": {},
   "source": [
    "## DOIs for Computational Publications\n",
    "\n",
    "Digital Object Identifiers (DOIs) are persistent identifiers for digital objects published on the web, from websites to e-books to computational publications. They make the publication easier to find, share, and access by providing metadata and solving the problem of broken links. \n",
    "\n",
    "To secure a DOI for your computational publication, contact [Ethan Fridmanski, Data Services Librarian, IU Libraries](https://libraries.indiana.edu/ethan-fridmanski)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f1608eb",
   "metadata": {},
   "source": [
    "## Further Reading\n",
    "\n",
    "* Bowie, S. (2022). [\"What is computational publishing? Community-Led Open Publication Infrastructures for Monographs (COPIM).\"](https://doi.org/10.21428/785a6451.af466093)\n",
    "* Odewahn, Andrew. (2017). [\"Computational Publishing with Jupyter\"](https://github.com/odewahn/computational-publishing#computational-publishing-with-jupyter)\n",
    "* (2019). [\"Six easy ways to run your Jupyter Notebook in the cloud\"](https://www.dataschool.io/cloud-services-for-jupyter-notebook/)\n",
    "* Luong, Jimmy. (2022). [\"Seamlessly Share Coding Demos to Colleagues Using Binder\"](https://towardsdatascience.com/seamlessly-share-coding-demos-to-colleagues-using-binder-bbea9a823505)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}