<commit_before>{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using and Creating Labels\n",
    "\n",
    "Labels are a way to 'bookmark' certain pores for easier lookup later, such as specifying boundary conditions.  When networks are generated they include a set of relevent labels that have been added for convenience.  It's also possible for users to add their own labels.  This tutorial will cover how they work, how to add them, and how to use them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import openpnm as op\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Pre-defined Labels\n",
    "\n",
    "The simple ``Cubic`` network has several labels added during creating.  We can see these labels when we inspecting (i.e. ``print``) the network,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "openpnm.network.Cubic : net_01\n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "#     Properties                                    Valid Values\n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "1     pore.coords                                      25 / 25   \n",
      "2     throat.conns                                     40 / 40   \n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "#     Labels                                        Assigned Locations\n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "1     pore.all                                      25        \n",
      "2     pore.back                                     5         \n",
      "3     pore.front                                    5         \n",
      "4     pore.internal                                 25        \n",
      "5     pore.left                                     5         \n",
      "6     pore.right                                    5         \n",
      "7     pore.surface                                  16        \n",
      "8     throat.all                                    40        \n",
      "9     throat.internal                               40        \n",
      "10    throat.surface                                16        \n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n"
     ]
    }
   ],
   "source": [
    "pn = op.network.Cubic(shape=[5, 5, 1])\n",
    "print(pn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above output we can see 2 'properties', which is the term used for numerical data, and 10 'labels'.  Labels are also Numpy arrays, so are stored in the OpenPNM objects along 'propery' arrays. The different is that 'labels' are ``boolean`` type (i.e. ``True``, ``False``).\n",
    "\n",
    "A ``boolean`` array, such as *'pore.left'* is an *Np* long with ``True`` values indicating which pores possess that label.  \n",
    "\n",
    "The label 'pore.left' clearly indicates which pores on of the 'left' side of the network.  We can inspect the label array directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[ True  True  True  True  True False False False False False False False\n",
      " False False False False False False False False False False False False\n",
      " False]\n"
     ]
    }
   ],
   "source": [
    "print(pn['pore.left'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But it's more useful to extract the *locations* of the true values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, 3, 4], dtype=int64)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.where(pn['pore.left'])[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OpenPNM objects all have a method for accessing such locations directly without calling ``where``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {<commit_msg>ignore output in tutorials/using_and_creating_labels because of adidtional dtype output<commit_after>{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using and Creating Labels\n",
    "\n",
    "Labels are a way to 'bookmark' certain pores for easier lookup later, such as specifying boundary conditions.  When networks are generated they include a set of relevent labels that have been added for convenience.  It's also possible for users to add their own labels.  This tutorial will cover how they work, how to add them, and how to use them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import openpnm as op\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Pre-defined Labels\n",
    "\n",
    "The simple ``Cubic`` network has several labels added during creating.  We can see these labels when we inspecting (i.e. ``print``) the network,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "openpnm.network.Cubic : net_01\n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "#     Properties                                    Valid Values\n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "1     pore.coords                                      25 / 25   \n",
      "2     throat.conns                                     40 / 40   \n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "#     Labels                                        Assigned Locations\n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n",
      "1     pore.all                                      25        \n",
      "2     pore.back                                     5         \n",
      "3     pore.front                                    5         \n",
      "4     pore.internal                                 25        \n",
      "5     pore.left                                     5         \n",
      "6     pore.right                                    5         \n",
      "7     pore.surface                                  16        \n",
      "8     throat.all                                    40        \n",
      "9     throat.internal                               40        \n",
      "10    throat.surface                                16        \n",
      "――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――\n"
     ]
    }
   ],
   "source": [
    "pn = op.network.Cubic(shape=[5, 5, 1])\n",
    "print(pn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above output we can see 2 'properties', which is the term used for numerical data, and 10 'labels'.  Labels are also Numpy arrays, so are stored in the OpenPNM objects along 'propery' arrays. The different is that 'labels' are ``boolean`` type (i.e. ``True``, ``False``).\n",
    "\n",
    "A ``boolean`` array, such as *'pore.left'* is an *Np* long with ``True`` values indicating which pores possess that label.  \n",
    "\n",
    "The label 'pore.left' clearly indicates which pores on of the 'left' side of the network.  We can inspect the label array directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[ True  True  True  True  True False False False False False False False\n",
      " False False False False False False False False False False False False\n",
      " False]\n"
     ]
    }
   ],
   "source": [
    "print(pn['pore.left'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But it's more useful to extract the *locations* of the true values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, 3, 4], dtype=int64)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "np.where(pn['pore.left'])[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OpenPNM objects all have a method for accessing such locations directly without calling ``where``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
{'fraction_non_alphanumeric': 0.2295390404515522, 'fraction_numerical': 0.012334065015156267, 'mean_word_length': 1.7886913436315943, 'pattern_counts': {'":': 104, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 52, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6713943', 'n_tokens_mistral': 3715, 'n_tokens_neox': 3590, 'n_words': 791}