{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Reading/Writing RMEMeas Objects\n\nThis is a basic example demonstrating how to read and write a RMEMeas object.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Creating an Object\nFirst lets create an object that we want to save.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from rmellipse.uobjects import RMEMeas\n\nimport xarray as xr\nimport numpy as np\n\nnom = xr.DataArray(np.zeros((10, 2)),\n                   dims=('d1', 'd2'),\n                   coords={'d1': np.arange(10),\n                           'd2': np.arange(2)})\n\nmeas = RMEMeas.from_nom(name='meas', nom=nom)\n\nmeas.add_umech(\n    name='mymechanisms',\n    value=meas.nom + np.ones(meas.nom.shape) * 0.01,\n    dof=np.inf,\n    category={'Type': 'B', 'Origin': 'Data Sheet'},\n    add_uid=True\n)\n\nfor i in range(100):\n    meas.add_mc_sample(meas.nom + np.random.rand(*meas.nom.shape) * 0.01)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## HDF5 Saving\n\nSaving to HDF5 is the recommended format for saving RMEMeas objects.\nCompared to xml, it's much faster and preserves category and degree\nof freedom information about the object. In addition, the HDF5 format doesn't\nrequire you to define a data format with to_csv and from_csv functions.\n\nTo save, open an HDF5 file or group and pass that to the\n:func:`rmellipse.uobjects.RMEMeas.to_h5` function. The RMEMeas object\nwill be stored in the group you provide it under a group with it's name.\nThe override argument tells the function to delete any pre-existing\ngroups with that RMEMeas objects name then try to save it, to avoid\npermission errors.\n\nWe recommend downloading the HDF5 viewer software. You can inspect your\nHDF5 object, and you will see that under the 'myval' group this creates, you\nwill see the cov,mc,covdofs, and covcats attributes stored. Each one is an\nHDF5 representation of an xarray DataArray and together completely describe\nyour RMEMeas object.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import h5py\nwith h5py.File('meas.hdf5', 'a') as f:\n    meas.to_h5(f, override=True)\n    print(f[meas.name])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## HDF5 Reading\n\nYou can open the HDF5 file you made in read mode,\nthen pass in the group with it's name to\n:func:`rmellipse.uobjects.RMEMeas.from_h5` in order to read it.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "with h5py.File('meas.hdf5', 'r') as f:\n    meas = RMEMeas.from_h5(f['meas'])\n    print(meas)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## XML Saving\n\nXML format is a legacy format inherited from the original drag and\ndrop menu Microwave Uncertainty Framework. It is included for backwards compatibility purposes, but it is\nnot the recommended way to save if you can help it. Specifically be aware\nthat saving data to XML you will lose degrees of freedom and category information\nabout\nyour linear uncertainty mechanisms. The default degrees of freedom for linear uncertainties\nis infinite, and the default category for uncertainties is type B. So\nif you save to XML then read it back in, all your mechanisms will default\nto both of those properties. To preserve categories and degrees of freedom\nyou assigned, use HDF5. Additionally, it is much slower than the\nHDF5 format.\n\nTo save to XML you need to define a read/write functions.\n\nFirst we turn our object into the s1p_ri format using the\n:func:`rmellipse.dataformats.as_format`\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from rmellipse.propagators import RMEProp\n\ndef to_txt(data, path):\n        np.savetxt(path, data.values, delimiter=',')\n\ndef from_txt(path):\n    values = xr.DataArray(np.loadtxt(path, float, delimiter=','))\n    return values\n\nm1 = RMEMeas.from_nom('mymeas', xr.DataArray(np.zeros((2,2))))\nm1.add_umech('my umech', m1.nom.copy()+0.1)\n\nm1.to_xml(\n    '.',\n    to_txt,\n    data_extension='.csv',\n    header_extension='.meas'\n)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Once we have our measurement in a format with read/write functions defined\nwe can use the :func:`rmellipse.uobjects.RMEMeas.to_xml` and\n:func:`rmellipse.uobjects.RMEMeas.from_xml` functions.\n\n:func:`rmellipse.uobjects.RMEMeas.to_xml` is expecting a target directory\nto save the measurement\nin. It will save a header '.meas' file and a '..._Support'\nin that directory with the covariance and Monte Carlo data next to it. Both will be\nnamed using the RMEMeas object's name attribute. When a RMEMeas object is\npassed\nthrough a function, it's name attribute is changed to the name of that\nfunction.\nSo, be sure to change the name attribute to something useful if the function\nname\nis not specific enough.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "m2 = RMEMeas.from_xml(\n    'mymeas.meas',\n    from_csv=from_txt\n)\nassert (m2.cov.values == m1.cov.values).all()"
      ]
    }
  ],
  "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
}