lsst-utils 25.2023.600__py3-none-any.whl → 29.2025.4800__py3-none-any.whl

lsst/utils/plotting/figures.py

@@ -0,0 +1,159 @@
+# This file is part of utils.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+"""Utilities related to making matplotlib figures."""
+
+from __future__ import annotations
+
+__all__ = [
+    "get_multiband_plot_colors",
+    "get_multiband_plot_linestyles",
+    "get_multiband_plot_symbols",
+    "make_figure",
+]
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+
+def make_figure(**kwargs: Any) -> Figure:
+    """Make a matplotlib Figure with an Agg-backend canvas.
+
+    This routine creates a matplotlib figure without using
+    ``matplotlib.pyplot``, and instead uses a fixed non-interactive
+    backend. The advantage is that these figures are not cached and
+    therefore do not need to be explicitly closed -- they
+    are completely self-contained and ephemeral unlike figures
+    created with `matplotlib.pyplot.figure()`.
+
+    Parameters
+    ----------
+    **kwargs : `dict`
+        Keyword arguments to be passed to `matplotlib.figure.Figure()`.
+
+    Returns
+    -------
+    figure : `matplotlib.figure.Figure`
+        Figure with a fixed Agg backend, and no caching.
+
+    Notes
+    -----
+    The code here is based on
+    https://matplotlib.org/stable/gallery/user_interfaces/canvasagg.html
+    """
+    try:
+        from matplotlib.backends.backend_agg import FigureCanvasAgg
+        from matplotlib.figure import Figure
+    except ImportError as e:
+        raise RuntimeError("Cannot use make_figure without matplotlib.") from e
+
+    fig = Figure(**kwargs)
+    FigureCanvasAgg(fig)
+
+    return fig
+
+
+def get_multiband_plot_colors(dark_background: bool = False) -> dict:
+    """Get color mappings for multiband plots using SDSS filter names.
+
+    Notes
+    -----
+    From https://rtn-045.lsst.io/#colorblind-friendly-plots
+
+    Parameters
+    ----------
+    dark_background : `bool`, optional
+        Use colors intended for a dark background.
+        Default colors are intended for a light background.
+
+    Returns
+    -------
+    plot_colors : `dict` of `str`
+        Mapping of the LSST bands to colors.
+    """
+    plot_filter_colors_white_background = {
+        "u": "#1600EA",
+        "g": "#31DE1F",
+        "r": "#B52626",
+        "i": "#370201",
+        "z": "#BA52FF",
+        "y": "#61A2B3",
+    }
+    plot_filter_colors_black_background = {
+        "u": "#3eb7ff",
+        "g": "#30c39f",
+        "r": "#ff7e00",
+        "i": "#2af5ff",
+        "z": "#a7f9c1",
+        "y": "#fdc900",
+    }
+    if dark_background:
+        return plot_filter_colors_black_background
+    else:
+        return plot_filter_colors_white_background
+
+
+def get_multiband_plot_symbols() -> dict:
+    """Get symbol mappings for multiband plots using SDSS filter names.
+
+    Notes
+    -----
+    From https://rtn-045.lsst.io/#colorblind-friendly-plots
+
+    Returns
+    -------
+    plot_symbols : `dict` of `str`
+        Mapping of the LSST bands to symbols.
+    """
+    plot_symbols = {
+        "u": "o",
+        "g": "^",
+        "r": "v",
+        "i": "s",
+        "z": "*",
+        "y": "p",
+    }
+    return plot_symbols
+
+
+def get_multiband_plot_linestyles() -> dict:
+    """Get line style mappings for multiband plots using SDSS filter names.
+
+    Notes
+    -----
+    From https://rtn-045.lsst.io/#colorblind-friendly-plots
+
+    Returns
+    -------
+    plot_linestyles : `dict` of `str`
+        Mapping of the LSST bands to line styles.
+    """
+    plot_line_styles = {
+        "u": "--",
+        "g": (0, (3, 1, 1, 1)),
+        "r": "-.",
+        "i": "-",
+        "z": (0, (3, 1, 1, 1, 1, 1)),
+        "y": ":",
+    }
+
+    # [SP-2200]: Restored to using parametric values.
+    # To avoid matplotlib v3.10 bug (see DM-49724),
+    # manually iterate over `patches` object returned
+    # by `plt.hist` when using histtype='step':
+    #     _, _, patches = plt.hist()
+    #     linestyle = plot_line_styles[band]
+    #     for patch in patches:
+    #         patch.set_linestyle(linestyle)
+    # It seems the bug will be fixed in matplotlib v.3.10.2,
+    # see DM-49724[TODO]
+    return plot_line_styles

