diff --git a/docs/tutorials/yieldplotlib_tutorial.ipynb b/docs/tutorials/yieldplotlib_tutorial.ipynb index 9cd749f8..b124f2e4 100644 --- a/docs/tutorials/yieldplotlib_tutorial.ipynb +++ b/docs/tutorials/yieldplotlib_tutorial.ipynb @@ -4,22 +4,30 @@ "cell_type": "markdown", "id": "b89e4e327f4c602", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "# Getting started with yieldplotlib\n", "\n", "## Introduction\n", - "This tutorial will walk you thorugh some of the basic functionality of yieldplotlib to get you started on generating your own yield visualizations. To run yieldplotlib you need to have at least one AYO output folder, EXOSIMS output folder, or yield input package (YIP). Sample data has been provided in the tutorials folder of this repository for demonstrative purposes. \n", + "This tutorial will walk you through some of the basic functionality of `yieldplotlib` to get you started on generating your own yield visualizations.\n", "\n", - "You can also run series of pre-made plots for yield outputs which can be found in the yieldplotlib/src/scripts folder, or accessed through the yieldplotlib pipeline and command line interface." + "`yieldplotlib` is designed to standardize outputs from different mission simulation tools (currently AYO and EXOSIMS) into a single, unified format. This allows you to write a plotting script once and apply it to results from entirely different yield calculators without changing your code and it facilitates easy comparisons between the tools.\n", + "\n", + "To run yieldplotlib you need to have at least one AYO output folder, EXOSIMS output folder, or yield input package (YIP). Sample data has been provided in the tutorials folder of this repository for demonstrative purposes. You can also run series of pre-made plots for yield outputs which can be found in the `yieldplotlib/src/scripts` folder, or accessed through the yieldplotlib pipeline and command line interface." ] }, { "cell_type": "markdown", "id": "bd81add72b0061c8", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "### Imports" @@ -30,7 +38,10 @@ "execution_count": null, "id": "45b087e4efb1fd2f", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -49,7 +60,10 @@ "cell_type": "markdown", "id": "caac767705351567", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "### Loading Yield Data" @@ -59,17 +73,13 @@ "cell_type": "markdown", "id": "6ee6ec87b52bdf5", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ - " Yieldplotlib uses a key map to equate parameters between EXOSIMS and AYO (and\n", - " potential future yield codes). This key map is pulled daily from a collaborative Google Sheet to the GitHub repository in the form of a key_map.csv file. To see all the possible named parameters that can be plotted in yieldplotlib, consult documentation or the first column of that CSV file/Google Sheet. \n", - "\n", - "In order to convert this CSV to the key_map.py file that is needed by yieldplotlib to parse the yield output directories, the user should run:\n", - "\n", - "`python generate_key_map.py --csv key_map.csv`\n", - "\n", - "This will populate a key_map.py file containing all the proper mappings. Now we can load our sample AYO and EXOSIMS data using the AYODirectory and EXOSIMSDirectory classes. " + "We can load our sample AYO and EXOSIMS data using the `AYODirectory` and `EXOSIMSDirectory` classes. These classes parse the output directories and prepare them for querying." ] }, { @@ -77,7 +87,10 @@ "execution_count": null, "id": "f81af9f7cf0da38f", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -99,7 +112,10 @@ "cell_type": "markdown", "id": "bfb770276dd32058", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "Now that we have loaded our directories, we can display the file structure to see what is contained in our yield outputs at a glance." @@ -110,7 +126,10 @@ "execution_count": null, "id": "923b00fc669a6ffb", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -119,11 +138,58 @@ "print(ayo.display_tree())" ] }, + { + "cell_type": "markdown", + "id": "861b7c81-de98-456f-81a0-f0b83a1b9a72", + "metadata": {}, + "source": [ + "### The Common Parameter Interface\n", + "\n", + "A core feature of `yieldplotlib` is the standardized set of \"Common Parameters\" that can be accessed. These parameters pull the same data from different yield codes without requiring a user to parse the underlying files and keys themself.\n", + "\n", + "The interactive table below lists the **currently supported parameters** available for querying. You can use the **search** box to filter by keyword (e.g., try typing \"magnitude\", \"yield\", or \"coronagraph\") to find the specific key you need for your plots.\n", + "\n", + "> **Note:** For a static version of this table see the [Common Parameters](https://yieldplotlib.readthedocs.io/en/latest/user/ypl_parameters.html) documentation page. To learn more about how this works see [Parsing and Getting Values](https://yieldplotlib.readthedocs.io/en/latest/user/functionality.html#parsing-and-getting-values)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e3f56eb3-a4cb-445a-944f-37b71a1b4953", + "metadata": {}, + "outputs": [], + "source": [ + "import io\n", + "\n", + "import pandas as pd\n", + "from itables import show\n", + "\n", + "\n", + "def read_markdown_table(filepath):\n", + " \"\"\"Parses our markdown table file into a Pandas DataFrame.\"\"\"\n", + " with open(filepath, \"r\") as f:\n", + " lines = f.readlines()\n", + " clean_lines = [line for line in lines if \"|\" in line and \"---\" not in line]\n", + " clean_data = \"\".join(clean_lines)\n", + " df = pd.read_csv(io.StringIO(clean_data), sep=\"|\", engine=\"python\")\n", + " df = df.dropna(axis=1, how=\"all\")\n", + " df.columns = [c.strip() for c in df.columns]\n", + " df = df.apply(lambda x: x.str.strip() if x.dtype == \"object\" else x)\n", + " return df\n", + "\n", + "\n", + "df_params = read_markdown_table(\"../user/parameters_table.md\")\n", + "show(df_params, classes=\"display\", paging=True, pageLength=10)" + ] + }, { "cell_type": "markdown", "id": "8e287d82caf8accd", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "## Accessing Data and Generating Plots \n", @@ -135,7 +201,10 @@ "cell_type": "markdown", "id": "6d27983ef5d390ab", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "### Get Data\n", @@ -147,7 +216,10 @@ "execution_count": null, "id": "c22892b22576bae", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -171,7 +243,10 @@ "cell_type": "markdown", "id": "14e148aa68cba687", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "### Generic Plots\n", @@ -184,7 +259,10 @@ "execution_count": null, "id": "9848320da4a411e2", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -202,7 +280,10 @@ "execution_count": null, "id": "b712b4a604d5cf5d", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -225,7 +306,10 @@ "cell_type": "markdown", "id": "f62480670fdc03c8", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "### Comparative Plots \n", @@ -238,7 +322,10 @@ "execution_count": null, "id": "13e53cfbbf318e11", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -263,7 +350,10 @@ "execution_count": null, "id": "d6ede430c07c5414", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -287,7 +377,10 @@ "cell_type": "markdown", "id": "cbf12f506d0d1557", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "Additionally, we can run more complex analyses on multi-dimensional grids of parameter space. " @@ -298,7 +391,10 @@ "execution_count": null, "id": "38186179426470c9", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -318,7 +414,10 @@ "execution_count": null, "id": "c452127a5b50e954", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -358,7 +457,10 @@ "cell_type": "markdown", "id": "c9a2e936b8bd79c", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "## Yield Input Package (YIP) Loading\n", @@ -370,7 +472,10 @@ "execution_count": null, "id": "3c9ee00316d2d052", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -386,7 +491,10 @@ "execution_count": null, "id": "18d118815a6dec94", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -400,7 +508,10 @@ "execution_count": null, "id": "2641102799748c28", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -415,7 +526,10 @@ "cell_type": "markdown", "id": "30c0064b1e73dc3e", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "source": [ "## Checking Accessibility \n", @@ -429,7 +543,10 @@ "execution_count": null, "id": "29999f4e17f11066", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -451,7 +568,10 @@ "execution_count": null, "id": "cac3049a41737280", "metadata": { - "collapsed": false + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } }, "outputs": [], "source": [ @@ -475,21 +595,13 @@ "am = AccessibilityManager(ax)\n", "am.run_checks()" ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e3f56eb3-a4cb-445a-944f-37b71a1b4953", - "metadata": {}, - "outputs": [], - "source": [] } ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "yieldplotlib", "language": "python", - "name": "python3" + "name": "ypl" }, "language_info": { "codemirror_mode": { diff --git a/pyproject.toml b/pyproject.toml index 404a6dff..f3dcacc2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,6 +60,7 @@ docs = [ "sphinx-autoapi", "sphinx_autodoc_typehints", "matplotlib", + "itables", ] test = ["nox", "pytest", "pytest-cov"]