Merge branch 'main' into doc/alias

Author: seisman

doc/_static/style.css

@@ -1,7 +1,3 @@
-/* To stick the footer to the bottom of the page */
-html {
-}
-
 body {
     font-family: "Atkinson Hyperlegible", sans-serif;
     font-size: 1.05em;
@@ -42,8 +38,9 @@ p {
     max-width: 1000px;
 }
 
-/* Compatibility with sphinx_rtd_theme v3.x.x */
-/* https://github.com/TexasInstruments/processor-sdk-doc/commit/4fa6276ddcf7f9db919af2e5b3aec7e70a1afa16 */
+/* Workaround for the upstream bug that version section is not shown for self-hosted documentation */
+/* Upstream bug: https://github.com/readthedocs/sphinx_rtd_theme/issues/1624
+/* Workaround from https://github.com/TexasInstruments/processor-sdk-doc/commit/4fa6276ddcf7f9db919af2e5b3aec7e70a1afa16 */
 .wy-side-nav-search>div.version {
     margin-top: -.4045em;
     margin-bottom: .809em;
@@ -74,12 +71,12 @@ p {
     margin-bottom: 10px;
 }
 
-/* Format parameters section similar to sphinx_rtd_theme v4.x.x (not a grid) */
+/* Format parameters section similar to sphinx_rtd_theme v0.4.x (not a grid) */
 html.writer-html5 .rst-content dl.field-list {
     display: initial;
 }
 
-/* Add a grey box around parameters similar to sphinx_rtd_theme v4.x.x) */
+/* Add a grey box around parameters similar to sphinx_rtd_theme v0.4.x */
 .rst-content dl:not(.docutils) dl dt {
     margin-bottom: 4px;
     border: none;
@@ -100,20 +97,6 @@ html.writer-html5 .rst-content dl.field-list {
     position: relative;
 }
 
-/* Remove the padding from the Parameters table */
-.rst-content table.field-list .field-name {
-    padding-left: 0px;
-}
-
-/* Lign up the Parameters section with the descriptions */
-.rst-content table.field-list td {
-    padding-top: 8px;
-}
-
-.rst-content .highlight > pre {
-    font-size: 14px;
-}
-
 .source-link {
     float: right;
 }

pygmt/src/histogram.py

@@ -6,13 +6,15 @@
 from typing import Literal
 
 from pygmt._typing import PathLike, TableLike
-from pygmt.alias import Alias, AliasSystem
+from pygmt.alias import Alias, AliasSystem, _to_string
 from pygmt.clib import Session
-from pygmt.exceptions import GMTParameterError
+from pygmt.exceptions import GMTParameterError, GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
+    data_kind,
     deprecate_parameter,
     fmt_docstring,
+    is_nonstr_iter,
     kwargs_to_strings,
     use_alias,
 )
@@ -70,13 +72,122 @@ def _alias_option_D(  # ruff: ignore[invalid-function-name]
     ]
 
 
+def _alias_option_N(  # ruff: ignore[invalid-function-name]
+    distribution=None, distribution_pen=None
+):
+    """
+    Helper function to create the alias for the -N option.
+
+    The ``-N`` option may be repeated to draw several distribution curves, so
+    ``distribution`` also accepts a sequence of modes. ``distribution_pen`` is either a
+    single pen, used for every curve, or one pen per curve.
+
+    Examples
+    --------
+    >>> def parse(**kwargs):
+    ...     return build_arg_list(AliasSystem(N=_alias_option_N(**kwargs)))
+    >>> parse()
+    []
+    >>> # A single curve
+    >>> parse(distribution="mean")
+    ['-N0']
+    >>> parse(distribution="median", distribution_pen="1p,blue")
+    ['-N1+p1p,blue']
+
+    >>> # Multiple curves
+    >>> parse(distribution=["mean", "lms"])
+    ['-N0', '-N2']
+
+    >>> # A single pen is used for every curve
+    >>> parse(distribution=["mean", "lms"], distribution_pen="1p,red")
+    ['-N0+p1p,red', '-N2+p1p,red']
+
+    >>> # Several curves, each with its own pen
+    >>> parse(
+    ...     distribution=["mean", "median", "lms"],
+    ...     distribution_pen=["1p,red", "1p,blue", "1p,green"],
+    ... )
+    ['-N0+p1p,red', '-N1+p1p,blue', '-N2+p1p,green']
+
+    >>> # A pen alone without distribution is ignored.
+    >>> parse(distribution_pen="1p,red")
+    []
+
+    >>> # Backward compatibility: the legacy syntax combines the mode and the pen into
+    >>> # a single string, and is passed through as is.
+    >>> parse(distribution="0+p1p,blue")
+    ['-N0+p1p,blue']
+    >>> parse(distribution=["0+p1p,blue", "1+p1p,red"])
+    ['-N0+p1p,blue', '-N1+p1p,red']
+    >>> parse(distribution="+p1p,blue")
+    ['-N+p1p,blue']
+    >>> parse(distribution="1")
+    ['-N1']
+    >>> parse(distribution=True)
+    ['-N']
+
+    >>> # But the legacy syntax cannot be mixed with 'distribution_pen'.
+    >>> parse(distribution="0+p1p,blue", distribution_pen="1p,red")
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTParameterError: Conflicting parameters: 'distribution_pen' ...
+
+    >>> parse(distribution="invalid")
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTValueError: Invalid value for parameter 'distribution': ...
+
+    >>> parse(distribution=["mean", "lms"], distribution_pen=["1p,red"])
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTParameterError: 'distribution_pen' must be a single pen or ...
+    """
+    # Do nothing if distribution is not specified. Ignoring distribution_pen.
+    if distribution is None:
+        return Alias(None, name="distribution")
+
+    modes = distribution if is_nonstr_iter(distribution) else [distribution]
+    # The legacy syntax gives the mode and the pen as a single string (e.g., "1+p1p,red"
+    # or "+p1p,red"), or the mode as a string (e.g. "1"). Pass it as is.
+    if any(isinstance(mode, str) and ("+" in mode or mode.isdigit()) for mode in modes):
+        if distribution_pen is not None:
+            raise GMTParameterError(
+                conflicts_with=("distribution_pen", ["distribution"]),
+                reason="'distribution' is using the legacy syntax.",
+            )
+        return Alias(distribution, name="distribution")
+
+    pens = (
+        distribution_pen
+        if is_nonstr_iter(distribution_pen)
+        else [distribution_pen] * len(modes)
+    )
+    if len(pens) != len(modes):
+        raise GMTParameterError(
+            reason=(
+                "'distribution_pen' must be a single pen or one pen per curve, but "
+                f"got {len(pens)} pen(s) for {len(modes)} curve(s)."
+            )
+        )
+
+    values = []
+    for mode, pen in zip(modes, pens, strict=True):
+        _mode = _to_string(
+            mode, mapping={"mean": 0, "median": 1, "lms": 2}, name="distribution"
+        )
+        _pen = _to_string(pen, prefix="+p", name="distribution_pen")
+        if _mode is None:  # e.g. distribution=False means no curve at all.
+            continue
+        values.append(_mode if _pen is None else f"{_mode}{_pen}")
+    return Alias(values, name="distribution")
+
+
 @fmt_docstring
 # TODO(PyGMT>=0.22.0): Remove the deprecated "extreme" parameter.
 # TODO(PyGMT>=0.22.0): Remove the deprecated "annotate" parameter.
 @deprecate_parameter("extreme", "out_range", "0.20.0", remove_version="0.22.0")
 @deprecate_parameter("annotate", "annot", "0.20.0", remove_version="0.22.0")
 @use_alias(
-    N="distribution",
     T="series",
     Z="histtype",
     b="binary",
@@ -90,6 +201,7 @@ def _alias_option_D(  # ruff: ignore[invalid-function-name]
 def histogram(
     self,
     data: PathLike | TableLike,
+    weights: bool | Sequence[float] = False,
     bar_width: float | str | None = None,
     bar_offset: float | str | None = None,
     cmap: str | bool = False,
@@ -105,6 +217,10 @@ def histogram(
     out_range: Literal["first", "last", "both"] | None = None,
     stairs: bool = False,
     cumulative: bool | Literal["reverse"] = False,
+    distribution: Literal["mean", "median", "lms"]
+    | Sequence[Literal["mean", "median", "lms"]]
+    | None = None,
+    distribution_pen: str | Sequence[str] | None = None,
     projection: str | None = None,
     region: Sequence[float | str] | str | None = None,
     frame: Frame | Axis | Literal["none"] | str | Sequence[str] | bool = False,
@@ -131,6 +247,7 @@ def histogram(
        - G = fill
        - J = projection
        - L = out_range
+       - N = distribution, **+p**: distribution_pen
        - Q = cumulative
        - R = region
        - S = stairs
@@ -146,6 +263,14 @@ def histogram(
     data
         Pass in either a file name to an ASCII data table, a Python list, a 2-D
         $table_classes.
+    weights
+        Use weighted counts instead of pure counts [Default is ``False``, i.e., pure
+        counts are used]. It can be:
+
+        - ``True``: Weights are provided in the second column of ``data``, if ``data``
+          is a file name or a 2-D sequence.
+        - A 1-D array of weights, one per data point, requiring that ``data`` is a 1-D
+          sequence of values.
     $cmap
     pen
         Draw bar outline (or stair-case curve) using the specified pen thickness
@@ -177,15 +302,6 @@ def histogram(
     center
         Center bin on each value specified via ``series`` [Default uses the values to
         define the left edge of each bin].
-    distribution : bool, float, or str
-        [*mode*][**+p**\ *pen*].
-        Draw the equivalent normal distribution; append desired
-        *pen* [Default is ``"0.25p,black,solid"``].
-        The *mode* selects which central location and scale to use:
-
-        * 0 = mean and standard deviation [Default];
-        * 1 = median and L1 scale (1.4826 \* median absolute deviation; MAD);
-        * 2 = LMS (least median of squares) mode and scale.
     out_range
         Handle values that fall outside the range set by ``series``. By default, these
         values are ignored. Valid values are:
@@ -207,8 +323,9 @@ def histogram(
         [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ].
         Set the interval for the width of each bar in the histogram.
     histtype : int or str
-        [*type*][**+w**].
-        Choose between 6 types of histograms:
+        [*type*].
+        By default, pure counts are determined. To get weighted counts, use the
+        ``weights`` parameter. Choose between 6 types of histograms:
 
         * 0 = counts [Default]
         * 1 = frequency_percent
@@ -217,8 +334,23 @@ def histogram(
         * 4 = log10 (1.0 + count)
         * 5 = log10 (1.0 + frequency_percent).
 
-        To use weights provided as a second data column instead of pure counts,
-        append **+w**.
+    distribution
+        Draw the equivalent normal distribution. Select which central location and scale
+        to use:
+
+        - ``"mean"``: mean and standard deviation
+        - ``"median"``: median and L1 scale (1.4826 \* median absolute deviation)
+        - ``"lms"``: least median of squares (LMS) mode and scale
+
+        Pass a sequence of modes to draw several curves at once, e.g.,
+        ``["mean", "lms"]``.
+
+        **Note**: If ``wrap`` is used, only ``"mean"`` is available and the circular
+        von Mises distribution is determined instead.
+    distribution_pen
+        Pen used to draw the distribution curve [Default is ``"0.25p,black,solid"``].
+        Pass a sequence of pens to use a different pen for each curve; a single pen is
+        used for all of them. If ``distribution`` is not set, this parameter is ignored.
     $projection
     $region
     $frame
@@ -251,6 +383,16 @@ def histogram(
             required="bar_width", reason="Required when 'bar_offset' is set."
         )
 
+    # weights can be given as a 1-D array, or as a boolean to indicate that the second
+    # column of data contains weights. If weights is an array, then data must be a 1-D
+    # sequence of values.
+    _weight_is_array = is_nonstr_iter(weights)
+    if data_kind(data) == "file" and _weight_is_array:
+        raise GMTTypeError(
+            type(weights),
+            reason="'weights' must be boolean when 'data' is a file name.",
+        )
+
     aliasdict = AliasSystem(
         A=Alias(horizontal, name="horizontal"),
         C=Alias(cmap, name="cmap"),
@@ -272,6 +414,7 @@ def histogram(
             name="out_range",
             mapping={"first": "l", "last": "h", "both": "b"},
         ),
+        N=_alias_option_N(distribution, distribution_pen),
         Q=Alias(cumulative, name="cumulative", mapping={"reverse": "r"}),
         S=Alias(stairs, name="stairs"),
         W=Alias(pen, name="pen"),
@@ -286,10 +429,13 @@ def histogram(
         t=transparency,
     )
     aliasdict.merge(kwargs)
+    if weights is not False:
+        aliasdict["Z"] = f"{aliasdict.get('Z', '')}+w"
 
     self._activate_figure()
     with Session() as lib:
-        with lib.virtualfile_in(check_kind="vector", data=data) as vintbl:
+        vfargs = {"x": data, "y": weights} if _weight_is_array else {"data": data}
+        with lib.virtualfile_in(check_kind="vector", **vfargs) as vintbl:
             lib.call_module(
                 module="histogram", args=build_arg_list(aliasdict, infile=vintbl)
             )