From 2d359d5390cd975cff1618e105652d692623f6e4 Mon Sep 17 00:00:00 2001 From: Corey Spohn Date: Thu, 4 Dec 2025 15:43:09 -0500 Subject: [PATCH 1/2] feat: Add searchable common parameter table to the tutorial --- docs/tutorials/yieldplotlib_tutorial.ipynb | 206 ++++++++++++++++----- pyproject.toml | 1 + 2 files changed, 160 insertions(+), 47 deletions(-) diff --git a/docs/tutorials/yieldplotlib_tutorial.ipynb b/docs/tutorials/yieldplotlib_tutorial.ipynb index 9cd749f8..28196d14 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 \"flux\") 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"] From ca5e85d0dfa398f617704b96ebe2e97a5ec473cb Mon Sep 17 00:00:00 2001 From: Corey Spohn Date: Thu, 4 Dec 2025 16:00:27 -0500 Subject: [PATCH 2/2] chore: fixing text because I forgot we don't have any flux stuff --- docs/tutorials/yieldplotlib_tutorial.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/yieldplotlib_tutorial.ipynb b/docs/tutorials/yieldplotlib_tutorial.ipynb index 28196d14..b124f2e4 100644 --- a/docs/tutorials/yieldplotlib_tutorial.ipynb +++ b/docs/tutorials/yieldplotlib_tutorial.ipynb @@ -147,7 +147,7 @@ "\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 \"flux\") to find the specific key you need for your plots.\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)." ]