wandb 0.20.2rc20250616__py3-none-win_amd64.whl → 0.21.1__py3-none-win_amd64.whl

wandb/plot/confusion_matrix.py

@@ -23,16 +23,16 @@ def confusion_matrix(
     """Constructs a confusion matrix from a sequence of probabilities or predictions.
 
     Args:
-        probs (Sequence[Sequence[float]] | None): A sequence of predicted probabilities for each
+        probs: A sequence of predicted probabilities for each
             class. The sequence shape should be (N, K) where N is the number of samples
             and K is the number of classes. If provided, `preds` should not be provided.
-        y_true (Sequence[T] | None): A sequence of true labels.
-        preds (Sequence[T] | None): A sequence of predicted class labels. If provided,
+        y_true: A sequence of true labels.
+        preds: A sequence of predicted class labels. If provided,
             `probs` should not be provided.
-        class_names (Sequence[str] | None): Sequence of class names. If not
+        class_names: Sequence of class names. If not
             provided, class names will be defined as "Class_1", "Class_2", etc.
-        title (str): Title of the confusion matrix chart.
-        split_table (bool): Whether the table should be split into a separate section
+        title: Title of the confusion matrix chart.
+        split_table: 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`.
 
@@ -48,75 +48,79 @@ def confusion_matrix(
         wandb.Error: If numpy is not installed.
 
     Examples:
-        1. Logging a confusion matrix with random probabilities for wildlife
-        classification:
-        ```
-        import numpy as np
-        import wandb
-
-        # Define class names for wildlife
-        wildlife_class_names = ["Lion", "Tiger", "Elephant", "Zebra"]
-
-        # Generate random true labels (0 to 3 for 10 samples)
-        wildlife_y_true = np.random.randint(0, 4, size=10)
-
-       # Generate random probabilities for each class (10 samples x 4 classes)
-        wildlife_probs = np.random.rand(10, 4)
-        wildlife_probs = np.exp(wildlife_probs) / np.sum(
-            np.exp(wildlife_probs),
-            axis=1,
-            keepdims=True,
+    Logging a confusion matrix with random probabilities for wildlife
+    classification:
+
+    ```python
+    import numpy as np
+    import wandb
+
+    # Define class names for wildlife
+    wildlife_class_names = ["Lion", "Tiger", "Elephant", "Zebra"]
+
+    # Generate random true labels (0 to 3 for 10 samples)
+    wildlife_y_true = np.random.randint(0, 4, size=10)
+
+    # Generate random probabilities for each class (10 samples x 4 classes)
+    wildlife_probs = np.random.rand(10, 4)
+    wildlife_probs = np.exp(wildlife_probs) / np.sum(
+        np.exp(wildlife_probs),
+        axis=1,
+        keepdims=True,
+    )
+
+    # Initialize W&B run and log confusion matrix
+    with wandb.init(project="wildlife_classification") as run:
+        confusion_matrix = wandb.plot.confusion_matrix(
+            probs=wildlife_probs,
+            y_true=wildlife_y_true,
+            class_names=wildlife_class_names,
+            title="Wildlife Classification Confusion Matrix",
         )
+        run.log({"wildlife_confusion_matrix": confusion_matrix})
+    ```
+
+    In this example, random probabilities are used to generate a confusion
+    matrix.
+
+    Logging a confusion matrix with simulated model predictions and 85%
+    accuracy:
 
-        # Initialize W&B run and log confusion matrix
-        with wandb.init(project="wildlife_classification") as run:
-            confusion_matrix = wandb.plot.confusion_matrix(
-                    probs=wildlife_probs,
-                    y_true=wildlife_y_true,
-                    class_names=wildlife_class_names,
-                    title="Wildlife Classification Confusion Matrix",
-                )
-            run.log({"wildlife_confusion_matrix": confusion_matrix})
-        ```
-        In this example, random probabilities are used to generate a confusion
-        matrix.
-
-        2. Logging a confusion matrix with simulated model predictions and 85%
-        accuracy:
-        ```
-        import numpy as np
-        import wandb
-
-        # Define class names for wildlife
-        wildlife_class_names = ["Lion", "Tiger", "Elephant", "Zebra"]
-
-        # Simulate true labels for 200 animal images (imbalanced distribution)
-        wildlife_y_true = np.random.choice(
-            [0, 1, 2, 3],
-            size=200,
-            p=[0.2, 0.3, 0.25, 0.25],
+    ```python
+    import numpy as np
+    import wandb
+
+    # Define class names for wildlife
+    wildlife_class_names = ["Lion", "Tiger", "Elephant", "Zebra"]
+
+    # Simulate true labels for 200 animal images (imbalanced distribution)
+    wildlife_y_true = np.random.choice(
+        [0, 1, 2, 3],
+        size=200,
+        p=[0.2, 0.3, 0.25, 0.25],
+    )
+
+    # Simulate model predictions with 85% accuracy
+    wildlife_preds = [
+        y_t
+        if np.random.rand() < 0.85
+        else np.random.choice([x for x in range(4) if x != y_t])
+        for y_t in wildlife_y_true
+    ]
+
+    # Initialize W&B run and log confusion matrix
+    with wandb.init(project="wildlife_classification") as run:
+        confusion_matrix = wandb.plot.confusion_matrix(
+            preds=wildlife_preds,
+            y_true=wildlife_y_true,
+            class_names=wildlife_class_names,
+            title="Simulated Wildlife Classification Confusion Matrix",
         )
+        run.log({"wildlife_confusion_matrix": confusion_matrix})
+    ```
 
-        # Simulate model predictions with 85% accuracy
-        wildlife_preds = [
-            y_t
-            if np.random.rand() < 0.85
-            else np.random.choice([x for x in range(4) if x != y_t])
-            for y_t in wildlife_y_true
-        ]
-
-        # Initialize W&B run and log confusion matrix
-        with wandb.init(project="wildlife_classification") as run:
-            confusion_matrix = wandb.plot.confusion_matrix(
-                preds=wildlife_preds,
-                y_true=wildlife_y_true,
-                class_names=wildlife_class_names,
-                title="Simulated Wildlife Classification Confusion Matrix"
-            )
-            run.log({"wildlife_confusion_matrix": confusion_matrix})
-        ```
-        In this example, predictions are simulated with 85% accuracy to generate a
-        confusion matrix.
+    In this example, predictions are simulated with 85% accuracy to generate a
+    confusion matrix.
     """
     np = util.get_module(
         "numpy",

wandb/plot/custom_chart.py

@@ -85,27 +85,50 @@ def plot_table(
     This function creates a custom chart based on a Vega-Lite specification and
     a data table represented by a `wandb.Table` object. The specification needs
     to be predefined and stored in the W&B backend. The function returns a custom
-    chart object that can be logged to W&B using `wandb.log()`.
+    chart object that can be logged to W&B using `wandb.Run.log()`.
 
     Args:
-        vega_spec_name (str): The name or identifier of the Vega-Lite spec
+        vega_spec_name: The name or identifier of the Vega-Lite spec
             that defines the visualization structure.
-        data_table (wandb.Table): A `wandb.Table` object containing the data to be
+        data_table: A `wandb.Table` object containing the data to be
             visualized.
-        fields (dict[str, Any]): A mapping between the fields in the Vega-Lite spec and the
+        fields: A mapping between the fields in the Vega-Lite spec and the
             corresponding columns in the data table to be visualized.
-        string_fields (dict[str, Any] | None): A dictionary for providing values for any string constants
+        string_fields: A dictionary for providing values for any string constants
             required by the custom visualization.
-        split_table (bool): Whether the table should be split into a separate section
+        split_table: 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:
         CustomChart: A custom chart object that can be logged to W&B. To log the
-            chart, pass it to `wandb.log()`.
+            chart, pass the chart object as argument to `wandb.Run.log()`.
 
     Raises:
         wandb.Error: If `data_table` is not a `wandb.Table` object.
+
+    Example:
+    ```python
+    # Create a custom chart using a Vega-Lite spec and the data table.
+    import wandb
+
+    data = [[1, 1], [2, 2], [3, 3], [4, 4], [5, 5]]
+    table = wandb.Table(data=data, columns=["x", "y"])
+    fields = {"x": "x", "y": "y", "title": "MY TITLE"}
+
+    with wandb.init() as run:
+        # Training code goes here
+
+        # Create a custom title with `string_fields`.
+        my_custom_chart = wandb.plot_table(
+            vega_spec_name="wandb/line/v0",
+            data_table=table,
+            fields=fields,
+            string_fields={"title": "Title"},
+        )
+
+        run.log({"custom_chart": my_custom_chart})
+    ```
     """
 
     if not isinstance(data_table, wandb.Table):

wandb/plot/histogram.py

@@ -18,10 +18,10 @@ def histogram(
     """Constructs a histogram chart from a W&B Table.
 
     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
+        table: The W&B Table containing the data for the histogram.
+        value: The label for the bin axis (x-axis).
+        title: The title of the histogram plot.
+        split_table: 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`.
 
@@ -30,31 +30,32 @@ def histogram(
             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)]
+    ```python
+    import math
+    import random
+    import wandb
+
+    # Generate random data
+    data = [[i, random.random() + math.sin(i / 10)] for i in range(100)]
 
-        # Create a W&B Table
-        table = wandb.Table(
-            data=data,
-            columns=["step", "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",
-        )
+    # 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})
-        ```
+    # Log the histogram plot to W&B
+    with wandb.init(...) as run:
+        run.log({"histogram-plot1": histogram})
+    ```
     """
     return plot_table(
         data_table=table,

wandb/plot/line.py

@@ -20,13 +20,13 @@ def line(
     """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
+        table:  The table containing data for the chart.
+        x: Column name for the x-axis values.
+        y: Column name for the y-axis values.
+        stroke: 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
+        title: Title of the chart.
+        split_table: 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`.
 
@@ -35,35 +35,36 @@ def line(
             chart, pass it to `wandb.log()`.
 
     Example:
-       ```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"])
+    ```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"])
+    # 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})
-        ```
+    # 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 plot_table(
         data_table=table,

wandb/plot/line_series.py

@@ -20,18 +20,18 @@ def line_series(
     """Constructs a line series chart.
 
     Args:
-        xs (Iterable[Iterable] | Iterable): Sequence of x values. If a singular
+        xs: 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
+        ys: Sequence of y values, where each iterable represents
             a separate line series.
-        keys (Iterable[str]): Sequence of keys for labeling each line series. If
+        keys: 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
+        title: Title of the chart.
+        xname: Label for the x-axis.
+        split_table: 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`.
 
@@ -40,103 +40,100 @@ def line_series(
             chart, pass it to `wandb.log()`.
 
     Examples:
-        1. Logging a single x array where all y series are plotted against
-           the same x values:
-
-        ```
-        import wandb
-
-        # 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})
-        ```
-
-        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
-
-        # 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})
-        ```
-
-        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
-            ]
-
-            # 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".
-
+    Logging a single x array where all y series are plotted against the same x values:
+
+    ```python
+    import wandb
+
+    # 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})
+    ```
+
+    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).
+
+    Logging multiple x arrays where each y series is plotted against its corresponding x array:
+
+    ```python
+    import wandb
+
+    # 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})
+    ```
+
+    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.
+
+    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
+        ]
+
+        # 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)):