suggestions

despadam · despadam · commit 23572e589127 · 2026-03-30T17:50:57.000+02:00
diff --git a/30_introduction_data_exploration.ipynb b/30_introduction_data_exploration.ipynb
@@ -81,6 +81,7 @@
     "Python libraries are collections of pre-written code that provide reusable functions and tools for specific tasks.\n",
     "They significantly extend the capabilities of Python, allowing you to perform complex operations without writing everything from scratch.\n",
     "This saves time and effort, promotes code reusability, and helps you focus on the higher-level logic of your data analysis and visualization workflows.\n",
+    "\n",
     "Have a look at the following plot: imagine you'd have to code every detail from scratch! Instead, we rely on the help of libraries to do most of the heavy lifting for us.\n",
     "However, there is still quite a bit to do before we can reproduce exactly this.\n",
     "Let's have a look at the following plot generated with Plotly."
@@ -250,13 +251,16 @@
     "#### Getting help and inspiration\n",
     "\n",
     "Of course one of the most important parts is to be able to understand, look up and get help on any function of a library.\n",
-    "Usually, we start with some inspiration, as we gave above with the plot, there might be someone who posted something which you would like to reproduce but with a twist or you would like to change something.\n",
+    "Typically, the creative process begins with an inspiration, such as a plot or an idea you've encountered elsewhere.\n",
+    "You might wish to reproduce this concept with a unique twist or modify specific elements to suit your vision.\n",
     "This is generally a good starting point.\n",
-    "However afterwards you won't have the documentation of all the functions so you need to have the skill to find documentation and understand the requirements for function, sometimes you even need to know more about the inner workings of a functions implementations.\n",
     "\n",
-    "There are several ways to access documentation.\n",
+    "After that, though, you won't have a full documentation guide for every function.\n",
+    "You'll need to know how to track down the info you need, figure out what each function requires, and sometimes even dig into how they work under the hood.\n",
+    "\n",
+    "There are several ways to access a library's documentation.\n",
     "One way, assuming it is a well-maintained package online, is to find the documentation website.\n",
-    "For pandas, this is a great place to find details on functions, and changes that may have been made with different versions and explore alternatives to a given function.\n",
+    "For pandas, this is a great place to find details on functions, or changes that may have been made in different versions of the library, as well as alternatives to a given function.\n",
     "\n",
     "[Pandas Documentation](https://pandas.pydata.org/docs/index.html)\n",
     "\n",
@@ -270,9 +274,9 @@
     "And if you are struggling with a specific function you can print out the signature and the docstring with `help(function)` or `function?`.\n",
     "\n",
     "When reading the documentation you might get overwhelmed.\n",
-    "Keep a lookout for the function parameters, many of which may be optional, and good documentations tend to have an example to get a feel for the function.\n",
+    "Keep a lookout for the function parameters, many of which may be optional.\n",
     "\n",
