example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# `scinum` example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "! [ -f \"scinum/__init__.py\" ] || pip install scinum\n",
    "from scinum import Number, Correlation, NOMINAL, UP, DOWN"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The examples below demonstrate\n",
    "\n",
    "- [Numbers and formatting](#Numbers-and-formatting)\n",
    "- [Defining uncertainties](#Defining-uncertainties)\n",
    "- [Multiple uncertainties](#Multiple-uncertainties)\n",
    "- [Configuration of correlations](#Configuration-of-correlations)\n",
    "- [Automatic uncertainty propagation](#Automatic-uncertainty-propagation)\n",
    "- [Rounding](#Rounding)\n",
    "- [Export into different formats](#Export-into-different-formats)\n",
    "  - [yaml via HEPData](#yaml-via-HEPData)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Numbers and formatting"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$1.234 \\pm0.2$"
      ],
      "text/plain": [
       "<Number at 0x1117c24f0, '1.234 +-0.2'>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n = Number(1.234, 0.2)\n",
    "n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The uncertainty definition is absolute. See the examples with [multiple uncertainties](#Multiple-uncertainties) for relative uncertainty definitions.\n",
    "\n",
    "The representation of numbers (`repr`) in jupyter notebooks uses latex-style formatting. Internally, [`Number.str()`](https://scinum.readthedocs.io/en/latest/#scinum.Number.str) is called, which - among others - accepts a `format` argument, defaulting to `\"%s\"` (configurable globally or per instance via [`Number.default_format`](https://scinum.readthedocs.io/en/latest/#scinum.Number.default_format)). Let's change the format for this instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$1.23 \\pm0.20$"
      ],
      "text/plain": [
       "<Number at 0x1117c24f0, '1.23 +-0.20'>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n.default_format = \"%.2f\"\n",
    "n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1.234 +-0.200'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# or\n",
    "n.str(\"%.3f\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining uncertainties"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above, `n` is defined with a single, symmetric uncertainty. Here are some basic examples to access and play it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.234\n",
      "<class 'float'>\n"
     ]
    }
   ],
   "source": [
    "# nominal value\n",
    "print(n.nominal)\n",
    "print(type(n.nominal))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(0.2, 0.2)\n",
      "0.2\n",
      "0.2\n"
     ]
    }
   ],
   "source": [
    "# get the uncertainty\n",
    "print(n.get_uncertainty())\n",
    "print(n.get_uncertainty(direction=UP))\n",
    "print(n.get_uncertainty(direction=DOWN))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.234\n",
      "1.434\n",
      "1.034\n"
     ]
    }
   ],
   "source": [
    "# get the nominal value, shifted by the uncertainty\n",
    "print(n.get())      # nominal value\n",
    "print(n.get(UP))    # up variation\n",
    "print(n.get(DOWN))  # down variation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "absolute factors:\n",
      "1.1620745542949757\n",
      "0.8379254457050244\n",
      "\n",
      "relative factors:\n",
      "0.1620745542949757\n",
      "0.1620745542949757\n"
     ]
    }
   ],
   "source": [
    "# some more advanved use-cases:\n",
    "\n",
    "# 1. get the multiplicative factor that would scale the nomninal value to the UP/DOWN varied ones\n",
    "print(\"absolute factors:\")\n",
    "print(n.get(UP, factor=True))\n",
    "print(n.get(DOWN, factor=True))\n",
    "\n",
    "# 2. get the factor to obtain the uncertainty only (i.e., the relative unceratinty)\n",
    "# (this is, of course, more useful in case of multiple uncertainties, see below)\n",
    "print(\"\\nrelative factors:\")\n",
    "print(n.get(UP, factor=True, unc=True))\n",
    "print(n.get(DOWN, factor=True, unc=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also a few shorthands for the above methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.234\n",
      "1.434\n",
      "(0.2, 0.2)\n",
      "0.2\n"
     ]
    }
   ],
   "source": [
    "# __call__ is forwarded to get()\n",
    "print(n())\n",
    "print(n(UP))\n",
    "\n",
    "# u() is forwarded to get_uncertainty()\n",
    "print(n.u())\n",
    "print(n.u(direction=UP))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multiple uncertainties"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Let's create a number that has two uncertainties: `\"stat\"` and `\"syst\"`. The `\"stat\"` uncertainty is asymmetric, and the `\"syst\"` uncertainty is relative. Float and integer values are interpreted as absolute uncertainties, imaginary parts of complex numbers as relative ones (= just append `j`, e.g. `0.5j`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$8848.0 \\,^{+30.0}_{-20.0} \\left(\\text{stat}\\right) \\pm4424.0 \\left(\\text{syst}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112edc400, '8848.0 +30.0-20.0 (stat) +-4424.0 (syst)'>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n = Number(8848, {\n",
    "    \"stat\": (30, 20),  # absolute +30-20 uncertainty\n",
    "    \"syst\": 0.5j,      # relative +-50% uncertainty\n",
    "})\n",
    "n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to above, we can access the uncertainties and shifted values with [`get()`](https://scinum.readthedocs.io/en/latest/#scinum.Number.get) (or `__call__`) and [`get_uncertainty()`](https://scinum.readthedocs.io/en/latest/#scinum.Number.get_uncertainty) (or [`u()`](https://scinum.readthedocs.io/en/latest/#scinum.Number.u)). But this time, we can distinguish between the combined (in quadrature) value or the particular uncertainty sources:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "8848.0\n",
      "OrderedDict([('stat', (30.0, 20.0)), ('syst', (4424.0, 4424.0))])\n"
     ]
    }
   ],
   "source": [
    "# nominal value as before\n",
    "print(n.nominal)\n",
    "\n",
    "# get all uncertainties (stored absolute internally)\n",
    "print(n.uncertainties)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(4424.0, 4424.0)\n",
      "(30.0, 20.0)\n",
      "30.0\n"
     ]
    }
   ],
   "source": [
    "# get particular uncertainties\n",
    "print(n.u(\"syst\"))\n",
    "print(n.u(\"stat\"))\n",
    "print(n.u(\"stat\", direction=UP))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "8878.0\n",
      "4424.0\n",
      "13272.101716733014\n"
     ]
    }
   ],
   "source": [
    "# get the nominal value, shifted by particular uncertainties\n",
    "print(n(UP, \"stat\"))\n",
    "print(n(DOWN, \"syst\"))\n",
    "\n",
    "# compute the shifted value for both uncertainties, added in quadrature without correlation (default but configurable)\n",
    "print(n(UP))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, we can also access certain aspects of the uncertainties:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "factors for particular uncertainties:\n",
      "1.0033905967450272\n",
      "0.5\n",
      "\n",
      "factors for the combined uncertainty:\n",
      "1.500011496014129\n",
      "0.49999489062775576\n"
     ]
    }
   ],
   "source": [
    "print(\"factors for particular uncertainties:\")\n",
    "print(n.get(UP, \"stat\", factor=True))\n",
    "print(n.get(DOWN, \"syst\", factor=True))\n",
    "\n",
    "print(\"\\nfactors for the combined uncertainty:\")\n",
    "print(n.get(UP, factor=True))\n",
    "print(n.get(DOWN, factor=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also apply some nice formatting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "8848.0 +30.0-20.0 (stat) +-4424.0 (syst)\n",
      "8848.00 +30.00-20.00 (stat) +-4424.00 (syst)\n",
      "8848.00 +30.00-20.00 (stat) +-4424.00 (syst) m\n",
      "8848.00 +30.00-20.00 (stat) +4424.00-4424.00 (syst) m\n",
      "8.85 +0.03-0.02 (stat) +-4.42 (syst) x 1E3 m\n",
      "8.85 +0.03-0.02 (stat) +-4.42 (syst) km\n",
      "8848.00 ^{+30.00}_{-20.00} #left(stat#right) #pm4424.00 #left(syst#right) m\n",
      "8848.00 \\,^{+30.00}_{-20.00} \\left(\\text{stat}\\right) \\pm4424.00 \\left(\\text{syst}\\right)\\,m\n"
     ]
    }
   ],
   "source": [
    "print(n.str())\n",
    "print(n.str(\"%.2f\"))\n",
    "print(n.str(\"%.2f\", unit=\"m\"))\n",
    "print(n.str(\"%.2f\", unit=\"m\", force_asymmetric=True))\n",
    "print(n.str(\"%.2f\", unit=\"m\", scientific=True))\n",
    "print(n.str(\"%.2f\", unit=\"m\", si=True))\n",
    "print(n.str(\"%.2f\", unit=\"m\", style=\"root\"))\n",
    "print(n.str(\"%.2f\", unit=\"m\", style=\"latex\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configuration of correlations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's assume that we have a second measurement for the quantity `n` we defined above,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$8848.0 \\,^{+30.0}_{-20.0} \\left(\\text{stat}\\right) \\pm4424.0 \\left(\\text{syst}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112edc400, '8848.0 +30.0-20.0 (stat) +-4424.0 (syst)'>"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and we measured it with the same sources of uncertainty,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$8920.0 \\,^{+35.0}_{-15.0} \\left(\\text{stat}\\right) \\pm2676.0 \\left(\\text{syst}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ed8250, '8920.0 +35.0-15.0 (stat) +-2676.0 (syst)'>"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n2 = Number(8920, {\n",
    "    \"stat\": (35, 15),  # absolute +35-15 uncertainty\n",
    "    \"syst\": 0.3j,      # relative +-30% uncertainty\n",
    "})\n",
    "n2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Now, we want to compute the average measurement, including correct error propagation under consideration of sensible correlations. For more info on automatic uncertainty propagation, see the [subsequent section](#Automatic-uncertainty-propagation).\n",
    " \n",
    "In this example, we want to fully correlate the *systematic* uncertainty, whereas we can treat *statistical* effects as uncorrelated. However, just wirting `(n + n2) / 2` will consider equally named uncertainty sources to be 100% correlated, i.e., both `syst` and `stat` uncertainties will be simply averaged. This is the default behavior in scinum as it is not possible (nor wise) to *guesstimate* the meaning of an uncertainty from its name.\n",
    "\n",
    "While this approach is certainly correct for `syst`, we don't achieve the correct treatment for `stat`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$8884.0 \\pm3550.0 \\left(\\text{syst}\\right) \\,^{+32.5}_{-17.5} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef4070, '8884.0 +-3550.0 (syst) +32.5-17.5 (stat)'>"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(n + n2) / 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead, we need to define the correlation specifically for `stat`. This can be achieved in multiple ways, but the most pythonic way is to use a [`Correlation`](https://scinum.readthedocs.io/en/latest/#correlation) object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$8884.0 \\pm3550.0 \\left(\\text{syst}\\right) \\,^{+23.04886114323222}_{-12.500000000000002} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef4460, '8884.0 +-3550.0 (syst) +23.04886114323222-12.500000000000002 (stat)'>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(n @ Correlation(stat=0) + n2) / 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note** that the statistical uncertainty decreased as desired, whereas the systematic one remained the same.\n",
    "`Correlation` objects have a default value that can be set as the first positional, yet optional parameter, and itself defaults to one.\n",
    "\n",
    "Internally, the operation `n @ Correlation(stat=0)` (or `n * Correlation(stat=0)` in Python 2) is evaluated prior to the addition of `n2` and generates a so-called [`DeferredResult`](https://scinum.readthedocs.io/en/latest/#deferredresult). This object carries the information of `n` and the correlation over to the next operation, at which point the uncertainty propagation is eventually resolved. As usual, in situations where the operator precedence might seem unclear, it is recommended to use parentheses to structure the expression."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Automatic uncertainty propagation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's continue working with the number `n` from above.\n",
    "\n",
    "Uncertainty propagation works in a pythonic way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$9048.0 \\pm4424.0 \\left(\\text{syst}\\right) \\,^{+30.0}_{-20.0} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef46a0, '9048.0 +-4424.0 (syst) +30.0-20.0 (stat)'>"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n + 200"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$4424.0 \\pm2212.0 \\left(\\text{syst}\\right) \\,^{+15.0}_{-10.0} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef4880, '4424.0 +-2212.0 (syst) +15.0-10.0 (stat)'>"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n / 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$94.06380813043877 \\pm23.515952032609693 \\left(\\text{syst}\\right) \\,^{+0.15946622083596085}_{-0.10631081389064057} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ed8a60, '94.06380813043877 +-23.515952032609693 (syst) +0.15946622083596085-0.10631081389064057 (stat)'>"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n**0.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In cases such as the last one, formatting makes a lot of sense ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'94.06 +-23.52 (syst) +0.16-0.11 (stat)'"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(n**0.5).str(\"%.2f\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More complex operations such as `exp`, `log`, `sin`, etc, are provided on the `ops` object, which mimics Python's `math` module. The benefit of the `ops` object is that all its operations are aware of Gaussian error propagation rules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$9.088 \\,^{+0.003}_{-0.002} \\left(\\text{stat}\\right) \\pm0.500 \\left(\\text{syst}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef48e0, '9.088 +0.003-0.002 (stat) +-0.500 (syst)'>"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from scinum import ops\n",
    "\n",
    "# change the default format for convenience\n",
    "Number.default_format = \"%.3f\"\n",
    "\n",
    "# compute the log of n\n",
    "ops.log(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The propagation is actually performed simultaneously per uncertainty source."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$13848.000 \\pm5424.000 \\left(\\text{syst}\\right) \\,^{+30.000}_{-20.000} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef47f0, '13848.000 +-5424.000 (syst) +30.000-20.000 (stat)'>"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = Number(5000, {\"syst\": 1000})\n",
    "\n",
    "n + m"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$1.770 \\pm0.531 \\left(\\text{syst}\\right) \\,^{+0.006}_{-0.004} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef46d0, '1.770 +-0.531 (syst) +0.006-0.004 (stat)'>"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n / m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As described [above](#Configuration-of-correlations), equally named uncertainty sources are assumed to be fully correlated. You can configure the correlation in operations through `Correlation` objects, or by using explicit methods on the number object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$13848.000 \\pm4999.578 \\left(\\text{syst}\\right) \\,^{+30.000}_{-20.000} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112ef4dc0, '13848.000 +-4999.578 (syst) +30.000-20.000 (stat)'>"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# n.add(m, rho=0.5, inplace=False)\n",
    "\n",
    "# same as\n",
    "n @ Correlation(0.5) + m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you set `inplace` to `True` (the default), `n` is updated inplace."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$13848.000 \\pm4999.578 \\left(\\text{syst}\\right) \\,^{+30.000}_{-20.000} \\left(\\text{stat}\\right)$"
      ],
      "text/plain": [
       "<Number at 0x112edc400, '13848.000 +-4999.578 (syst) +30.000-20.000 (stat)'>"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n.add(m, rho=0.5)\n",
    "n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Rounding"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above examples used format strings such as `\"%.2f\"` or `\"%.3f\"` to enforce a certain amount of significant digits after the decimal point when the number is printed. Internally, this is done via [`round_value`](https://scinum.readthedocs.io/en/latest/#round-value) and [`round_uncertainty`](https://scinum.readthedocs.io/en/latest/#round-uncertainty) which provide a variety of automatic rounding options that are accepted by both [`Number.default_format`](https://scinum.readthedocs.io/en/latest/#scinum.Number.default_format) and [`Number.str()`](https://scinum.readthedocs.io/en/latest/#scinum.Number.str):\n",
    "\n",
    "- Format strings (e.g. `\"%.2f\"`) allow to round values and their uncertainties in a pythonic way.\n",
    "- Negative integers or 0 are interpreted similarly to format strings and control the number of significant digits *after* the decimal point. For instance, `-2` is identical to `\"%.2f\"`.\n",
    "- Positive integers define the total number of significant digits, evaluated on the smallest value across nominal and uncertainty values.\n",
    "\n",
    "In addition, there are three methods that implement uncertainty-based rounding rules:\n",
    "- `\"pdg\"`: Applies rounding rules defined by the [Particle Data Group](https://pdg.lbl.gov/2021/reviews/rpp2021-rev-rpp-intro.pdf#page=18) based on the values of the three leading significant digits.\n",
    "- `\"pdg+1\"`: Same as `\"pdg\"` with one additional digit.\n",
    "- `\"publication\"`: Same as `\"pdg+1\"` but it does not apply the rounding of values above 949 to 1000 (see the link above).\n",
    "\n",
    "All rounding rules are demonstrated below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.234 +-0.220 (a) +-0.533 (b) +-0.970 (c)\n"
     ]
    }
   ],
   "source": [
    "n = Number(1.234, {\"a\": 0.22, \"b\": 0.533, \"c\": 0.97})\n",
    "n\n",
    "print(n.str())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1.23 +-0.22 (a) +-0.53 (b) +-0.97 (c)'"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# format string\n",
    "n.str(\"%.2f\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1.23 +-0.22 (a) +-0.53 (b) +-0.97 (c)'"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# negative integer -> same as format string\n",
    "n.str(-2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1.2 +-0.2 (a) +-0.5 (b) +-1.0 (c)'"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# positive integer -> uses unc. \"c\" with the smallest value as reference and picks 1 digit\n",
    "n.str(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1 +-0 (a) +-1 (b) +-1 (c)'"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# zero -> integer rounding\n",
    "n.str(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.23 +-0.22\n",
      "1.2 +-0.5\n",
      "1.2 +-1.0\n"
     ]
    }
   ],
   "source": [
    "# \"pdg\" -> based on three leading digits of uncertainty\n",
    "print(Number(1.234, 0.22).str(\"pdg\"))\n",
    "print(Number(1.234, 0.53).str(\"pdg\"))\n",
    "print(Number(1.234, 0.97).str(\"pdg\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.234 +-0.220\n",
      "1.23 +-0.53\n",
      "1.23 +-1.00\n"
     ]
    }
   ],
   "source": [
    "# \"pdg+1\" -> \"pdg\" with one additional digit\n",
    "print(Number(1.234, 0.22).str(\"pdg+1\"))\n",
    "print(Number(1.234, 0.53).str(\"pdg+1\"))\n",
    "print(Number(1.234, 0.97).str(\"pdg+1\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.234 +-0.220\n",
      "1.23 +-0.53\n",
      "1.23 +-0.97\n"
     ]
    }
   ],
   "source": [
    "# \"publication\" -> \"pdg+1\" without rounding above 949 (third line)\n",
    "print(Number(1.234, 0.22).str(\"publication\"))\n",
    "print(Number(1.234, 0.53).str(\"publication\"))\n",
    "print(Number(1.234, 0.97).str(\"publication\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Export into different formats"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### yaml via HEPData"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`scinum.Number` objects can be serialized to yaml (json) through by using the format suggested by the [HEPData format](https://hepdata-submission.readthedocs.io/en/latest/data_yaml.html) for values that are attributed multiple uncertainties.\n",
    "\n",
    "The main idea is to register a *representer* to the [`yaml`](https://pypi.org/project/PyYAML) module that knows how a `scinum.Number` instance should be serialized."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "import yaml\n",
    "from scinum import create_hep_data_representer\n",
    "\n",
    "# add the representer\n",
    "yaml.add_representer(Number, create_hep_data_representer())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can simply pass any number instance to `yaml.dump`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "value: 1.234\n",
      "errors:\n",
      "- label: a\n",
      "  symerror: 0.220\n",
      "- label: b\n",
      "  asymerror:\n",
      "    plus: 0.533\n",
      "    minus: -0.617\n",
      "\n"
     ]
    }
   ],
   "source": [
    "n = Number(1.234, {\"a\": 0.22, \"b\": (0.533, 0.5j)})\n",
    "print(yaml.dump(n))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more info, checkout the [`create_hep_data_representer` documentation](https://scinum.readthedocs.io/#create-hep-data-representer)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}