Explain column identifiers (#296)

Author: schroedtert

docs/source/api/column_identifiers.rst

@@ -0,0 +1,10 @@
+.. _api_column_identifier:
+
+******************
+Column identifiers
+******************
+
+.. autoapimodule:: pedpy.column_identifier
+    :members:
+    :no-private-members:
+    :no-special-members:

docs/source/api/index.rst

@@ -13,6 +13,8 @@ API Reference
       - Analysis methods to compute: density, speed, flow, etc
     * - :doc:`Plotting <plotting>`
       - Plot methods for displaying the measurement setup and other computed results
+    * - :doc:`Column identifiers <column_identifiers>`
+      - Identifier of the data and result columns
 
 .. toctree::
     :maxdepth: 1
@@ -22,3 +24,4 @@ API Reference
     Load Trajectories <io>
     Analysis Methods <methods>
     Plotting <plotting>
+    Column identifiers <column_identifiers>

notebooks/user_guide.ipynb

@@ -3036,10 +3036,44 @@
     "\n",
     "Now we have completed our analysis, what can be done to \n",
     "\n",
+    "- access specific columns\n",
     "- combine for further analysis\n",
     "- save results"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Access specific columns\n",
+    "\n",
+    "In order to access a specific column of the computed results or the {class}`trajectory data<trajectory_data.TrajectoryData>` *PedPy* provides all the column names for access.\n",
+    "It is highly encouraged to use these identifiers instead of using the column names directly, as the identifier would be updated, if they change. \n",
+    "A list of all identifiers can be found in the [API reference](api_column_identifier)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pedpy.column_identifier import *\n",
+    "\n",
+    "# Access with column identifier\n",
+    "traj.data[[ID_COL, FRAME_COL, POINT_COL]]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Access with column names\n",
+    "traj.data[[\"id\", \"frame\", \"point\"]]"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -3267,7 +3301,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.5"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,