From c36dfba00151d49e93c9a32401f361959ebbb158 Mon Sep 17 00:00:00 2001 From: mlee03 Date: Mon, 13 Apr 2026 11:30:51 -0400 Subject: [PATCH 1/4] merge --- fre/gfdl_msd_schemas | 2 +- fre/mkmf | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fre/gfdl_msd_schemas b/fre/gfdl_msd_schemas index d5a42a3b4..2175868f9 160000 --- a/fre/gfdl_msd_schemas +++ b/fre/gfdl_msd_schemas @@ -1 +1 @@ -Subproject commit d5a42a3b423265262aefe9a4a6ba9add90d784ab +Subproject commit 2175868f9f7c9181fd9fdc69f74b1c1a1eab6a5e diff --git a/fre/mkmf b/fre/mkmf index a71029740..9830f1ac0 160000 --- a/fre/mkmf +++ b/fre/mkmf @@ -1 +1 @@ -Subproject commit a71029740c3ed13cdbfc3c89191b376e54971912 +Subproject commit 9830f1ac08566ec94e6b28555c921df28b6d0fea From a3fb87e268a7dbb3acba926084a873f3de5640b8 Mon Sep 17 00:00:00 2001 From: mlee03 Date: Mon, 13 Apr 2026 11:31:16 -0400 Subject: [PATCH 2/4] document click interfaces --- fre/analysis/freanalysis.py | 99 ++++++++++++++++++++++++++----------- 1 file changed, 71 insertions(+), 28 deletions(-) diff --git a/fre/analysis/freanalysis.py b/fre/analysis/freanalysis.py index 1863eae7e..ee1d5bcd0 100644 --- a/fre/analysis/freanalysis.py +++ b/fre/analysis/freanalysis.py @@ -1,6 +1,12 @@ -''' fre analysis ''' +""" +Module defining the `click `_ interfaces fo the following subcommands: +* fre analysis install [ARGS]: installs NOAA-GFDL/analysis-scripts package. If specified, + also installs the user-analysis-script plug-ins, and a venv virtual environment +* fre analysis list [ARGS]: lists all the installed user-analysis-script plug-ins +* fre analysis run [ARGS]: runs the user-analysis-script plug-in +* fre analysis uninstall [ARGS]: uninstalls the specified user-analysis-script plug-in +""" -# a third party package import logging import click @@ -18,54 +24,91 @@ @click.group(help=click.style(" - analysis subcommands", fg=(250, 154, 90))) def analysis_cli(): - """Entry point to fre analysis click commands.""" + """ + Click entrypoint to the command `fre analysis`. + """ + pass - -@analysis_cli.command() -@click.option("--url", type=str, required=True, help="URL of the github repository.") -@click.option("--name", type=str, required=False, help="Subdirectory to pip install.") -@click.option("--library-directory", type=str, required=False, - help="Path to a custom lib directory.") +@analysis_cli.command('install', short_help="Installs 'NOAA-GFDL'-based analysis-scripts") +@click.option("--url", type=str, required=True, help=""" + Github repository URL to the NOAA-GFDL/analysis-scripts package or to its fork/variants +""") +@click.option("--name", type=str, required=False, help=""" + Name of the user-analysis-script to pip install in addition as a plug-in. + If not specified, only the core analysis-scripts engine in + analysis_scripts/core/analysis_scripts will be installed +""") +@click.option("--library-directory", type=str, required=False, help=""" + venv target directory if installing the analysis-scripts + package in a venv virtual environment. If not provided, the analysis-script + package and the plug-ins will be installed in the current/default environment. +""") def install(url, name, library_directory): - """Installs an analysis package.""" + """ + Install the analysis-scripts package from the Github url. + If specified, install the user-analysis-script plug-ins. + If specified, create a venv environment + """ install_analysis_package(url, name, library_directory) @analysis_cli.command() -@click.option("--library-directory", type=str, required=False, - help="Path to a custom lib directory.") +@click.option("--library-directory", type=str, required=False, help=""" + venv target directory from which to list all installed user-analysis-script plug-ins +""") def list(library_directory): - """List available plugins.""" + """ + list all installed user-analysis-script plug-ins + """ plugins = list_plugins(library_directory) if plugins: - fre_logger.info("Installed analysis packages:\n") + fre_logger.info("Installed analysis plug-ins:\n") for plugin in plugins: fre_logger.info(plugin) else: - fre_logger.info("No analysis packages found.") + fre_logger.info("No analysis plug-ins were found.") @analysis_cli.command() -@click.option("--name", type=str, required=True, help="Name of the analysis script.") -@click.option("--catalog", type=str, required=True, help="Path to the data catalog.") -@click.option("--output-directory", type=str, required=True, - help="Path to the output directory.") -@click.option("--output-yaml", type=str, required=True, help="Path to the output yaml.") -@click.option("--experiment-yaml", type=str, required=True, help="Path to the experiment yaml.") -@click.option("--library-directory", type=str, required=False, - help="Path to a custom lib directory.") +@click.option("--name", type=str, required=True, help="Name of the user-analysis-script plug-in") +@click.option("--catalog", type=str, required=True, help="Path to the data catalog") +@click.option("--output-directory", type=str, required=True, help=""" + Path to the output directory where figures from the plug-in will be saved +""") +@click.option("--output-yaml", type=str, required=True, help=""" + Name of the output yaml file. A yaml file listing the paths to all the + generated images will be generated at the end of the run to the output-directory. +""" +@click.option("--experiment-yaml", type=str, required=True, help=""" + Path to the experiment yaml file containing the configurations required by the + user-analysis-script plug-in. Configurations must be specified under the key + analysis/name/required +""") +@click.option("--library-directory", type=str, required=False, help=""" + Path to the venv target directory if the analysis-script package was + installed in a virtual environment +""") def run(name, catalog, output_directory, output_yaml, experiment_yaml, library_directory): - """Runs the analysis script and writes the paths to the created figures to a yaml file.""" + """ + Runs the user-analysis-script plug-in and generates a yaml file + cataloging the paths to the generated figures + """ run_analysis(name, catalog, output_directory, output_yaml, experiment_yaml, library_directory) @analysis_cli.command() -@click.option("--name", type=str, required=True, help="Name of package to uninstall.") -@click.option("--library-directory", type=str, required=False, - help="Path to a custom lib directory.") +@click.option("--name", type=str, required=True, help=""" + Name of user-analysis-script plug-in to uninstall. +""") +@click.option("--library-directory", type=str, required=False, help=""" + Path to the venv target directory if the user-analysis-script plug-in + was installed in a virtual environment +""") def uninstall(name, library_directory): - """Uninstall an analysis package.""" + """ + Uninstall user-anlaysis-script plug-in + """ uninstall_analysis_package(name, library_directory) From 591f878bd67dee43f29a1c175e683f0092c21400 Mon Sep 17 00:00:00 2001 From: mlee03 Date: Mon, 13 Apr 2026 11:36:10 -0400 Subject: [PATCH 3/4] revert gfdl_msd_schemas and mkmf --- fre/gfdl_msd_schemas | 2 +- fre/mkmf | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fre/gfdl_msd_schemas b/fre/gfdl_msd_schemas index 2175868f9..d5a42a3b4 160000 --- a/fre/gfdl_msd_schemas +++ b/fre/gfdl_msd_schemas @@ -1 +1 @@ -Subproject commit 2175868f9f7c9181fd9fdc69f74b1c1a1eab6a5e +Subproject commit d5a42a3b423265262aefe9a4a6ba9add90d784ab diff --git a/fre/mkmf b/fre/mkmf index 9830f1ac0..a71029740 160000 --- a/fre/mkmf +++ b/fre/mkmf @@ -1 +1 @@ -Subproject commit 9830f1ac08566ec94e6b28555c921df28b6d0fea +Subproject commit a71029740c3ed13cdbfc3c89191b376e54971912 From 6f9e59fc7303bb95879e65714622f5deaa28ad95 Mon Sep 17 00:00:00 2001 From: mlee03 Date: Mon, 13 Apr 2026 11:47:03 -0400 Subject: [PATCH 4/4] something better? --- fre/analysis/freanalysis.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/fre/analysis/freanalysis.py b/fre/analysis/freanalysis.py index ee1d5bcd0..3a22ec819 100644 --- a/fre/analysis/freanalysis.py +++ b/fre/analysis/freanalysis.py @@ -1,10 +1,15 @@ """ -Module defining the `click `_ interfaces fo the following subcommands: +The package analysis-scripts (https://github.com/NOAA-GFDL/analysis-scripts.git) contains +user-defined analysis scripts/plug-ins and the core engine to run the scripts/plug-ins. +This module defines the Click `fre analysis` command and the following subcommands to interface +with the analysis-scripts package: * fre analysis install [ARGS]: installs NOAA-GFDL/analysis-scripts package. If specified, also installs the user-analysis-script plug-ins, and a venv virtual environment * fre analysis list [ARGS]: lists all the installed user-analysis-script plug-ins * fre analysis run [ARGS]: runs the user-analysis-script plug-in * fre analysis uninstall [ARGS]: uninstalls the specified user-analysis-script plug-in + + """ import logging @@ -32,7 +37,8 @@ def analysis_cli(): @analysis_cli.command('install', short_help="Installs 'NOAA-GFDL'-based analysis-scripts") @click.option("--url", type=str, required=True, help=""" - Github repository URL to the NOAA-GFDL/analysis-scripts package or to its fork/variants + Github repository URL to the NOAA-GFDL/analysis-scripts package or to its fork/variants. + For example, url = https://github.com/NOAA-GFDL/analysis-scripts.git """) @click.option("--name", type=str, required=False, help=""" Name of the user-analysis-script to pip install in addition as a plug-in.