First run-through

Author: AlenkaF

tutorial/01-Introduction-to-Ibis.ipynb

@@ -1,14 +1,33 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Getting started\n",
+    "# Getting started"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Setting up"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To start using `ibis`, you need a Python environment with `ibis` installed.\n",
+    "\n",
+    "If you're running through this tutorial on your own machine (rather than binder) please follow the [installation instructions](https://ibis-project.org/install/ to setup an environment with the `SQLite` backend.\n",
     "\n",
-    "To start using Ibis, you need a Python environment with Ibis installed. If you're running through this tutorial on your own machine (rather than binder) please follow the [installation instructions for SQLite](https://ibis-project.org/docs/latest/backends/SQLite/) to setup an environment.\n",
+    "You'll also need access to the `geography.db` database hosted [here](https://storage.googleapis.com/ibis-tutorial-data/geography.db).\n",
     "\n",
-    "You'll also need access to the `geography.db` database hosted [here](https://storage.googleapis.com/ibis-tutorial-data/geography.db). Every notebook in the tutorial starts with the following code to download the database if it doesn't already exist."
+    "Every notebook in the tutorial starts with the following code to download the database if it doesn't already exist:"
    ]
   },
   {
@@ -22,10 +41,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You should now have `ibis` and the tutorial data all setup. We're ready to get started. First lets import `ibis`."
+    "You should now have `ibis` and the tutorial data all setup.\n",
+    "We're ready to get started. First lets import `ibis`."
    ]
   },
   {
@@ -38,10 +59,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To make it things easier in this tutorial, we will be using Ibis's \"interactive mode\". This is the recommended mode to use when doing interactive/iterative work with `ibis`. When deploying production code you'll typically run in non-interactive mode. More details on Ibis non-interactive mode are covered in [a later notebook](./03-Expressions-Lazy-Mode-Logging.ipynb).\n",
+    "To make things easier, we will be using `ibis`'s **interactive mode** in order to see the results of an operation immediately.\n",
+    "This is the recommended mode to use when doing interactive/iterative work with `ibis`.\n",
+    "\n",
+    "When deploying production code you'll typically run in **non-interactive/lazy mode**. More details on `ibis` non-interactive mode are covered in [a later notebook](./03-Expressions-Lazy-Mode-Logging.ipynb).\n",
     "\n",
     "To enable interactive mode, run:"
    ]
@@ -56,14 +81,25 @@
    ]
   },
   {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Creating a connection"
+   ]
+  },
+  {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next thing we need is to create a connection object. The connection defines where the data is stored and where the computations will be performed.\n",
+    "Next thing we need is to create a **connection object**.\n",
+    "\n",
+    "The connection defines where the data is stored and where the computations will be performed.\n",
     "\n",
-    "For a comparison to pandas, this is not the same as where the data is imported from (e.g. `pandas.read_sql`). pandas loads data into memory and performs the computations itself. Ibis won't load the data and perform any computation, but instead will leave the data in the backend defined in the connection, and will _ask_ the backend to perform the computations.\n",
+    "This is not the same as in `pandas` when we import the data from an external source (e.g. `pandas.read_sql`). In this case `pandas` loads data into memory and performs the computations itself. `ibis` will not load the data and perform any computation, but instead will leave the data in the backend defined in the connection, and will _ask_ the backend to perform the computations.\n",
     "\n",
-    "In this tutorial we will be using a SQLite connection for its simplicity (no installation is needed). But Ibis can work with many different backends, including big data systems, or GPU-accelerated analytical databases. As well as most common relational databases (PostgreSQL, MySQL,...)."
+    "In this tutorial we will be using a `SQLite` connection for its simplicity (no installation is needed). But `ibis` can work with many different backends, including big data systems, or GPU-accelerated analytical databases. As well as most common relational databases (`PostgreSQL`, `MySQL`, ...)."
    ]
   },
   {
@@ -94,14 +130,16 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "These two tables include data about countries, and about GDP by country and year.\n",
+    "These three tables include world countries data, their GDP by year and their independence information.\n",
     "\n",
-    "The data from countries has been obtained from [GeoNames](https://www.geonames.org/countries/).\n",
-    "The GDP table will be used in the next tutorial, and the data has been obtained from the\n",
+    "* The data for the countries table has been obtained from [GeoNames](https://www.geonames.org/countries/).\n",
+    "* The GDP table will be used in the next tutorial, and the data for it has been obtained from the\n",
     "[World Bank website](https://data.worldbank.org/indicator/NY.GDP.MKTP.CD).\n",
+    "* The data for the `independence` table has been obtained from [Wikipedia](https://en.wikipedia.org/wiki/List_of_national_independence_days) and will be used in one of the following tutorials.\n",
     "\n",
     "Next, we want to access a specific table in the database. We can create a handler to the `countries` table with:"
    ]
@@ -150,10 +188,11 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The table is too big for all the results to be displayed, and we probably don't want to see all of them at once anyway. For this reason, just the beginning and the end of the results is displayed. Often, the number of rows will be so large that this operation could take a long time.\n",
+    "The table is too big for all the results to be displayed, and we probably don't want to see all of them at once anyway. For this reason, just the first 10 rows of the results are displayed.\n",
     "\n",
     "To check how many rows a table has, we can use the `.count()` method:"
    ]
@@ -204,10 +243,11 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We will focus on Asia (`AS` in the table). We can identify which rows belong to Asian countries using the standard Python `==` operator:"
+    "We will focus on Asia (`AS`). We can identify which rows belong to Asian countries using the standard Python `==` operator:"
    ]
   },
   {
@@ -257,10 +297,11 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we want to find the most populated countries in Asia. To obtain them, we are going to sort the countries by the column `population`, and just fetch the first 10. To sort by a column in Ibis, we can use the `.order_by()` method:"
+    "Next, we want to find the most populated countries in Asia. We are going to sort the countries by the column `population` and fetch the first 10. We can use the `.order_by()` method to sort by a column:"
    ]
   },
   {
@@ -273,10 +314,11 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This will return the least populated countries, since `.order_by` will by default order in ascending order (ascending order like in `1, 2, 3, 4`). This behavior is consistent with SQL `ORDER BY`.\n",
+    "Because the default for `.order_by` is ascending order (ascending order like in `1, 2, 3, 4`) the operation will return the least populated countries. This behavior is consistent with SQL `ORDER BY`.\n",
     "\n",
     "To order in descending order we can use `ibis.desc()`:"
    ]
@@ -291,12 +333,13 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "This is the list of the 10 most populated countries based on the data from [GeoNames](https://www.geonames.org/).\n",
     "\n",
-    "To learn more about Ibis, continue to the next tutorial."
+    "**_To learn more about Ibis, continue to our next tutorial: [Aggregating and joining data](./02-Aggregates-Joins.ipynb)._**"
    ]
   }
  ],