anta-database 0.2.0__tar.gz → 0.2.1__tar.gz

{anta_database-0.2.0 → anta_database-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anta_database
-Version: 0.2.0
+Version: 0.2.1
 Summary: SQLite database for the AntArchitecture Community Data
 Author: Antoine Hermant
 Author-email: antoine.hermant@etik.com

{anta_database-0.2.0 → anta_database-0.2.1}/anta_database/plotting/plotting.py

@@ -15,6 +15,7 @@ class Plotting:
         self._db = database_instance
         module_dir = os.path.dirname(os.path.abspath(__file__))
         self.gl = pd.read_pickle(os.path.join(module_dir, 'GL.pkl'))
+        self.site_coords = pd.read_pickle(os.path.join(module_dir, 'site-coords.pkl'))
 
 
     def _pre_plot_check(self,
@@ -353,6 +354,10 @@ class Plotting:
 
         plt.tight_layout()
 
+        # --- Plot ice core sites ---
+        for i in self.site_coords.index:
+            site = self.site_coords.loc[i]
+            ax.scatter(site['x']/1000, site['y']/1000, color='red', s=50, marker='^', edgecolor='black', linewidth=1.5)
         # --- Save/Show ---
         with self._plot_context():
             if save:

{anta_database-0.2.0 → anta_database-0.2.1}/anta_database.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anta_database
-Version: 0.2.0
+Version: 0.2.1
 Summary: SQLite database for the AntArchitecture Community Data
 Author: Antoine Hermant
 Author-email: antoine.hermant@etik.com

{anta_database-0.2.0 → anta_database-0.2.1}/anta_database.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ anta_database/indexing/index_database.py
 anta_database/plotting/GL.pkl
 anta_database/plotting/__init__.py
 anta_database/plotting/plotting.py
+anta_database/plotting/site-coords.pkl
 book/_config.yml
 book/_toc.yml
 book/advanced.md

anta_database-0.2.1/book/quick_start.ipynb

@@ -0,0 +1,400 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "da20d131",
+   "metadata": {},
+   "source": [
+    "# Quick start\n",
+    "\n",
+    "## Installation\n",
+    "\n",
+    "The Python module can be directly installed from [PyPI](https://pypi.org/project/anta-database/) with:\n",
+    "\n",
+    "    pip install anta_database"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "126ab4cf",
+   "metadata": {
+    "lines_to_next_cell": 0
+   },
+   "source": [
+    "\n",
+    "This Python module is designed to query and visualized data in a AntADatabase folder. The latter has to be first compiled using published IRH datasets, or you can contact for downloading it.\n",
+    "You can already have a look at this guide to have an idea of the features of this tool. This Jupyter Notebook can be directly downloaded (top bar) and ran locally (assuming you had downloaded or compiled the AntADatabase folder).\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "338b0e0d",
+   "metadata": {},
+   "source": [
+    "## Browsing the database\n",
+    "\n",
+    "First, initialize the Database class by providing the full path to the AntADatabase:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e8f554db",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from anta_database import Database\n",
+    "\n",
+    "db = Database('/home/anthe/documents/data/isochrones/AntADatabase/')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dafead60",
+   "metadata": {},
+   "source": [
+    "Use the query() function to browse the database. 'query()' without argument will return all metadata contained in the database:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "527d2e4e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "db.query()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "115fe971",
+   "metadata": {},
+   "source": [
+    "The query() function takes as argument:\n",
+    "- author: author(s) of the datasets of interest\n",
+    "- age: age(s) in yrs before present of the layer(s) of interest\n",
+    "- var: variables(s) other than age depth such as 'IceThk', 'SurfElev', 'BedElev' or 'BasalUnit'\n",
+    "- trace_id: ID of a particular trace. This is useful for explicit trace IDs such as 'DC_LDC_DIVIDE'\n",
+    "\n",
+    "One can also combine field queries as well as providing lists. Use '%' for searching by regular expressions. Here are a few examples:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "781cf326",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#Examples of queries:\n",
+    "db.query(author='Cavitte_2020') # all data from Cavitte et al. 2020\n",
+    "db.query(age='38100') # all datasets with the 38.1ka isochrone\n",
+    "db.query(var='IceThk') # all datasets with IceThk variable\n",
+    "db.query(trace_id='DC_LDC_DIVIDE') # all layers with the trace ID DC_LDC_DIVIDE\n",
+    "db.query(trace_id='%WSB%') # all traces with WSB in the trace ID\n",
+    "db.query(author=['Franke_2025', 'Winter_2018'], age='38100') # example of multiple criteria"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0df57fa9",
+   "metadata": {},
+   "source": [
+    "## Visualization\n",
+    "\n",
+    "Use the results of the query in the plotting functions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "da7aa572",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = db.query(age=['38100','38000'])\n",
+    "db.plot.author(results,\n",
+    "                downscale_factor=100, # downscale the datasets n times, which makes no visual difference but it is much lighter\n",
+    "                title='AntArchitecture 38(.1)ka layer',\n",
+    "                xlim=(-500, 2400), ylim=(-2200, 2200), # set the plot extent in km\n",
+    "                scale_factor=0.7, # adjust the size of the plot\n",
+    "                latex=True, # use latex compilers for plotting if you have them installed on your system\n",
+    "                # save='AntA_38ka.pdf', # Uncomment to save the figure, otherwise it we visualize with pyplot\n",
+    "                )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ea04b98e",
+   "metadata": {},
+   "source": [
+    "Current implemented plotting functions are:\n",
+    "- plot.author(): plot locations of the data, with different colors for the different datasets (example above)\n",
+    "- plot.depth(): color-coded IRH depth scatter plot. One should provide a valid layer age.\n",
+    "- plot.var(): color-coded scatter plot for the additional variables. One should use it for plotting 'IceThk', 'SurfElev', 'BedElev', 'BasalUnit' or 'IRHDensity'\n",
+    "- plot.trace_id(): color-coded trace IDs. Useful for identifying specific traces of interest.\n",
+    "\n",
+    "In Jupyter Notebook, use '%matplotlib qt' or '%matplotlib widget' depending on your IDE, to switch to the matplotlib widget that allows you to zoom in etc.\n",
+    "Use '%matplotlib inline' (default) to plot the figure in the notebook"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4c05c516",
+   "metadata": {
+    "lines_to_next_cell": 2
+   },
+   "outputs": [],
+   "source": [
+    "# %matplotlib widget\n",
+    "%matplotlib inline\n",
+    "results = db.query(age=['38100','38000'])\n",
+    "db.plot.depth(results, title='AntArchitecture 38(.1)ka isochrone depth',\n",
+    "                downscale_factor=100,\n",
+    "                xlim=(-500, 2400),\n",
+    "                ylim=(-2200, 2200),\n",
+    "                scale_factor=0.7,\n",
+    "                latex=True,\n",
+    "                # save='AntA_38ka_depth.png'\n",
+    "                )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f04f2c8d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = db.query(var='IRHDensity')\n",
+    "db.plot.var(results, title='IRH Density over the Antarctic Ice Sheet',\n",
+    "                downscale_factor=100,\n",
+    "                scale_factor=1,\n",
+    "                latex=True,\n",
+    "                )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c7430b95",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = db.query(author='Winter%', var='IRHDensity', trace_id=['EPICA%'])\n",
+    "db.plot.trace_id(results, title='Winter et al. 2018 - EPICA',\n",
+    "                xlim=(-500, 1000),\n",
+    "                ylim=(1000, 2200),\n",
+    "                latex=True,\n",
+    "                )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "49b0f0ae",
+   "metadata": {},
+   "source": [
+    "For an overview of the database, I suggest use plot.author() providing var='IRHDensity'. Indeed this variable is computed for each trace, giving the spatial span of the data: "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3ad14a9f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = db.query(var='IRHDensity')\n",
+    "db.plot.author(results, title='Overview of the AntADatabase',\n",
+    "                downscale_factor=100,\n",
+    "                latex=True,\n",
+    "                # save='all_data.png'\n",
+    "                )\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a27f997d",
+   "metadata": {},
+   "source": [
+    "Other possible arguments for the plot methods:\n",
+    "- cmap: provide your colormap of choice (as LinearSegmentedColormap). Tip: 'import colormaps as cmaps' for a large choice of colormaps (see [Colormaps docs](https://pratiman-91.github.io/colormaps/)) \n",
+    "- marker_size: for setting larger or smaller markers on the scatter plots"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2a08824b",
+   "metadata": {},
+   "source": [
+    "## Generate data from the database\n",
+    "\n",
+    "Note: This part could be developed further in the future if there is the need. But for now, I am designing a separate Python module for constraining my ice sheet model of use, which is tailored to this database and other parallel processing libraries.\n",
+    "\n",
+    "The data_generator() function reads the query and 'yield' the dataframes for later use.\n",
+    "Here is a quick example of how this can be used for computing the mean layer depth:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "313e2ba3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = db.query(age=['38100'])\n",
+    "lazy_dfs = db.data_generator()\n",
+    "\n",
+    "import numpy as np\n",
+    "mean_depth_trs = []\n",
+    "min_depth = float('inf')\n",
+    "max_depth = float('-inf')\n",
+    "for df, md in lazy_dfs:\n",
+    "    depth_values = df['IRHDepth']\n",
+    "    mean_depth_trs.append(np.mean(depth_values))\n",
+    "    min_depth = min(min_depth, min(depth_values))\n",
+    "    max_depth = max(max_depth, max(depth_values))\n",
+    "\n",
+    "\n",
+    "mean_depth = np.mean(mean_depth_trs)\n",
+    "std_dev = np.std(mean_depth_trs, ddof=1)\n",
+    "print(f\"The mean depth of the 38ka isochrone across East Antarctica is {round(mean_depth, 2)} m ranging from {round(min_depth, 2)} m to {round(max_depth, 2)} m.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab55a799",
+   "metadata": {},
+   "source": [
+    "In the for loop, 'df' is an individual dataframe from the database, corresponding to a single layer of a single trace from a single dataset. The 'md' stores the unique metadata from the current 'df'. One can then associate the metadata with the current df, for example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "190de359",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = db.query(author='Cavitte_2020', trace_id='DC_LDC_DIVIDE')\n",
+    "lazy_dfs = db.data_generator(results)\n",
+    "\n",
+    "import matplotlib.pyplot as plt\n",
+    "# from matplotlib import rc\n",
+    "# rc('font', **{'family': 'serif', 'serif': ['Computer Modern']})\n",
+    "# rc('text', usetex=True) # Do you use latex?\n",
+    "\n",
+    "for df, md in lazy_dfs:\n",
+    "    if md['age'] is not None:\n",
+    "        plt.plot(df.distance/1000, df['IRHDepth'], label=md['age'])\n",
+    "    if md['var'] == 'IceThk':\n",
+    "        plt.plot(df.distance/1000, df['IceThk'], linewidth=2, color='k', label='Bedrock')\n",
+    "\n",
+    "plt.legend(ncol=2)\n",
+    "plt.xlabel('Distance (km)')\n",
+    "plt.ylabel('Depth (m)')\n",
+    "plt.ylim(4000, 0)\n",
+    "plt.title('Isochronal structure along DC_LDC_DIVIDE transect')\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f1b541cf",
+   "metadata": {},
+   "source": [
+    "### Downscale the data\n",
+    "\n",
+    "The downscale_factor argument in the data_generator reduces the size of the generated data by n times. This is useful when dealing with large data where the downscaling has a neglectable influence on the results.\n",
+    "Another solution, probably more straightforward, is the downsample_distance option, which allows to provide a distance in meters by which the data should be average along the transects:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bed8b1c8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "results = db.query(author='Cavitte_2020', age='278000', trace_id='DC_LDC_DIVIDE')\n",
+    "original = db.data_generator(results)\n",
+    "downscale_10 = db.data_generator(results, downscale_factor=100)\n",
+    "downsampled_by_distance = db.data_generator(results, downsample_distance=5000)\n",
+    "\n",
+    "list = [original, downscale_10, downsampled_by_distance]\n",
+    "labels = ['original', 'downscale 100', 'downsample 5km']\n",
+    "\n",
+    "for i, lazy_dfs in enumerate(list):\n",
+    "    for df, md in lazy_dfs:\n",
+    "        plt.plot(df.distance, df['IRHDepth'],label=labels[i], linestyle='--')\n",
+    "\n",
+    "plt.ylim(3000, 0)\n",
+    "plt.xlabel('Distance along DC_LDC_DIVIDE (km)')\n",
+    "plt.ylabel('Depth (m)')\n",
+    "plt.legend()\n",
+    "plt.title('Different downscaling methods for Cavitte 2020 278ka along DC_LDC_DIVIDE')\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "90c918f0",
+   "metadata": {},
+   "source": [
+    "# Pro tips\n",
+    "\n",
+    "The Database methods always keep the last query in memory. This means that one does not have to actually pass argument.\n",
+    "Example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8fa78641",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "db.query(var='IRHDensity')\n",
+    "# db.plot.var() # This is equivalent to the overview plot above. Note that without downscaling it is very heavy to plot.\n",
+    "\n",
+    "import numpy as np\n",
+    "mean_density_trs = []\n",
+    "min_density = float('inf')\n",
+    "max_density = float('-inf')\n",
+    "for df, md in db.data_generator():    # without explicitly passing results, it uses the last query.\n",
+    "    density_values = df['IRHDensity']\n",
+    "    mean_density_trs.append(np.mean(density_values))\n",
+    "    min_density = min(min_density, min(density_values))\n",
+    "    max_density = max(max_density, max(density_values))\n",
+    "\n",
+    "mean_density = np.mean(mean_density_trs)\n",
+    "print(f\"The average number of picked layers per data point in the AntADatabase is {int(mean_density)}, ranging from {int(min_density)} to {int(max_density)}. \")\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "processing",
+   "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.13.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{anta_database-0.2.0 → anta_database-0.2.1}/pyproject.toml

@@ -43,6 +43,6 @@ Issues = "https://github.com/antoinehermant/anta_database/issues"
 exclude = ["book*"]
 
 [tool.setuptools.package-data]
-anta_database = ["database/plotting/*.pkl"]
+anta_database = ["plotting/*.pkl"]
 
 [tool.setuptools_scm]