{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _networkset:\n",
    "| \n",
    "|\n",
    "Download This Notebook: :download:`NetworkSet.ipynb`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# NetworkSet\n",
    "\n",
    "\n",
    "## Introduction\n",
    "\n",
    "\n",
    "\n",
    "The [NetworkSet](../api/networkSet.rst) object represents an unordered  set of networks. It \n",
    "provides  methods iterating and slicing the set, sorting by datetime, calculating statistical quantities, and displaying uncertainty bounds on plots. \n",
    "\n",
    "## Creating a [NetworkSet](../api/networkSet.rst)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets take a look in the `data/` folder, there are some redundant measurements of a network called `ro`,  which is a *radiating open* waveguide. "
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "ls data/ro*\n",
    "\n",
    "-a----       14/02/2021     12:35           8031 ro,1.s1p\n",
    "-a----       14/02/2021     12:35           8030 ro,2.s1p\n",
    "-a----       14/02/2021     12:35           8031 ro,3.s1p\n",
    "-a----       14/02/2021     12:35          46592 ro_spreadsheet.xls"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "raw_mimetype": "text/markdown"
   },
   "source": [
    "The files `ro,1.s1p` , `ro,2.s1p`, ...  are redundant measurements on \n",
    "which we would like to calculate statistics using the [NetworkSet](../api/networkSet.rst)\n",
    "class.\n",
    "\n",
    "A [NetworkSet](../api/networkSet.rst) is created from a list or dict of \n",
    "[Network](../api/network.rst)'s. So first we need to load all of the \n",
    "touchstone files into `Networks`. This can be done quickly with \n",
    "`rf.read_all`,  The argument `contains` is used to load only files \n",
    "which match a given substring. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import skrf as rf\n",
    "\n",
    "rf.read_all(rf.data.pwd, contains='ro')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be passed directly to the [NetworkSet](../api/networkSet.rst) constructor, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from skrf import NetworkSet \n",
    "\n",
    "ro_dict = rf.read_all(rf.data.pwd, contains='ro')\n",
    "ro_ns = NetworkSet(ro_dict, name='ro set') \n",
    "ro_ns"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A NetworkSet can also be constructed directly from a dir with `NetworkSet.from_dir()` or from a zipfile of touchstones through the class method `NetworkSet.from_zip()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing Network Methods \n",
    "The [Network](../api/network.rst) elements in a [NetworkSet](../api/networkSet.rst) can be accessed like the elements of list, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most [Network](../api/network.rst) methods are also methods of \n",
    "[NetworkSet](../api/networkSet.rst). These methods are called on each \n",
    "[Network](../api/network.rst) element individually. For example to \n",
    "plot the log-magnitude of the s-parameters of each Network."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "from pylab import *\n",
    "import skrf as rf\n",
    "rf.stylely()\n",
    "\n",
    "ro_ns.plot_s_db()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Statistical Properties\n",
    "\n",
    "\n",
    "Statistical quantities can be calculated by accessing \n",
    "properties of the NetworkSet. To calculate the complex \n",
    "average of the set, access the `mean_s` property"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.mean_s"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "    \n",
    ".. note:: \n",
    "\n",
    "    Because the statistical operator methods are generated upon initialization\n",
    "    their API is not explicitly documented in this manual. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    \n",
    "The naming convention of the statistical operator properties are `NetworkSet.{function}_{parameter}`, where `function` is the name of the \n",
    "statistical function, and `parameter` is the Network parameter to operate \n",
    "on. These methods return a [Network](../api/network.rst) object, so they can be \n",
    "saved or plotted in the same way as you would with a Network.\n",
    "To plot the log-magnitude of the complex mean response "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.mean_s.plot_s_db(label='ro')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or to plot the standard deviation of the complex s-parameters,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.std_s.plot_s_re(y_label='Standard Deviations')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using these properties it is possible to calculate statistical quantities on the scalar \n",
    "components of the complex network parameters. To calculate the \n",
    "mean of the phase component,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.mean_s_deg.plot_s_re()    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting Uncertainty Bounds\n",
    "\n",
    "\n",
    "Uncertainty bounds can be plotted through the methods "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.plot_uncertainty_bounds_s_db()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.plot_uncertainty_bounds_s_deg()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note::\n",
    "\n",
    "    The uncertainty bounds plotted above are calculated  **after** \n",
    "    the complex number has been projected onto the specified scalar component.\n",
    "    Thus, the first plot represents uncertainty in the magnitude component **only**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Reading and Writing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To write all [Network](../api/network.rst)s of a [NetworkSet](../api/networkSet.rst) out to individual touchstones,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.write_touchstone(dir='data/')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For temporary data storage, [NetworkSet](../api/networkSet.rst)s can be saved and read from disk \n",
    "using  the functions `rf.read` and `rf.write`\n",
    "\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rf.write('ro set.ns', ro_ns)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns = rf.read('ro set.ns')\n",
    "ro_ns"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Export to Excel, csv, or html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[NetworkSet](../api/networkSet.rst)s can also be exported to other filetypes. The format of the output; real/imag, mag/phase is adjustable, as is the output type; csv, excel, html. For example to export mag/phase for each network into an Excel spreadsheet for your boss[s]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ro_ns.write_spreadsheet('data/ro_spreadsheet.xls', form='db')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More info on this can be found in the function, `skrf.io.general.network_2_spreadsheet`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "celltoolbar": "Raw Cell Format",
  "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.7.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}