Add/hierarchical models (#3)

* remove example script

* update

* Bump version

* small fixes

* allow python 3.11

* remove unused import

* remove old token

---------

Co-authored-by: Ingeborg Gjerde <ingeborg.gjerde@ngi.no>

Author: IngeborgGjerde

Demo.ipynb

@@ -0,0 +1,209 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4a9e8552",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from field_manager_api.field_manager import FieldManagerAPI"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fbc48aa3",
+   "metadata": {},
+   "source": [
+    "### Adding your user token\n",
+    "\n",
+    "Access to the Field Manager API is controlled using tokens. To retrieve your token, go to [the Field Manager Developer Portal](https://app.test.fieldmanager.io/developer). This page shows the documentation for the API, i.e., all the endpoints and their inputs and outputs.\n",
+    "\n",
+    "For now, just click `get_token` in the upper right corner:\n",
+    "\n",
+    "<img src=\"get_token.png\" width=\"40\">\n",
+    "\n",
+    "Copy the token you get into the string below.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "03b57afc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "token = \"YOUR_TOKEN_HERE\"\n",
+    "fm = FieldManagerAPI()\n",
+    "fm.set_token(token)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3ebe8b65",
+   "metadata": {},
+   "source": [
+    "The token expires after 30 minutes, at which pointy you should make a new one.\n",
+    "\n",
+    "## Importing data\n",
+    "\n",
+    "The `Field Manager API` is a python package that simplifies using the API.\n",
+    "\n",
+    "If you know the name of the project, you can look up all projects with names containing some substring:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dc3246df",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "project_names = fm.search_for_project_name(substring=\"TellefTest\")\n",
+    "print(project_names)\n",
+    "project = fm.get_project_by_name(project_names[0])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2928f0df",
+   "metadata": {},
+   "source": [
+    "We take the first match.\n",
+    "\n",
+    "Data is structured hierarchically within the `project`:\n",
+    "\n",
+    "- `project`s have `locations`, i.e., a list of `Location` classes\n",
+    "- `locations`s have `methods`, i.e., a list of `Method` classes\n",
+    "- `method`s have `method_data`, which is a pandas dataframe:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "48dc9b1b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = project.locations[3].methods[0].data\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "80886a4e",
+   "metadata": {},
+   "source": [
+    "You can easily drop columns you're not interested in\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "980d175f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = project.locations[3].methods[0].data\n",
+    "df.drop(\n",
+    "    columns=[\"updated_at\", \"created_at\", \"comment_code\", \"remarks\"],\n",
+    "    errors=\"ignore\",\n",
+    "    inplace=True,\n",
+    ")\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e94b80bc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from field_manager_api.utils.folium_plotter import MapHandler\n",
+    "\n",
+    "mh = MapHandler(project.locations, tiles=\"OpenTopoMap\", height=\"300px\", width=\"80%\")\n",
+    "mh.plot_locations()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5f455cb4",
+   "metadata": {},
+   "source": [
+    "If you hover of the locations, a tooltip will display the _location index_ and a list of methods performed at the location. E.g.,If you want to examine the method data associated with e.g. the 0th method on the 2nd location, write\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c426f7aa",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_full = project.locations[2].methods[0].data\n",
+    "df_full.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b716e9f2",
+   "metadata": {},
+   "source": [
+    "You can easily drop columns you're not interested in,\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8ce891b1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = df_full.drop(\n",
+    "    columns=[\"updated_at\", \"remarks\", \"comment_code\", \"conductivity\", \"created_at\"]\n",
+    ")\n",
+    "df.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2d79e6a0",
+   "metadata": {},
+   "source": [
+    "or only grab the data you want\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0cc17db8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = df_full[[\"depth\", \"fs\", \"qc\", \"u2\"]]"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "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.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}