{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7f08bcc7",
   "metadata": {},
   "source": [
    "# Tree species basics"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4dd5f8e",
   "metadata": {},
   "source": [
    "This notebook shows how to retrieve species using `TreeSpecies` and inspect the underlying `TreeName` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "3670a82d",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-07-17T18:03:47.171315Z",
     "iopub.status.busy": "2025-07-17T18:03:47.171146Z",
     "iopub.status.idle": "2025-07-17T18:03:47.518072Z",
     "shell.execute_reply": "2025-07-17T18:03:47.516732Z"
    }
   },
   "outputs": [],
   "source": [
    "from pyforestry.base.helpers.tree_species import (\n",
    "    ALNUS_GLUTINOSA,\n",
    "    ALNUS_INCANA,\n",
    "    TreeName,\n",
    "    TreeSpecies,\n",
    "    parse_tree_species,\n",
    ")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "983749f9",
   "metadata": {},
   "source": [
    "`TreeSpecies` exposes region-specific namespaces. Each attribute is a `TreeName` instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "a757c95d",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-07-17T18:03:47.527886Z",
     "iopub.status.busy": "2025-07-17T18:03:47.526977Z",
     "iopub.status.idle": "2025-07-17T18:03:47.532855Z",
     "shell.execute_reply": "2025-07-17T18:03:47.532377Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "TreeName(genus=TreeGenus(name='Pinus', code='PINUS'), species_name='sylvestris', code='PSYL')"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "TreeSpecies.Sweden.pinus_sylvestris\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "545b8976",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-07-17T18:03:47.534441Z",
     "iopub.status.busy": "2025-07-17T18:03:47.534266Z",
     "iopub.status.idle": "2025-07-17T18:03:47.538032Z",
     "shell.execute_reply": "2025-07-17T18:03:47.537625Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[TreeName(genus=TreeGenus(name='Pinus', code='PINUS'), species_name='sylvestris', code='PSYL'),\n",
       " TreeName(genus=TreeGenus(name='Pinus', code='PINUS'), species_name='contorta', code='PCON'),\n",
       " TreeName(genus=TreeGenus(name='Pinus', code='PINUS'), species_name='mugo', code='PMUG')]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "TreeSpecies.Sweden.pinus.full_name\n",
    "list(TreeSpecies.Sweden.pinus)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "372ff760",
   "metadata": {},
   "source": [
    "Strings can be converted to `TreeName` objects using `parse_tree_species()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "fbec2bee",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-07-17T18:03:47.539890Z",
     "iopub.status.busy": "2025-07-17T18:03:47.539529Z",
     "iopub.status.idle": "2025-07-17T18:03:47.543012Z",
     "shell.execute_reply": "2025-07-17T18:03:47.542494Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parse_tree_species('Pinus sylvestris')\n",
    "parse_tree_species('pInus sylvestris') == TreeSpecies.Sweden.pinus_sylvestris\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a56719c1",
   "metadata": {},
   "source": [
    "`TreeName` holds genus and species information and can be compared directly. `TreeSpecies` simply provides organized access to these objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "c3e7ec3f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-07-17T18:03:47.544604Z",
     "iopub.status.busy": "2025-07-17T18:03:47.544437Z",
     "iopub.status.idle": "2025-07-17T18:03:47.547901Z",
     "shell.execute_reply": "2025-07-17T18:03:47.547432Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "pyforestry.base.helpers.tree_species.RegionalTreeSpecies"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "isinstance(TreeSpecies.Sweden.pinus_sylvestris, TreeName)\n",
    "type(TreeSpecies.Sweden)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0039e0ee",
   "metadata": {},
   "source": [
    "Genus groups act like containers. We can check membership just like in the tests."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "7e3347c1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-07-17T18:03:47.549430Z",
     "iopub.status.busy": "2025-07-17T18:03:47.549261Z",
     "iopub.status.idle": "2025-07-17T18:03:47.552705Z",
     "shell.execute_reply": "2025-07-17T18:03:47.552186Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ALNUS_GLUTINOSA in TreeSpecies.Sweden.alnus\n",
    "ALNUS_INCANA in TreeSpecies.Sweden.alnus\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.11.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}