wandb 0.18.4__py3-none-any.whl → 0.18.6__py3-none-any.whl

wandb/plot/histogram.py

@@ -1,39 +1,65 @@
-from typing import TYPE_CHECKING, Optional
+from __future__ import annotations
 
-from wandb.plot.viz import custom_chart
+from typing import TYPE_CHECKING
+
+from wandb.plot.custom_chart import plot_table
 
 if TYPE_CHECKING:
     import wandb
+    from wandb.plot.custom_chart import CustomChart
 
 
 def histogram(
-    table: "wandb.Table",
+    table: wandb.Table,
     value: str,
-    title: Optional[str] = None,
-    split_table: Optional[bool] = False,
-):
-    """Construct a histogram plot.
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a histogram chart from a W&B Table.
 
-    Arguments:
-        table (wandb.Table): Table of data.
-        value (string): Name of column to use as data for bucketing.
-        title (string): Plot title.
-        split_table (bool): If True, adds "Custom Chart Tables/" to the key of the table so that it's logged in a different section.
+    Args:
+        table (wandb.Table): The W&B Table containing the data for the histogram.
+        value (str): The label for the bin axis (x-axis).
+        title (str): The title of the histogram plot.
+        split_table (bool): Whether the table should be split into a separate section
+            in the W&B UI. If `True`, the table will be displayed in a section named
+            "Custom Chart Tables". Default is `False`.
 
     Returns:
-        A plot object, to be passed to wandb.log()
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
 
     Example:
         ```
+        import math
+        import random
+        import wandb
+
+        # Generate random data
         data = [[i, random.random() + math.sin(i / 10)] for i in range(100)]
-        table = wandb.Table(data=data, columns=["step", "height"])
-        wandb.log({'histogram-plot1': wandb.plot.histogram(table, "height")})
+
+        # Create a W&B Table
+        table = wandb.Table(
+            data=data,
+            columns=["step", "height"],
+        )
+
+        # Create a histogram plot
+        histogram = wandb.plot.histogram(
+            table,
+            value="height",
+            title="My Histogram",
+        )
+
+        # Log the histogram plot to W&B
+        with wandb.init(...) as run:
+            run.log({'histogram-plot1': histogram})
         ```
     """
