doc(analysis): document the pandas based API (#69)

This diff refactors the analysis notebook to illustrate how a developer
can obtain the data as DataFrames.

It also shows how to convert the obtained DataFrames to the data format
expected by the IQB calculator.

The availability of DataFrames allows for additional filtering and
exploration while working with the notebooks.

We also document how to get additional (large) data from GitHub
releases.

Author: bassosimone

analysis/00-template.ipynb

@@ -30,9 +30,18 @@
     "\n",
     "## Overview\n",
     "\n",
-    "The Internet Quality Barometer (IQB) framework assesses Internet quality beyond simple speed metrics by considering multiple use cases (gaming, video streaming, etc.) and their specific network requirements.\n",
+    "The Internet Quality Barometer (IQB) framework assesses Internet quality beyond simple speed\n",
+    "metrics by considering multiple use cases (gaming, video streaming, etc.) and their\n",
+    "specific network requirements.\n",
     "\n",
-    "This template uses pre-cached data for the United States from October 2024."
+    "This template uses pre-cached data included in the repository `./data` directory. You can\n",
+    "download additional data using this command:\n",
+    "\n",
+    "```bash\n",
+    "uv run ./data/ghcache.py sync\n",
+    "```\n",
+    "\n",
+    "This command will download larger data files stored inside GitHub releases."
    ]
   },
   {
@@ -50,9 +59,7 @@
    "outputs": [],
    "source": [
     "# Import required libraries\n",
-    "from datetime import datetime\n",
-    "\n",
-    "from iqb import IQBCache, IQBCalculator"
+    "from iqb import IQBCache, IQBCalculator, IQBDatasetGranularity"
    ]
   },
   {
@@ -117,20 +124,31 @@
    },
    "outputs": [],
    "source": [
-    "# Fetch data for US, October 2024, using 95th percentile\n",
-    "country = \"US\"\n",
-    "start_date = datetime(2024, 10, 1)\n",
-    "percentile = 95\n",
-    "\n",
-    "data = cache.get_data(country=country, start_date=start_date, percentile=percentile)\n",
-    "\n",
-    "# Display the retrieved data\n",
-    "print(f\"\\nData for {country} (October 2024, p{percentile}):\")\n",
-    "print(\"=\" * 50)\n",
-    "for source, metrics in data.items():\n",
-    "    print(f\"\\nSource: {source}\")\n",
-    "    for metric, value in metrics.items():\n",
-    "        print(f\"  {metric}: {value}\")"
+    "# Get cache entry for the [2024-10-01, 2024-11-01) month with country data\n",
+    "entry = cache.get_cache_entry(\n",
+    "    start_date=\"2024-10-01\",\n",
+    "    end_date=\"2024-11-01\",\n",
+    "    granularity=IQBDatasetGranularity.COUNTRY,\n",
+    ")\n",
+    "\n",
+    "# Filter the M-Lab dataset to focus on the US\n",
+    "df_pair = entry.mlab.read_data_frame_pair(country_code=\"US\")\n",
+    "\n",
+    "print(df_pair.download)\n",
+    "print(df_pair.upload)\n",
+    "\n",
+    "# Extract the 50 percentile\n",
+    "p50 = df_pair.to_iqb_data(percentile=50)\n",
+    "\n",
+    "print(p50)\n",
+    "\n",
+    "# Convert the p50 class to dict\n",
+    "p50_dict = p50.to_dict()\n",
+    "\n",
+    "# Create data compatible with the IQB calculator\n",
+    "data = {\"m-lab\": p50_dict}\n",
+    "\n",
+    "print(data)\n"
    ]
   },
   {
@@ -220,7 +238,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "iqb",
    "language": "python",
    "name": "python3"
   },