notebooks/methods/intro-to-notebooks.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Intro to Jupyter Notebooks\n",
    "Jupyter Notebooks are interactive coding environments composed of sequential cells where each cell is either code or documentation (like this first text cell). If no code cells are added, they are essentially a text document. When code cells are used they can run specific programming languages (originally [Julia](https://julialang.org/) and [Python](https://www.python.org/), hence `Ju Py ter`) but also command line operations. \n",
    "\n",
    "We can take advantage of this combination: command line, code, and documentation to produce notebooks that lay out how to use a tool or method, and easily share it with others.\n",
    "\n",
    "This is a sample notebook where we showcase the basic operations you need to know to navigate the open source research notebooks in this repository.\n",
    "\n",
    "Although you can install and run Jupyter on your computer, it can become a hassle depending on your operating system, app versions, and so on. So we advise you to start with [Google Colab](https://colab.research.google.com/) which is like any other Google document but instead of slides or spreadsheets it's a Jupyter Notebook you get. You can [open this very notebook on Colab](https://colab.research.google.com/github/bellingcat/open-source-research-notebooks/blob/main/notebooks/methods/intro-to-notebooks.ipynb) and execute it there, you can also just [view it on GitHub](https://github.com/bellingcat/open-source-research-notebooks/blob/main/notebooks/methods/intro-to-notebooks.ipynb) but that will be a static version.\n",
    "\n",
    "We **strongly** advise you to watch [this 3min video on Google Colab](https://www.youtube.com/watch?v=inN8seMm7UI) and come back to run the cells in this notebook. The internet is full of great tutorials for Jupyter Notebooks, Google Colab, and more notebook environments.\n",
    "\n",
    "Now, let's run our first code cell below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "today = datetime.datetime.now().strftime(\"%Y-%m-%d\")\n",
    "print(f\"Hello from a piece of python code, today is {today}!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What you just did was run a simple set of python instructions that printed today's date to the calendar.\n",
    "\n",
    "---\n",
    "\n",
    "Now, let's take advantage of another notebooks feature, reading your input. \n",
    "\n",
    "When you run the next cell, the execution will hold until you give it an input.\n",
    "Depending on the environment you are running this notebook on, there will be a popup or a text box. On Google Colab, this may not be visible in dark mode but if you click to the right of the question you will find the text input.\n",
    "\n",
    "Answer it and press enter to see the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "name = input(\"What is your name? \")\n",
    "print(f\"Hi {name}, you're getting the hang of this!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that all the changes you make to your notebook are kept only in your copy. \n",
    "\n",
    "If you imported or clicked a button on one of our links what you see is a copy made from our original that you are now in total control of. In fact, if you use Google Colab you can share it with people just like any other Google doc.\n",
    "\n",
    "In the next cell we will not run Python code, but rather call the command line. Think of it like giving instructions to the computer that is running this notebook. Command line cells start with `!` or `%%bash` and that's how you'll know what kind of cell is running, it's how the notebook knows it too! \n",
    "\n",
    "Some of these commands are for Linux-based systems and Mac, like Google Colab, but if you run it on a Windows machine you will get an error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!echo \"Hello from the command line, I'm in this location: $(pwd)\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's run a command line script that downloads an image to the Notebook environment. If you're on Google Colab, there's a folder icon to the left where you can see the files available in the environment, after running the cell a new file `bellingcat.png` will appear.\n",
    "\n",
    "You will also see the messages from the `wget` command about the download operation progress."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!wget \"https://www.bellingcat.com/app/themes/bellingcat/assets/icons/favicons/apple-touch-icon-1024x1024.png\" -O bellingcat.png"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can now find the new `bellingcat.png` file on your notebook environment and download it. This is a crucial step as many times you want to produce a result (think a dataset) and download it to share and manipulate elsewhere. Similarly, you can also upload files to process them with a notebook.\n",
    "\n",
    "\n",
    "Finally, you need to know how to edit a code cell, change the value of `count_to` from `5` to a number of your choice (under 1000 so you don't long outputs) and `count_object` from `apple` to another object you'd like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "count_to = 5\n",
    "count_object = \"apple\"\n",
    "\n",
    "assert count_to < 1000, \"That's too high!\"\n",
    "print(f\"Counting {count_object} to {count_to}!\")\n",
    "for i in range(1, count_to + 1):\n",
    "    print(f\"{i} {count_object if i == 1 else count_object + 's'}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With these exercises you should now be able to navigate the remaining notebooks on the repository!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "open-source-research-notebooks-4sg58OrJ",
   "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}