lsst/utils/plotting/limits.py

@@ -0,0 +1,155 @@
+# This file is part of utils.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+from __future__ import annotations
+
+__all__ = ["calculate_safe_plotting_limits", "make_calculate_safe_plotting_limits"]
+
+from collections.abc import Callable, Iterable, Sequence
+
+import numpy as np
+
+
+def calculate_safe_plotting_limits(
+    data_series: Sequence,
+    percentile: float = 99.9,
+    constant_extra: float | None = None,
+    symmetric_around_zero: bool = False,
+) -> tuple[float, float]:
+    """Calculate the right limits for plotting for one or more data series.
+
+    Given one or more data series with potential outliers, calculated the
+    values to pass for ymin, ymax so that extreme outliers don't ruin the
+    plot. If you are plotting several series on a single axis, pass them
+    all in and the overall plotting range will be given.
+
+    Parameters
+    ----------
+    data_series : `iterable` or `iterable` of `iterable`
+        One or more data series which will be going on the same axis, and
+        therefore want to have their common plotting limits calculated.
+    percentile : `float`, optional
+        The percentile used to clip the outliers from the data.
+    constant_extra : `float` or `None`, optional
+        The amount that's added on each side of the range so that data does not
+        quite touch the axes. If the default ``None`` is left then 5% of the
+        data range is added for cosmetics, but if zero is set this will
+        overrides this behaviour and zero you will get.
+    symmetric_around_zero : `bool`, optional
+        Whether to make the limits symmetric around zero.
+
+    Returns
+    -------
+    ymin : `float`
+        The value to set the ylim minimum to.
+    ymax : `float`
+        The value to set the ylim maximum to.
+    """
+    localFunc = make_calculate_safe_plotting_limits(percentile, constant_extra, symmetric_around_zero)
+    return localFunc(data_series)
+
+
+def make_calculate_safe_plotting_limits(
+    percentile: float = 99.9,
+    constant_extra: float | None = None,
+    symmetric_around_zero: bool = False,
+) -> Callable[[Sequence], tuple[float, float]]:
+    """Make a ``calculate_safe_plotting_limits`` closure to get the common
+    limits when not all data series are available initially.
+
+    Parameters
+    ----------
+    percentile : `float`, optional
+        The percentile used to clip the outliers from the data.
+    constant_extra : `float`, optional
+        The amount that's added on each side of the range so that data does not
+        quite touch the axes. If the default ``None`` is left then 5% of the
+        data range is added for cosmetics, but if zero is set this will
+        overrides this behaviour and zero you will get.
+    symmetric_around_zero : `bool`, optional
+        Whether to make the limits symmetric around zero.
+
+    Returns
+    -------
+    calculate_safe_plotting_limits : `callable`
+        The calculate_safe_plotting_limits function to pass the data series to.
+    """
+    memory: list[Sequence] = []
+
+    def calculate_safe_plotting_limits(
+        data_series: Sequence,  # a sequence of sequences is still a sequence
+    ) -> tuple[float, float]:
+        """Calculate the right limits for plotting for one or more data series.
+
+        Given one or more data series with potential outliers, calculated the
+        values to pass for ymin, ymax so that extreme outliers don't ruin the
+        plot. If you are plotting several series on a single axis, pass them
+        all in and the overall plotting range will be given.
+
+        Parameters
+        ----------
+        data_series : `iterable` or `iterable` of `iterable`
+            One or more data series which will be going on the same axis, and
+            therefore want to have their common plotting limits calculated.
+
+        Returns
+        -------
+        ymin : `float`
+            The value to set the ylim minimum to.
+        ymax : `float`
+            The value to set the ylim maximum to.
+        """
+        nonlocal constant_extra
+        nonlocal percentile
+        nonlocal symmetric_around_zero
+
+        if not isinstance(data_series, Iterable):
+            raise TypeError("data_series must be either an iterable, or an iterable of iterables")
+
+        # now we're sure we have an iterable, if it's just one make it a list
+        # of it lsst.utils.ensure_iterable is not suitable here as we already
+        # have one, we would need ensure_iterable_of_iterables here
+
+        # np.array are Iterable but not Sequence so isinstance that
+        if not isinstance(data_series[0], Iterable):
+            # we have a single data series, not multiple, wrap in [] so we can
+            # iterate over it as if we were given many
+            data_series = [data_series]
+
+        memory.extend(data_series)
+
+        mins = []
+        maxs = []
+
+        for dataSeries in memory:
+            max_val = np.nanpercentile(dataSeries, percentile)
+            min_val = np.nanpercentile(dataSeries, 100.0 - percentile)
+
+            if constant_extra is None:
+                data_range = max_val - min_val
+                constant_extra = 0.05 * data_range
+
+            max_val += constant_extra
+            min_val -= constant_extra
+
+            maxs.append(max_val)
+            mins.append(min_val)
+
+        max_val = max(maxs)
+        min_val = min(mins)
+
+        if symmetric_around_zero:
+            biggest_abs = max(abs(min_val), abs(max_val))
+            return -biggest_abs, biggest_abs
+
+        return min_val, max_val
+
+    return calculate_safe_plotting_limits

