02b_extractors.extract.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2b. Using yadg in Python via `yadg.extractors.extract()`\n",
    "\n",
    "The functionality that is accessed when using the [command line `yadg extract`](02a_yadg_extract.ipynb) can be conveniently accessed from within Python, using the `yadg.extractors.extract()` function. The [documentation of this function](https://dgbowl.github.io/yadg/5.1/apidoc/yadg.extractors.html#yadg.extractors.extract) is embedded below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<iframe src=\"https://dgbowl.github.io/yadg/5.1/apidoc/yadg.extractors.html#yadg.extractors.extract\" width=\"100%\" height=\"300\"></iframe>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%html \n",
    "<iframe src=\"https://dgbowl.github.io/yadg/5.1/apidoc/yadg.extractors.html#yadg.extractors.extract\" width=\"100%\" height=\"300\"></iframe>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2b.2 Extracting data from a BioLogic `.mpr` file\n",
    "In analogy with the command line example in the previous section of the tutorial, we are extracting some PEIS data from the `extract/peis.mpr` file. The returned object will be a `DataTree`. Note that we are letting yadg use the default options for `timezone` (i.e. `localtime`), `encoding` (i.e. `utf-8`), and `locale` (i.e. `LC.NUMERIC` or `en_GB`, if unset). When extracting `mpr` files, only the `timezone` option has any effect. When using other *Extractors* (e.g. `eclab.mpt` or `basic.csv`), the setting appropriate `locale` and `encoding` may be necessary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import yadg\n",
    "yadg.extractors.extract(filetype=\"eclab.mpr\", path=\"extract/peis.mpr\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We obtain the equivalent object to our previous example, with one root node that contains one dimension (`uts`) and 48 data variables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2b.3 Extracting metadata from a PANalytical `.xrdml` file\n",
    "To extract data from PANalytical `.xrdml` files, we need to pass `panalytical.xrdml` as the `filetype` argument and the correct path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt = yadg.extractors.extract(filetype=\"panalytical.xrdml\", path=\"extract/scans.xrdml\")\n",
    "dt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, the above object contains not only the metadata, but also the data. Currently, there is no simple way to ask for just the metadata of a `DataTree` object. As workaround, one can traverse the tree and use the `.to_dict(data=False)` method on each tree node (which contains a `xarray.Dataset`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import JSON\n",
    "metatree = {k: v.to_dict(data=False) for k, v in dt.to_dict().items()}\n",
    "JSON(metatree)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `metatree` object created here is a `dict` that is equivalent to the `JSON` created using `yadg extract --meta-only` in the previous chapter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Back to index](index.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "yadg-examples",
   "language": "python",
   "name": "yadg-examples"
  },
  "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}