From c38e521d6e86828b2dc07700bb31218180380f7d Mon Sep 17 00:00:00 2001
From: Raymond Menzel <Raymond.Menzel@noaa.gov>
Date: Wed, 31 Jul 2024 10:58:07 -0400
Subject: [PATCH] add to the readme

---
 README.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 111 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 260c8d3..1d81aa8 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,9 @@ $ cd freanalysis_clouds; pip install .; cd ..
 $ cd freanalysis_radiation; pip install .; cd ..
 ```
 
-# Running an analysis plugin
+### For Workflow Developers
+
+#### Running an analysis plugin
 In order to run a plugin, you must first create a data catalog and can then perform
 the analysis:
 
@@ -57,3 +59,111 @@ reqs = plugin_requirements(name)
 print(reqs)
 run_plugin(name, "catalog.json", "pngs")
 ```
+
+### For Analysis Script Developers
+
+### How to use this framework.
+The idea behind ths framework is to treat each analysis script as a plugin, which can
+be discovered dynamically by the workflow.  Each analysis script is expected to be
+its own fully developed python package, which has a name that starts with
+`freanalysis_`.  At runtime, the workflow will search through all of its installed
+python packages, looking specifically for packages whose names begin with
+`freanalysis_`.  It will then search each of these found `freanalysis_` packages
+for a class that inherits from the `AnalysisScript` base class provided by the
+`analysis_scripts` package, and attempt to construct one of these objects.
+
+### Creating A New Analysis Script For This Framework.
+A python package is a directory that contains an `__init__.py` file.  In this example,
+we will make a new analysis script called `freanalysis_readme_example`.  To do this,
+let's setup up a directory:
+
+```bash
+freanalysis_readme_example
+  -- README.md  # Explain what this analysis script does.
+  -- pyproject.toml  # Tell python how to build/install this analysis script.
+  -- freanalysis_readme_example  # This directory is the actual python package.
+     -- __init__.py  # This file makes its parent directory a python package.
+```
+
+Once we have this directory tree, we can fill in the necessary files.
+
+
+##### README.
+
+
+##### pyproject.toml
+
+
+##### Defining the analysis script class
+Custom analysis scripts classes can be created that inherit the `AnalysisScript` base
+class provided by the `analysis_scripts` package.  Override its contructor,
+`requires`, and `run_analysis` methods. For example:
+
+```python3
+from analysis_scripts import AnalysisScript
+
+
+class NewAnalysisScript(AnalysisScript):
+    """Analysis script for some task.
+
+    Attributes:
+       description: Longer form description for the analysis.
+       title: Title that describes the analysis.
+    """
+    def __init__(self):
+        """Instantiates an object.  The user should provide a description and title."""
+        self.description = "This analysis does something cool."
+        self.title = "Brief, but descriptive name for the analysis."
+
+    def requires(self):
+        """Provides metadata describing what is needed for this analysis to run.
+
+        Returns:
+            A json string describing the metadata.
+        """
+        return json.dumps({
+            "settings": {
+                "activity_id": "<fill this>",
+                "institution_id": "<fill this>",
+                "source_id": "<fill this>",
+                "experiment_id": "<fill this>",
+                "frequency": "<fill this>",
+                "modeling_realm": "<fill this>",
+                "table_id": "<fill this>",
+                "member_id": "<fill this>",
+                "grid_label": "<fill this>",
+                "temporal_subset": "<fill this>",
+                "chunk_freq": "<fill this>",
+                "platform": "<fill this>",
+                "cell_methods": "<fill this>"
+            },
+            "dimensions": {
+                # These are just examples, you can put more/different ones.
+                "lat": {"standard_name": "latitude"},
+                "lon": {"standard_name": "longitude"},
+                "time": {"standard_name": "time"}
+            },
+            "varlist": {
+                "<fill this>": {
+                    "standard_name": "<a standard name>",
+                    "units": "<some units>",
+                    "dimensions": ["time", "lat", "lon"]
+                }, 
+            }
+        })
+
+    def run_analysis(self, catalog, png_dir, reference_catalog=None):
+        """Runs the analysis and generates all plots and associated datasets.
+
+        Args:
+            catalog: Path to a model output catalog.
+            png_dir: Directory to store output png figures in.
+            reference_catalog: Path to a catalog of reference data.
+
+        Returns:
+            A list of png figures.
+        """
+        Do some stuff to create the figures.
+        return ["figure1.png", "figure2.png",]
+```
+