update

ESMBenchmarkViz/taylor_diagram/taylor_diagram.py

@@ -2,7 +2,9 @@
 
 import numpy as np
 from bokeh.models import ColumnDataSource, HoverTool, Label, LabelSet
-from bokeh.palettes import Spectral10
+#from bokeh.palettes import Spectral10
+from bokeh.palettes import all_palettes
+
 from bokeh.plotting import figure, show
 from bokeh.transform import factor_cmap
 
@@ -16,7 +18,7 @@ def taylor_diagram(
     refstd,
     normalize=False,
     step=0.2,
-    palette=Spectral10,
+    colormap="Spectral",
     width=600,
     height=600,
     aspect_ratio=1,
@@ -25,6 +27,11 @@ def taylor_diagram(
 ):
     """
     Creates an interactive Taylor diagram using Bokeh.
+    
+    .. image:: /_static/interactive_taylor_diagram_screen_capture.gif
+        :alt: Example interactive Taylor diagram
+        :align: center
+        :width: 600px
 
     The Taylor diagram visually represents the relationship between the
     standard deviation and correlation of different models against a
@@ -46,8 +53,8 @@ def taylor_diagram(
         If True, the standard deviations are normalized by the reference standard deviation (default is False).
     step : float, optional
         The step size for the arcs and grid lines in the Taylor diagram (default is 0.2).
-    palette : list, optional
-        A list of colors to use for the model points. More options can be found at https://docs.bokeh.org/en/latest/docs/reference/palettes.html. Default is Spectral10.
+    colormap : Union[str, list], optional
+        A name or colormap or list of colors to use for the model points. Available names of colormap can be found at https://docs.bokeh.org/en/latest/docs/reference/palettes.html. Default is Spectral.
     width : int, optional
         The width of the plot in pixels (default is 600).
     height : int, optional
@@ -84,6 +91,13 @@ def taylor_diagram(
     2024-10-04: Jiwoo Lee, initial version
 
     """
+    # Convert input lists to numpy arrays for consistency
+    if isinstance(std_devs, list):
+        std_devs = np.array(std_devs)
+
+    if isinstance(correlations, list):
+        correlations = np.array(correlations)
+
     # Standard deviation axis extent
     if normalize:
         std_devs = std_devs / refstd
@@ -117,12 +131,11 @@ def taylor_diagram(
     p.axis.visible = False
 
     # Apply the adjustments in your main code
-    add_reference_arcs(
-        p, max_stddev, step=step, refstd=refstd
-    )  # Standard deviation and RMSE arcs
-    add_reference_lines(
-        p, max_stddev + step
-    )  # Adjust reference lines to end at the outermost arc
+    # Standard deviation and RMSE arcs
+    add_reference_arcs(p, max_stddev, step=step, refstd=refstd) 
+
+    # Adjust reference lines to end at the outermost arc
+    add_reference_lines(p, max_stddev + step)
 
     # Plot data points with color mapping
     source = ColumnDataSource(
@@ -135,9 +148,23 @@ def taylor_diagram(
             rmse=rmse,
         )
     )
+
+    # Get the selected colormap
+    if isinstance(colormap, list):
+        selected_palette = colormap
+    else:
+        # Check if the colormap is available in the Bokeh palettes       
+        if colormap in all_palettes:
+            selected_palette = all_palettes[colormap]
+            if isinstance(selected_palette, dict):
+                # If the palette is a dict, choose the longest available
+                selected_palette = selected_palette[max(selected_palette.keys())]
+        else:
+            print(f"Warning: Colormap '{colormap}' not found. Defaulting to 'Viridis'.")
+            selected_palette = all_palettes['Viridis'][256]
 
     # Dynamic color mapping based on model names
-    colors = factor_cmap("names", palette=palette, factors=names)
+    colors = factor_cmap("names", palette=selected_palette, factors=names)
     points = p.scatter(
         "x", "y", size=10, source=source, color=colors, legend_field="names"
     )
@@ -247,7 +274,7 @@ def find_circle_intersection(x1, y1, r1, x2, y2, r2):
 
     # Finding the intersection points
     a = (r1**2 - r2**2 + d**2) / (2 * d)
-    h = math.sqrt(r1**2 - a**2)
+    h = math.sqrt(abs(r1**2 - a**2))
 
     # Finding point P2 which is the point where the line through the circle
     # intersection points crosses the line between the circle centers.

conda-env/environment.yml

@@ -4,3 +4,10 @@ dependencies:
   - python>=3.7
   - numpy
   - bokeh
+  # test
+  - pre_commit
+  - pytest
+  # documentation
+  - sphinx
+  - sphinx-autosummary-accessors
+  - furo

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = ESMBenchmarkViz
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,16 @@
+API Reference
+=============
+The `ESMBenchmarkViz` package provides a set of tools to visualize data from the Earth System Model (ESM) Benchmarking project. 
+The package is built on top of the `bokeh` library.
+
+
+.. currentmodule:: ESMBenchmarkViz
+
+Below is a list of APIs available in `ESMBenchmarkViz`.
+
+Plotting
+~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+
+    taylor_diagram

docs/conf.py

@@ -0,0 +1,160 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+import sys
+import os
+sys.path.insert(0, os.path.abspath('../ESMBenchmarkViz'))
+
+import sphinx_autosummary_accessors
+from sphinx.application import Sphinx
+from sphinx.util import logging
+
+LOGGER = logging.getLogger("conf")
+
+import ESMBenchmarkViz
+
+# -- Project information -----------------------------------------------------
+# General information about the project.
+project = "ESMBenchmarkViz"
+copyright = "2024, Jiwoo Lee"
+author = "Jiwoo Lee"
+
+# The version info for the project you're documenting, acts as replacement
+# for |version| and |release|, also used in various other places throughout
+# the built documents.
+#
+# The short X.Y version.
+# import pcmdi_metrics
+# version = pcmdi_metrics.__version__
+# The full version, including alpha/beta/rc tags.
+# release = pcmdi_metrics.__version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme', 'sphinx.ext.napoleon']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_autosummary_accessors",
+    "sphinx_copybutton",
+    "sphinx_rtd_theme",
+    "nbsphinx",
+    "sphinx_design",
+]
+
+# autosummary and autodoc configurations
+autosummary_generate = True
+
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": True,
+}
+autodoc_typehints = "none"
+
+# Napoleon configurations
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_preprocess_types = True
+
+# sphinx-copybutton configurations
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
+# templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "demos/1-25-23-cwss-seminar/xsearch-xcdat-example.ipynb",
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+#html_theme = "sphinx_book_theme"
+html_theme = "furo"
+
+# Theme options are theme-specific and customize the look and feel of a
+# theme further.  For a list of options available for each theme, see the
+# documentation.
+#
+# sphinx_book_theme configurations
+# https://sphinx-book-theme.readthedocs.io/en/latest/configure.html
+#html_logo = "_static/PMPLogo_500x421px_72dpi.png"
+html_title = "ESMBenchmarkViz Documentation"
+
+if html_theme == "sphinx_book_theme":
+    html_theme_options = {
+        "repository_url": "https://github.com/lee1043/ESMBenchmarkViz",
+        "repository_branch": "main",
+        "path_to_docs": "docs",
+        "use_edit_page_button": True,
+        "use_repository_button": True,
+        "use_issues_button": True,
+        "use_download_button": True,
+        "use_fullscreen_button": True,
+    }
+
+elif html_theme == "furo":
+    html_theme_options = {
+        "source_repository": "https://github.com/lee1043/ESMBenchmarkViz",
+        "source_branch": "main",
+        "source_directory": "docs/",
+}
+elif html_theme == "sphinx_rtd_theme":
+    import sphinx_rtd_theme
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,53 @@
+***************
+ESMBenchmarkViz
+***************
+
+The `ESMBenchmarkViz` package provides a set of tools to visualize data from the Earth System Model (ESM) Benchmarking project. 
+The package is built on top of the `bokeh` library.
+
+
+Getting Started
+===============
+Text here
+
+
+References
+==========
+Reference here
+
+Acknowledgement
+===============
+
+Huge thank you to all of the ESMBenchmarkViz contributors!
+
+ESMBenchmarkViz is developed by scientists and developers from the Program for Climate Model Diagnosis and
+Intercomparison (`PCMDI`_) at Lawrence Livermore National Laboratory (`LLNL`_). 
+This work is sponsored by the Regional and Global Model Analysis (`RGMA`_) program of 
+the Earth and Environmental Systems Sciences Division (`EESSD`_) in 
+the Office of Biological and Environmental Research (`BER`_) 
+within the `Department of Energy`_'s `Office of Science`_. 
+The work is performed under the auspices of the U.S. Department of Energy by 
+Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344.
+
+.. _LLNL: https://www.llnl.gov/
+.. _PCMDI: https://pcmdi.llnl.gov/
+.. _RGMA: https://climatemodeling.science.energy.gov/program/regional-global-model-analysis
+.. _EESSD: https://science.osti.gov/ber/Research/eessd
+.. _BER: https://science.osti.gov/ber
+.. _Department of Energy: https://www.energy.gov/
+.. _Office of Science: https://science.osti.gov/
+.. _obs4MIPs: https://pcmdi.github.io/obs4MIPs/
+
+
+License
+=======
+
+BSD 3-Clause License.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: For users:
+
+   api
+