-    "For most of this tutorial we will give you the infos about a function that you need, however if you want to know more or need some extra information then use these tools to inform yourself."
+    "For most of this tutorial we will give you the info about a function that you need, however if you want to know more or need some extra information then use these tools to inform yourself."
    ]
   },
   {
@@ -281,7 +285,7 @@
    "source": [
     "## First step: Data import and exploration\n",
     "\n",
-    "Already getting your data from a file to a variable you can work with can be a headache.\n",
+    "Getting your data from a file to a variable you can work with can be a headache.\n",
     "How do I read the file, how do I choose delimiters and what encoding does the file have?\n",
     "\n",
     "We will use the `pd.read_csv` function from pandas to read \"The World Happiness Report\" which is a report study on how people rate their happiness in different countries."
@@ -352,8 +356,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "happyness = pd.read_csv('data/data_exploration/World-happiness-report-updated_2024.csv', encoding='latin1')\n",
-    "happyness.describe()"
+    "happiness = pd.read_csv('data/data_exploration/World-happiness-report-updated_2024.csv', encoding='latin1')\n",
+    "happiness.describe()\n",
+    "happiness.groupby('year')['Generosity'].mean()"
    ]
   },
   {
@@ -381,7 +386,8 @@
     "| `pd.DataFrame['column_name'].value_counts()`   | Returns a Series containing counts of unique values in a column.                                           | `df['Status'].value_counts()`                  |\n",
     "| `pd.DataFrame.sort_values(by='column_name')`   | Sorts the DataFrame by the values in a specified column.                                                   | `df.sort_values(by='Date')`                    |\n",
     "| `pd.DataFrame.sort_index()`                    | Sorts the DataFrame by its index.                                                                         | `df.sort_index()`                             |\n",
-    "| `pd.DataFrame.isna().sum()`                    | Returns the number of missing (NaN) values in each column.                                                 | `df.isna().sum()`                             |\n",
+    "| `pd.DataFrame.isnull().sum()`                  | Returns the number of missing (NaN, None) values in each column.                                         | `df.isna().sum()`                             |\n",
+    "| `pd.DataFrame.isna().sum()`                    | Same as `isnull`, but `isna` is the newer preferred alias.                                               | `df.isna().sum()`                             |\n",
     "| `pd.DataFrame.duplicated().sum()`              | Returns the number of duplicate rows in the DataFrame.                                                      | `df.duplicated().sum()`                       |\n",
     "| `pd.DataFrame['column_name'].unique()`        | Returns a NumPy array of the unique values in a column.                                                     | `df['Country'].unique()`                      |\n",
     "| `pd.DataFrame.sample(n=5)`                     | Returns a random sample of items from the DataFrame (default is 1).                                        | `df.sample(n=10)`                             |\n",
@@ -414,10 +420,8 @@
    "source": [
     "import pandas as pd\n",
     "\n",
-    "happyness = pd.read_csv('data/data_exploration/World-happiness-report-updated_2024.csv', encoding='latin1')\n",
+    "df = pd.read_csv('data/data_exploration/World-happiness-report-updated_2024.csv', encoding='latin1')\n",
     "\n",
-    "# Assuming your dataframe is loaded into 'df'\n",
-    "df = happyness\n",
     "print(\"--- First few rows of the dataframe ---\")\n",
     "print(df.head(2))\n",
     "print(\"\\n\")\n",
@@ -448,8 +452,7 @@
     "    print(f\"Minimum year: {min_year}\")\n",
     "    print(f\"Maximum year: {max_year}\")\n",
     "    print(f\"Year range: {max_year - min_year} years\")\n",
-    "    print(\"\\n\")\n",
-    "\n"
+    "    print(\"\\n\")"
    ]
   },
   {
@@ -483,14 +486,13 @@
     "## Finding the limits\n",
     "\n",
     "If we are plotting a function, it is important to know the order of magnitude of some of the data.\n",
-    "In our case for example we want to have an animated plot over some years and it helps to know for which years we actually have data.\n",
-    "In a dataframe we can e.g. use the `.min()` and `.max()` methods. \n",
+    "For example, in our case we want to have an animated plot over some years and it helps to know for which years we actually have data.\n",
+    "To do that in a dataframe we can use the `.min()` and `.max()` methods. \n",
     "Optionally, to understand the distribution or \"order of magnitude\" of your time values, you might want to plot out the years and check the rough distribution to identify any anomalies or gaps in the data.\n",
     "This can be done using a histogram or a line plot to visualize the frequency or trend of the time values over the range.\n",
     "\n",
     "We want to use `matplotlib.pyplot` for displaying the histogram because it has a useful function hist which does exactly that. \n",
-    "\n",
-    "We use the `matplotlib.pyplot as plt` library and there there is `.hist` function which will produce a histogram."
+    "To do that we use the `matplotlib.pyplot as plt` library and there there is `.hist` function which will produce a histogram."
    ]
   },
   {
@@ -502,12 +504,11 @@
     "import pandas as pd\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "happiness = pd.read_csv('data/data_exploration/World-happiness-report-updated_2024.csv', encoding='latin1')\n",
-    "years = happiness['year'].unique()\n",
+    "df = pd.read_csv('data/data_exploration/World-happiness-report-updated_2024.csv', encoding='latin1')\n",
+    "years = df['year'].unique()\n",
     "print(f\"Unique years in the dataset: {sorted(years)}\")\n",
     "\n",
-    "df = happiness\n",
-    "df['year'] = happiness['year'].astype(int)  # Ensure the years are integers\n",
+    "df['year'] = df['year'].astype(int)  # Ensure the years are integers\n",
     "\n",
     "# Determine the minimum and maximum years\n",
     "min_year = df['year'].min()\n",
@@ -549,8 +550,8 @@
    "source": [
     "### Exercise: Complete Happiness\n",
     "\n",
-    "In this exercise, we want to complete the dataframe with missing values.\n",
-    "Complete the function below to \n",
+    "In this exercise, we want to complete the dataframe's missing values.\n",
+    "Complete the function below to:\n",
     "\n",
     "1. Fill in missing years for every country (so we have an entry for every year between 2005 and 2023 and every country).\n",
     "   Do this by initializing a DataFrame with `pd.DataFrame()` with a list.\n",
@@ -743,7 +744,8 @@
     "\n",
     "The data can be seen as the plot data initially, and the frames are then the animation steps.\n",
     "\n",
-    "Let's first try to create a simple scatter plot, for that we populate a figure dictionary data with a trace (`dict`) which contains an array of values for `x`, an array of values for `y`, a `mode` ('markers') and an array of strings for the text which is what appears when hovered over.\n",
+    "Let's first try to create a simple scatter plot.\n",
+    "For that, we populate a figure dictionary data with a trace (`dict`) which contains an array of values for `x`, an array of values for `y`, a `mode` ('markers') and an array of strings for the text, which is what appears when hovered over.\n",
     "\n",
     "```python\n",
     "trace = {\n",
@@ -867,7 +869,8 @@
    "source": [
     "### Adding slider bar for time scale\n",
     "\n",
-    "The slider needs configuring, this would require a bit of reading up what exactly you need or if you have an example you can make use of the existing functions.\n",
+    "The slider needs configuring.\n",
+    "This would require a bit of reading up on what exactly you need or, if you have an example, you can make use of the existing functions.\n",
     "The following is heavily inspired by the module  [`bubbly`](https://github.com/AashitaK/bubbly).\n",
     "This is simply a configuration and contains only the years data."
    ]
@@ -1252,23 +1255,25 @@
     "However, if you are browsing through possible libraries to use you might also find less well-maintained libraries, ones that may only have a single author and ones that haven't been touched in a while. \n",
     "\n",
     "Here we give you a direct example, this tutorial was inspired by the [bubbly](https://github.com/AashitaK/bubbly) package.\n",
-    "However, with an update from the pandas library it is no longer compatible with newer versions of pandas and will through an error (see codeblock below). \n",
+    "However, with an update from the pandas library it is no longer compatible with newer versions of pandas and will throw an error (see codeblock below). \n",
     "So what to do in that case?\n",
     "\n",
-    "There are many options, you can inform the author of this problem on GitHub.\n",
-    "Of course, they may not have time to fix this.\n",
+    "There are many options.\n",
+    "For example, you can inform the author of this problem on GitHub.\n",
+    "But of course, they may not have time to fix this.\n",
     "You can find a different library, however, it might not be exactly the way you wanted it.\n",
-    "You can downgrade your pandas library to be compatible, if you use pip show pandas you will see what version you have, it is possible to uninstall and reinstall a specific version.\n",
-    "However, this might not be feasible if you need it in other places and is generally not a pretty solution. \n",
+    "You can downgrade your pandas library to be compatible.\n",
+    "If you use `pip show pandas` you will see what version you have, and it is possible to uninstall and reinstall a specific version.\n",
+    "However, this might not be feasible if you need it in other places and is generally not the best solution. \n",
     "Last but not least you can try to fix it yourself.\n",
     "\n",
     "So as an exercise, we exported the bubbly library as a file `bubbly.py` into the folder `data.plotly_intro`.\n",
     "It is quite a short library so quite managable.\n",
     "Try to figure out what the error is exactly and then fix the library locally by modifying only the file `data/plotly_intro/bubbly.py` until the same code below compiles.\n",
     "\n",
-    "Note: You will need to restart the kernel after changes to the packages.\n",
+    "Note: You will need to restart the kernel after applying changes to the packages.\n",
     "\n",
-    "(If you are interested in a solution, we have a fixed version under tutorial.my_bubbly.py, feel free to check the differences.)"
+    "(If you are interested in a solution, we have a fixed version under `tutorial.my_bubbly.py`, feel free to check the differences.)"
    ]
   },
   {