lsst/utils/plotting/publication_plots.py

@@ -0,0 +1,184 @@
+# This file is part of utils.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+"""Utilities for making publication-quality figures."""
+
+__all__ = [
+    "accent_color",
+    "divergent_cmap",
+    "galaxies_cmap",
+    "galaxies_color",
+    "get_band_dicts",
+    "mk_colormap",
+    "set_rubin_plotstyle",
+    "sso_cmap",
+    "sso_color",
+    "stars_cmap",
+    "stars_color",
+]
+
+import numpy as np
+
+from . import (
+    get_multiband_plot_colors,
+    get_multiband_plot_linestyles,
+    get_multiband_plot_symbols,
+)
+
+
+def set_rubin_plotstyle() -> None:
+    """
+    Set the matplotlib style for Rubin publications
+    """
+    from matplotlib import style
+
+    style.use("lsst.utils.plotting.rubin")
+
+
+def mk_colormap(colorNames):  # type: ignore
+    """Make a colormap from the list of color names.
+
+    Parameters
+    ----------
+    colorNames : `list`
+        A list of strings that correspond to matplotlib named colors.
+
+    Returns
+    -------
+    cmap : `matplotlib.colors.LinearSegmentedColormap`
+        A colormap stepping through the supplied list of names.
+    """
+    from matplotlib import colors
+
+    blues = []
+    greens = []
+    reds = []
+    alphas = []
+
+    if len(colorNames) == 1:
+        # Alpha is between 0 and 1 really but
+        # using 1.5 saturates out the top of the
+        # colorscale, this looks good for ComCam data
+        # but might want to be changed in the future.
+        alphaRange = [0.2, 1.0]
+        nums = np.linspace(0, 1, len(alphaRange))
+        r, g, b = colors.colorConverter.to_rgb(colorNames[0])
+        for num, alpha in zip(nums, alphaRange):
+            blues.append((num, b, b))
+            greens.append((num, g, g))
+            reds.append((num, r, r))
+            alphas.append((num, alpha, alpha))
+
+    else:
+        nums = np.linspace(0, 1, len(colorNames))
+        if len(colorNames) == 3:
+            alphaRange = [1.0, 1.0, 1.0]
+        elif len(colorNames) == 5:
+            alphaRange = [1.0, 0.7, 0.3, 0.7, 1.0]
+        else:
+            alphaRange = np.ones(len(colorNames))
+
+        for num, color, alpha in zip(nums, colorNames, alphaRange):
+            r, g, b = colors.colorConverter.to_rgb(color)
+            blues.append((num, b, b))
+            greens.append((num, g, g))
+            reds.append((num, r, r))
+            alphas.append((num, alpha, alpha))
+
+    colorDict = {"blue": blues, "red": reds, "green": greens, "alpha": alphas}
+    cmap = colors.LinearSegmentedColormap("newCmap", colorDict)
+    return cmap
+
+
+def divergent_cmap():  # type: ignore
+    """
+    Make a divergent color map.
+    """
+    cmap = mk_colormap([stars_color(), "#D9DCDE", accent_color()])
+
+    return cmap
+
+
+def stars_cmap(single_color=False):  # type: ignore
+    """Make a color map for stars."""
+    import seaborn as sns
+    from matplotlib.colors import ListedColormap
+
+    if single_color:
+        cmap = mk_colormap([stars_color()])
+    else:
+        cmap = ListedColormap(sns.color_palette("mako", 256))
+    return cmap
+
+
+def stars_color() -> str:
+    """Return the star color string for lines"""
+    return "#084d96"
+
+
+def accent_color() -> str:
+    """Return a contrasting color for overplotting,
+    black is the best for this but if you need two colors
+    this works well on blue.
+    """
+    return "#DE8F05"
+
+
+def galaxies_cmap(single_color=False):  # type: ignore
+    """Make a color map for galaxies."""
+    if single_color:
+        cmap = mk_colormap([galaxies_color()])
+    else:
+        cmap = "inferno"
+    return cmap
+
+
+def galaxies_color() -> str:
+    """Return the galaxy color string for lines"""
+    return "#961A45"
+
+
+def sso_color() -> str:
+    """Return the SSO color string for lines"""
+    return "#01694c"
+
+
+def sso_cmap(single_color=False):  # type: ignore
+    """Make a color map for solar system objects."""
+    if single_color:
+        cmap = mk_colormap([sso_color()])
+    else:
+        cmap = "viridis"
+    return cmap
+
+
+def get_band_dicts() -> dict:
+    """
+    Define palettes, from RTN-045. This includes dicts for colors (bandpass
+    colors for white background), colors_black (bandpass colors for
+    black background), plot symbols, and line_styles, keyed on band (ugrizy).
+
+    Returns
+    -------
+    band_dict : `dict` of `dict`
+        Dicts of colors, colors_black, symbols, and line_styles,
+        keyed on bands 'u', 'g', 'r', 'i', 'z', and 'y'.
+    """
+    colors = get_multiband_plot_colors()
+    colors_black = get_multiband_plot_colors(dark_background=True)
+    symbols = get_multiband_plot_symbols()
+    line_styles = get_multiband_plot_linestyles()
+
+    return {
+        "colors": colors,
+        "colors_black": colors_black,
+        "symbols": symbols,
+        "line_styles": line_styles,
+    }

