{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# RMEMeas Objects\n\nThis is a basic example demonstrating how to create and use RMEMeas objects. In this\nexample we go over different ways to initialize one from scratch,\nhow to create linear uncertainty mechanisms, and how to create probability\ndistributions for Monte Carlo analysis. Indexing and interpolating are also\nbriefly discussed.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Initializing from a Nominal Data Set\n\nThe easiest - and most versatile - way to make a RMEMeas object from scratch is to\nuse the :func:`rmellipse.uobjects.RMEMeas.from_nom` function, then\nadd the uncertainty mechanisms and Monte Carlo data.\nWith this function you just provide a nominal data set and a name for\nyour object. The name is used when saving to formats like xml and hdf5.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from rmellipse.uobjects import RMEMeas\nimport xarray as xr\nimport numpy as np\n\nnom = xr.DataArray(\n\t[[1, 2, 3], [4, 5, 6]],\n\tdims=('d1', 'd2'),\n\tcoords={'d1': [0.1, 0.2], 'd2': ['a', 'b', 'c']},\n)\n\nmeas = RMEMeas.from_nom(name='myval', nom=nom)\nprint(meas.nom)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "-----------------------\n\nThen we can manually add linear uncertainty mechanisms, defining the degrees\nof freedom and categorizing the mechanisms as we go. The\n:func:`rmellipse.uobjects.RMEMeas.add_umech` function\nis expecting the value to be the same shape, dimensions, and coordinates of the\nnominal. It is easiest to use the `nom` attribute of your object, then perturb\nit 1 standard uncertainty.\nThis example adds a linear uncertainty mechanism with infinite degrees of\nfreedom, because\nit comes from an external source we trust, and perturbs each element in the\nnominal data set by 0.001.\nWe also add a unique ID to the mechanism name, because we want to be sure\nthat this mechanism will be fully independent in the event someone\nuses it with other uncertainty objects they might create in their own\nscripts. We also categorize it as Type B and categorize it's origin from\na data sheet so we can group this mechanism down the road with mechanisms\nfrom similar sources.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "meas.add_umech(\n\tname='My Uncertainty Mechanism',\n\tvalue=meas.nom + np.ones(meas.nom.shape) * 0.01,\n\tdof=np.inf,\n\tcategory={'Type': 'B', 'Origin': 'Data Sheet'},\n\tadd_uid=True,\n)\nprint(meas.stdunc(k=1).cov)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "For linear uncertainties can calculate degrees of freedom\nassociated with each measurand.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(meas.dof())\n\n# Calculate uncertainty bounds for a given expansion factor\n# (nominal + k * standard uncertainty).\nprint(meas.uncbounds(k=1).cov)\n\n# And estimate confidence intervals.\nprint(meas.confint(0.95))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Monte Carlo Distributions\n\nWe also sample from a random distribution to add samples for use\nin Monte Carlo uncertainty analysis using\n:func:`rmellipse.uobjects.RMEMeas.add_mc_sample`. It is expecting a DataArray\nwith the same dimensions and coordinates as the nominal.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "for i in range(100):\n\tmeas.add_mc_sample(meas.nom + np.random.normal(*meas.nom.shape) * 0.01)\n\nprint(meas.stdunc(k=1).mc)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We can also calculate uncertainty bounds for a given expansion factor\n(nominal + k * standard uncertainty).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(meas.uncbounds(k=1).cov)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Indexing\n\nRMEMeas objects support xarray style indexing, which allows for label based\nindexing into arrays (like pandas) and integer based indexing into arrays\n(like numpy).The cov/mc attributes of the newly\ncreated RMEMeas object will be views on the original. Call RMEMeas.copy()\nto turn the view into it's own measurement.\n\nImportantly, when indexing into a RMEMeas array with xarray like functions (\n__getitem__ , loc, sel, and isel) you index into the RMEMeas object as if you\nwere indexing into the nominal value. These functions, when called on the\nRMEMeas object, will always keep all the linear uncertainty mechanisms or\nMonte Carlo samples.\n\nPlease refer to the xarray documentation for more details on how to use\nthese indexing functions.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print('Inspect the nominal to see the dimensions and coordinates to index')\nprint(meas.nom.shape)\nprint(meas.nom.dims)\nprint(meas.nom.coords, '\\n')\n\n\nprint('positional lookup by integer')\nprint(meas[0, 0], '\\n')\n\nprint('positional lookup by label')\nprint(meas.loc[0.1, 'a'], '\\n')\n\nprint('named lookup by integer')\nprint(meas.isel(d1=0, d2=0), '\\n')\n\nprint('named lookup by label')\nprint(meas.sel(d1=0.1, d2='a'), '\\n')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Indexing Covariance and Monte Carlo Data\n\nIf you wish to get a view into specific uncertainty mechanisms, or specific\nsamples in the Monte Carlo distribution, then use the function `usel`.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# This example throws away the montecarlo samples and looks only at a single\n# linear uncertainty mechanism.\nmech = meas.usel(umech_id=meas.umech_id[0], mcsamples=[])\n\nlinunc, mcunc = mech.stdunc(k=1)\nprint(linunc)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We can also look a one or more of the Monte Carlo samples\nby throwing away the covariance data and just keeping one of the Monte Carlo\nsamples.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "sample = meas.usel(umech_id=[], mcsamples=[1])\n\nprint(sample.mc[1, ...])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "While the xarray indexing methods index across uncertainty mechanisms and\nMonte Carlo samples, the usel method indexes into uncertainty mechanisms\nand Monte Carlo samples. In either case, the nominal values (the 'nominal'\nparameter location and 0th Monte Carlo sample) are always protected and\nalways kept regardless of method.\n\nFor example, using usel and giving empty lists for umech_id\nand mcsamples throws away all the uncertainty information, and just keeps\nthe nominal. This effectively means it no longer has any associated\nuncertainties.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "nominal_only = meas.usel(umech_id=[], mcsamples=[])\n\nprint(nominal_only.nom)\nprint(nominal_only.stdunc())"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Assigning RMEMeas\n\nCurrently, RMEMeas objects indexing functions do not support item assignment.\nValues can be reassigned through propagation.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "try:\n\tmeas[0] = 1\nexcept TypeError as e:\n\tprint(e)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Interpolating\n\nRMEMeas supports interpolation by wrapping xarray's built in `interp` function.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(meas.interp(d1=[0.125, 0.15, 0.175]))"
      ]
    }
  ],
  "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.13.3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}