-    return custom_chart(
-        "wandb/histogram/v0",
-        table,
-        {"value": value},
-        {"title": title},
+    return plot_table(
+        data_table=table,
+        vega_spec_name="wandb/histogram/v0",
+        fields={"value": value},
+        string_fields={"title": title},
         split_table=split_table,
     )

wandb/plot/line.py

@@ -1,43 +1,74 @@
-from typing import TYPE_CHECKING, Optional
+from __future__ import annotations
 
-from wandb.plot.viz import custom_chart
+from typing import TYPE_CHECKING
+
+from wandb.plot.custom_chart import plot_table
 
 if TYPE_CHECKING:
     import wandb
+    from wandb.plot.custom_chart import CustomChart
 
 
 def line(
-    table: "wandb.Table",
+    table: wandb.Table,
     x: str,
     y: str,
-    stroke: Optional[str] = None,
-    title: Optional[str] = None,
-    split_table: Optional[bool] = False,
-):
-    """Construct a line plot.
-
-    Arguments:
-        table (wandb.Table): Table of data.
-        x (string): Name of column to as for x-axis values.
-        y (string): Name of column to as for y-axis values.
-        stroke (string): Name of column to map to the line stroke scale.
-        title (string): Plot title.
-        split_table (bool): If True, adds "Custom Chart Tables/" to the key of the table so that it's logged in a different section.
+    stroke: str | None = None,
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a customizable line chart.
+
+    Args:
+        table (wandb.Table):  The table containing data for the chart.
+        x (str): Column name for the x-axis values.
+        y (str): Column name for the y-axis values.
+        stroke (str):Column name to differentiate line strokes (e.g., for
+            grouping lines).
+        title (str):Title of the chart.
+        split_table (bool): Whether the table should be split into a separate section
+            in the W&B UI. If `True`, the table will be displayed in a section named
+            "Custom Chart Tables". Default is `False`.
 
     Returns:
-        A plot object, to be passed to wandb.log()
+       CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
 
     Example:
-        ```
-        data = [[i, random.random() + math.sin(i / 10)] for i in range(100)]
-        table = wandb.Table(data=data, columns=["step", "height"])
-        wandb.log({'line-plot1': wandb.plot.line(table, "step", "height")})
+       ```python
+        import math
+        import random
+        import wandb
+
+        # Create multiple series of data with different patterns
+        data = []
+        for i in range(100):
+            # Series 1: Sinusoidal pattern with random noise
+            data.append([i, math.sin(i / 10) + random.uniform(-0.1, 0.1), "series_1"])
+            # Series 2: Cosine pattern with random noise
+            data.append([i, math.cos(i / 10) + random.uniform(-0.1, 0.1), "series_2"])
+            # Series 3: Linear increase with random noise
+            data.append([i, i / 10 + random.uniform(-0.5, 0.5), "series_3"])
+
+        # Define the columns for the table
+        table = wandb.Table(data=data, columns=["step", "value", "series"])
+
+        # Initialize wandb run and log the line chart
+        with wandb.init(project="line_chart_example") as run:
+            line_chart = wandb.plot.line(
+                table=table,
+                x="step",
+                y="value",
+                stroke="series",  # Group by the "series" column
+                title="Multi-Series Line Plot",
+            )
+            run.log({"line-chart": line_chart})
         ```
     """
-    return custom_chart(
-        "wandb/line/v0",
-        table,
-        {"x": x, "y": y, "stroke": stroke},
-        {"title": title},
+    return plot_table(
+        data_table=table,
+        vega_spec_name="wandb/line/v0",
+        fields={"x": x, "y": y, "stroke": stroke},
+        string_fields={"title": title},
         split_table=split_table,
     )

wandb/plot/line_series.py

@@ -1,88 +1,176 @@
-import typing as t
-from collections.abc import Iterable
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable
 
 import wandb
+from wandb.plot.custom_chart import plot_table
+
+if TYPE_CHECKING:
+    from wandb.plot.custom_chart import CustomChart
 
 
 def line_series(
-    xs: t.Union[t.Iterable, t.Iterable[t.Iterable]],
-    ys: t.Iterable[t.Iterable],
-    keys: t.Optional[t.Iterable] = None,
-    title: t.Optional[str] = None,
-    xname: t.Optional[str] = None,
-    split_table: t.Optional[bool] = False,
-):
-    """Construct a line series plot.
-
-    Arguments:
-        xs (array of arrays, or array): Array of arrays of x values
-        ys (array of arrays): Array of y values
-        keys (array): Array of labels for the line plots
-        title (string): Plot title.
-        xname: Title of x-axis
-        split_table (bool): If True, adds "Custom Chart Tables/" to the key of the table so that it's logged in a different section.
+    xs: Iterable[Iterable[Any]] | Iterable[Any],
+    ys: Iterable[Iterable[Any]],
+    keys: Iterable[str] | None = None,
+    title: str = "",
+    xname: str = "x",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a line series chart.
+
+    Args:
+        xs (Iterable[Iterable] | Iterable): Sequence of x values. If a singular
+            array is provided, all y values are plotted against that x array. If
+            an array of arrays is provided, each y value is plotted against the
+            corresponding x array.
+        ys (Iterable[Iterable]): Sequence of y values, where each iterable represents
+            a separate line series.
+        keys (Iterable[str]): Sequence of keys for labeling each line series. If
+            not provided, keys will be automatically generated as "line_1",
+            "line_2", etc.
+        title (str): Title of the chart.
+        xname (str): Label for the x-axis.
+        split_table (bool): Whether the table should be split into a separate section
+            in the W&B UI. If `True`, the table will be displayed in a section named
+            "Custom Chart Tables". Default is `False`.
 
     Returns:
-        A plot object, to be passed to wandb.log()
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
 
-    Example:
-        When logging a singular array for xs, all ys are plotted against that xs
-        <!--yeadoc-test:plot-line-series-single-->
-        ```python
+    Examples:
+        1. Logging a single x array where all y series are plotted against
+           the same x values:
+
+        ```
         import wandb
 
-        run = wandb.init()
-        xs = [i for i in range(10)]
-        ys = [[i for i in range(10)], [i**2 for i in range(10)]]
-        run.log(
-            {"line-series-plot1": wandb.plot.line_series(xs, ys, title="title", xname="step")}
-        )
-        run.finish()
+        # Initialize W&B run
+        with wandb.init(project="line_series_example") as run:
+            # x values shared across all y series
+            xs = list(range(10))
+
+            # Multiple y series to plot
+            ys = [
+                [i for i in range(10)],       # y = x
+                [i**2 for i in range(10)],    # y = x^2
+                [i**3 for i in range(10)],     # y = x^3
+            ]
+
+            # Generate and log the line series chart
+            line_series_chart = wandb.plot.line_series(
+                xs,
+                ys,
+                title="title",
+                xname="step",
+            )
+            run.log({"line-series-single-x": line_series_chart})
         ```
-        xs can also contain an array of arrays for having different steps for each metric
-        <!--yeadoc-test:plot-line-series-double-->
+
+        In this example, a single `xs` series (shared x-values) is used for all
+        `ys` series. This results in each y-series being plotted against the
+        same x-values (0-9).
+
+        2. Logging multiple x arrays where each y series is plotted against
+           its corresponding x array:
+
         ```python
         import wandb
 
-        run = wandb.init()
-        xs = [[i for i in range(10)], [2 * i for i in range(10)]]
-        ys = [[i for i in range(10)], [i**2 for i in range(10)]]
-        run.log(
-            {"line-series-plot2": wandb.plot.line_series(xs, ys, title="title", xname="step")}
-        )
-        run.finish()
+        # Initialize W&B run
+        with wandb.init(project="line_series_example") as run:
+            # Separate x values for each y series
+            xs = [
+                [i for i in range(10)],  # x for first series
+                [2 * i for i in range(10)],  # x for second series (stretched)
+                [3 * i for i in range(10)],  # x for third series (stretched more)
+            ]
+
+            # Corresponding y series
+            ys = [
+                [i for i in range(10)],  # y = x
+                [i**2 for i in range(10)],  # y = x^2
+                [i**3 for i in range(10)],  # y = x^3
+            ]
+
+            # Generate and log the line series chart
+            line_series_chart = wandb.plot.line_series(
+                xs, ys, title="Multiple X Arrays Example", xname="Step"
+            )
+            run.log({"line-series-multiple-x": line_series_chart})
         ```
-    """
-    if not isinstance(xs, Iterable):
-        raise TypeError(f"Expected xs to be an array instead got {type(xs)}")
 
-    if not isinstance(ys, Iterable):
-        raise TypeError(f"Expected ys to be an array instead got {type(xs)}")
+        In this example, each y series is plotted against its own unique x series.
+        This allows for more flexibility when the x values are not uniform across
+        the data series.
+
+        3. Customizing line labels using `keys`:
+
+        ```python
+        import wandb
+
+        # Initialize W&B run
+        with wandb.init(project="line_series_example") as run:
+            xs = list(range(10))  # Single x array
+            ys = [
+                [i for i in range(10)],  # y = x
+                [i**2 for i in range(10)],  # y = x^2
+                [i**3 for i in range(10)],  # y = x^3
+            ]
 
-    for y in ys:
-        if not isinstance(y, Iterable):
-            raise TypeError(
-                f"Expected ys to be an array of arrays instead got {type(y)}"
+            # Custom labels for each line
+            keys = ["Linear", "Quadratic", "Cubic"]
+
+            # Generate and log the line series chart
+            line_series_chart = wandb.plot.line_series(
+                xs,
+                ys,
+                keys=keys,  # Custom keys (line labels)
+                title="Custom Line Labels Example",
+                xname="Step",
             )
+            run.log({"line-series-custom-keys": line_series_chart})
+        ```
 
+        This example shows how to provide custom labels for the lines using
+        the `keys` argument. The keys will appear in the legend as "Linear",
+        "Quadratic", and "Cubic".
+
+    """
+    # If xs is a single array, repeat it for each y in ys
     if not isinstance(xs[0], Iterable) or isinstance(xs[0], (str, bytes)):
-        xs = [xs for _ in range(len(ys))]
-    assert len(xs) == len(ys), "Number of x-lines and y-lines must match"
+        xs = [xs] * len(ys)
+
+    if len(xs) != len(ys):
+        msg = f"Number of x-series ({len(xs)}) must match y-series ({len(ys)})."
+        raise ValueError(msg)
+
+    if keys is None:
+        keys = [f"line_{i}" for i in range(len(ys))]
+
+    if len(keys) != len(ys):
+        msg = f"Number of keys ({len(keys)}) must match y-series ({len(ys)})."
+        raise ValueError(msg)
 
-    if keys is not None:
-        assert len(keys) == len(ys), "Number of keys and y-lines must match"
     data = [
-        [x, f"key_{i}" if keys is None else keys[i], y]
+        [x, keys[i], y]
         for i, (xx, yy) in enumerate(zip(xs, ys))
         for x, y in zip(xx, yy)
     ]
+    table = wandb.Table(
+        data=data,
+        columns=["step", "lineKey", "lineVal"],
+    )
 
-    table = wandb.Table(data=data, columns=["step", "lineKey", "lineVal"])
-
-    return wandb.plot_table(
-        "wandb/lineseries/v0",
-        table,
-        {"step": "step", "lineKey": "lineKey", "lineVal": "lineVal"},
-        {"title": title, "xname": xname or "x"},
+    return plot_table(
+        data_table=table,
+        vega_spec_name="wandb/lineseries/v0",
+        fields={
+            "step": "step",
+            "lineKey": "lineKey",
+            "lineVal": "lineVal",
+        },
+        string_fields={"title": title, "xname": xname},
         split_table=split_table,
     )

wandb/plot/pr_curve.py

@@ -1,48 +1,92 @@
-from typing import Optional
+from __future__ import annotations
+
+import numbers
+from typing import TYPE_CHECKING, Iterable, TypeVar
 
 import wandb
 from wandb import util
+from wandb.plot.custom_chart import plot_table
+from wandb.plot.utils import test_missing, test_types
+
+if TYPE_CHECKING:
+    from wandb.plot.custom_chart import CustomChart
+
 
-from .utils import test_missing, test_types
+T = TypeVar("T")
 
 
 def pr_curve(
-    y_true=None,
-    y_probas=None,
-    labels=None,
-    classes_to_plot=None,
-    interp_size=21,
-    title=None,
-    split_table: Optional[bool] = False,
-):
-    """Compute the tradeoff between precision and recall for different thresholds.
-
-    A high area under the curve represents both high recall and high precision, where
-    high precision relates to a low false positive rate, and high recall relates to a
-    low false negative rate. High scores for both show that the classifier is returning
-    accurate results (high precision), and returning a majority of all positive results
-    (high recall). PR curve is useful when the classes are very imbalanced.
-
-    Arguments:
-        y_true (arr): true sparse labels y_probas (arr): Target scores, can either be
-            probability estimates, confidence values, or non-thresholded measure of
-            decisions. shape: (*y_true.shape, num_classes)
-        labels (list): Named labels for target variable (y). Makes plots easier to read
-            by replacing target values with corresponding index. For example labels =
-            ['dog', 'cat', 'owl'] all 0s are replaced by 'dog', 1s by 'cat'.
-        classes_to_plot (list): unique values of y_true to include in the plot
-        interp_size (int): the recall values will be fixed to `interp_size` points
-            uniform on [0, 1] and the precision will be interpolated for these recall
-            values.
-        split_table (bool): If True, adds "Custom Chart Tables/" to the key of the table so that it's logged in a different section.
+    y_true: Iterable[T] | None = None,
+    y_probas: Iterable[numbers.Number] | None = None,
+    labels: list[str] | None = None,
+    classes_to_plot: list[T] | None = None,
+    interp_size: int = 21,
+    title: str = "Precision-Recall Curve",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a Precision-Recall (PR) curve.
+
+    The Precision-Recall curve is particularly useful for evaluating classifiers
+    on imbalanced datasets. A high area under the PR curve signifies both high
+    precision (a low false positive rate) and high recall (a low false negative
+    rate). The curve provides insights into the balance between false positives
+    and false negatives at various threshold levels, aiding in the assessment of
+    a model's performance.
+
+    Args:
+        y_true (Iterable): True binary labels. The shape should be (`num_samples`,).
+        y_probas (Iterable): Predicted scores or probabilities for each class.
+            These can be probability estimates, confidence scores, or non-thresholded
+            decision values. The shape should be (`num_samples`, `num_classes`).
+        labels (list[str] | None): Optional list of class names to replace
+            numeric values in `y_true` for easier plot interpretation.
+            For example, `labels = ['dog', 'cat', 'owl']` will replace 0 with
+            'dog', 1 with 'cat', and 2 with 'owl' in the plot. If not provided,
+            numeric values from `y_true` will be used.
+        classes_to_plot (list | None): Optional list of unique class values from
+            y_true to be included in the plot. If not specified, all unique
+            classes in y_true will be plotted.
+        interp_size (int): Number of points to interpolate recall values. The
+            recall values will be fixed to `interp_size` uniformly distributed
+            points in the range [0, 1], and the precision will be interpolated
+            accordingly.
+        title (str): Title of the plot. Defaults to "Precision-Recall Curve".
+        split_table (bool): Whether the table should be split into a separate section
+            in the W&B UI. If `True`, the table will be displayed in a section named
+            "Custom Chart Tables". Default is `False`.
 
     Returns:
-        Nothing. To see plots, go to your W&B run page then expand the 'media' tab under
-        'auto visualizations'.
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
+
+    Raises:
+        wandb.Error: If numpy, pandas, or scikit-learn is not installed.
+
 
     Example:
         ```
-        wandb.log({"pr-curve": wandb.plot.pr_curve(y_true, y_probas, labels)})
+        import wandb
+
+        # Example for spam detection (binary classification)
+        y_true = [0, 1, 1, 0, 1]  # 0 = not spam, 1 = spam
+        y_probas = [
+            [0.9, 0.1],  # Predicted probabilities for the first sample (not spam)
+            [0.2, 0.8],  # Second sample (spam), and so on
+            [0.1, 0.9],
+            [0.8, 0.2],
+            [0.3, 0.7]
+        ]
+
+        labels = ['not spam', 'spam']  # Optional class names for readability
+
+        with wandb.init(project="spam-detection") as run:
+            pr_curve = wandb.plot.pr_curve(
+                y_true=y_true,
+                y_probas=y_probas,
+                labels=labels,
+                title="Precision-Recall Curve for Spam Detection",
+            )
+            run.log({"pr-curve": pr_curve})
         ```
     """
     np = util.get_module(
@@ -80,7 +124,7 @@ def pr_curve(
     if classes_to_plot is None:
         classes_to_plot = classes
 
-    precision = dict()
+    precision = {}
     interp_recall = np.linspace(0, 1, interp_size)[::-1]
     indices_to_plot = np.where(np.isin(classes, classes_to_plot))[0]
     for i in indices_to_plot:
@@ -109,12 +153,11 @@ def pr_curve(
             "precision": np.hstack(list(precision.values())),
             "recall": np.tile(interp_recall, len(precision)),
         }
-    )
-    df = df.round(3)
+    ).round(3)
 
     if len(df) > wandb.Table.MAX_ROWS:
         wandb.termwarn(
-            "wandb uses only %d data points to create the plots." % wandb.Table.MAX_ROWS
+            f"Table has a limit of {wandb.Table.MAX_ROWS} rows. Resampling to fit."
         )
         # different sampling could be applied, possibly to ensure endpoints are kept
         df = sklearn_utils.resample(
@@ -125,12 +168,14 @@ def pr_curve(
             stratify=df["class"],
         ).sort_values(["precision", "recall", "class"])
 
-    table = wandb.Table(dataframe=df)
-    title = title or "Precision v. Recall"
-    return wandb.plot_table(
-        "wandb/area-under-curve/v0",
-        table,
-        {"x": "recall", "y": "precision", "class": "class"},
-        {"title": title},
+    return plot_table(
+        data_table=wandb.Table(dataframe=df),
+        vega_spec_name="wandb/area-under-curve/v0",
+        fields={
+            "x": "recall",
+            "y": "precision",
+            "class": "class",
+        },
+        string_fields={"title": title},
         split_table=split_table,
     )