lsst/utils/plotting/rubin.mplstyle

@@ -0,0 +1,46 @@
+axes.labelweight: normal
+figure.titleweight : normal
+axes.labelsize : large
+axes.linewidth: 1
+axes.titleweight: normal
+axes.titlesize : small
+figure.titlesize: small
+errorbar.capsize: 3.0
+
+lines.linewidth : 2
+lines.markersize : 10
+
+xtick.labelsize : small
+ytick.labelsize : small
+
+figure.dpi : 300.0
+figure.facecolor: White
+figure.figsize : 6.4, 4.8
+
+# From seaborn-v0_8-colorblind colormap: https://seaborn.pydata.org/tutorial/color_palettes.html
+axes.prop_cycle: cycler('color', ['0173B2', 'DE8F05', '029E73', 'D55E00', 'CC78BC', 'CA9161', 'FBAFE4', '949494', 'ECE133', '56B4E9'])
+patch.facecolor: 006BA4
+
+font.size : 14
+legend.fontsize: x-small
+
+xtick.major.width: 1.0
+xtick.minor.width: 0.5
+xtick.major.size: 7
+xtick.minor.size: 4
+xtick.minor.visible: True
+xtick.direction: in
+xtick.top: True
+xtick.bottom: True
+ytick.major.width: 1.0
+ytick.minor.width: 0.5
+ytick.major.size: 7
+ytick.minor.size: 4
+ytick.minor.visible: True
+ytick.direction: in
+ytick.left: True
+ytick.right: True
+xtick.major.pad : 6
+xtick.minor.pad : 6
+ytick.major.pad : 6
+ytick.minor.pad : 6