{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Experiment Parameters\n\nExperiment Parameters are a type safe markup language\nthat utilizes CSV files to described arbitrarily nested\ndictionaries. Experiment parameters are always a dictionary,\nbut may contain lists and other dictionaries.\n\nExperiment parameters support ``bool``, ``str``, ``int``,\nand ``float`` types. The string stored int he csv is cast\ninto this type when read in. The type must be declared.\n\nA header line is required of the form ``key_1,value,type,comment``.\nFor nested dictionaries, add additional key columns. The key values\nproceeding the value column designate the path to access the\nvalue in the dictionary.\n\nSingle comment lines with a leading ``#`` can be inserted to organize related\nblocks of parameters.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from rminstr.data_structures import ExptParameters\nfrom pathlib import Path\n\n# lets create a csv file\n# and write it to a file\nmy_csv_1 = \"\"\"key_1,value,type,comment\nname,reader,str,name of person\nage,1,int,age of read\n# comment lines can be added for clarity\nheight,5.11,float,height of person\ntruthy,True,bool,is this person truthy\"\"\"\n\nfile_path = Path('outputs/parameters_0.csv')\n\nwith open(file_path, 'w') as f:\n    f.write(my_csv_1)\n\n# we can read it back in\nparameters = ExptParameters(file_path)\n\nassert parameters['height'] == 5.11"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Nested Keys\nCreate more key columns in the header\nto create nested structures.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "my_csv_1 = \"\"\"key_1,key_2,value,type,comment\nobject,attribute,value,str,some nested value\"\"\"\n\nfile_path = Path('outputs/parameters_1.csv')\n\nwith open(file_path, 'w') as f:\n    f.write(my_csv_1)\n\n# we can read it back in\nparameters = ExptParameters(file_path)\n\nassert parameters['object']['attribute'] == 'value'"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Lists\nRepeating a key will create a list ordered\nfrom top to bottom.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# this creates a list of length two\n# under the key ``item``\nmy_csv_1 = \"\"\"key_1,value,type,comment\nitem,value,str,index 0\nitem,another_value,str,index 1\"\"\"\n\nfile_path = Path('outputs/parameters_2.csv')\n\nwith open(file_path, 'w') as f:\n    f.write(my_csv_1)\n\n# we can read it back in\nparameters = ExptParameters(file_path)\n\nassert len(parameters['item']) == 2"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## File Composition\nDictionaries can be composed of multiple\nfiles, and will be recursively merged in the order\nprovided.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "files = [\n    'outputs/parameters_0.csv',\n    'outputs/parameters_1.csv',\n    'outputs/parameters_2.csv',\n]\n\nparameters = ExptParameters(file_path)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Run Settings\nIn addition to configuration files, ``ExperimentParameters``\ncan take in a csv of settings that defines a set\niterable parameters (like a frequency list). The\nobject can be iterated over to track your position in a\nmeasurement. Unless specified, run_settings are assumed\nto be float values.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "my_run_settings = \"\"\"frequency (GHz),voltage (V)\n1.0, 0.1\n2.0, 0.2\n3.0, 0.3\"\"\"\n\nrun_settings = Path('outputs/my_run_settings.csv')\nwith open(run_settings, 'w') as f:\n    f.write(my_run_settings)\n\nparameters = ExptParameters(files, run_settings_file=run_settings)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The columns of the run settings are accesible\ninside the parameters as if they were\npart of the configuration, adjusted as you advance\nthrough the loop.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "parameters.advance()\n\n# iterate till complete\nwhile not parameters.complete():\n    this_voltage = parameters['voltage (V)']\n\n    # advance to next step\n    parameters.advance()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Saving\nParameters and run settings can be saved for record purposes.\nConfig files will be saved to a single file.\nComments are no preserved.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "parameters.save_config('outputs/config_copy.csv')\nparameters.save_run_settings('outputs/run_settings_copy.csv')"
      ]
    }
  ],
  "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.12.4"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}