wandb 0.21.2__py3-none-macosx_12_0_arm64.whl

wandb/plot/bar.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+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 bar(
+    table: wandb.Table,
+    label: str,
+    value: str,
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a bar chart from a wandb.Table of data.
+
+    Args:
+        table: A table containing the data for the bar chart.
+        label: The name of the column to use for the labels of each bar.
+        value: The name of the column to use for the values of each bar.
+        title: The title of the bar 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`.
+
+    Returns:
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
+
+    Example:
+
+    ```python
+    import random
+    import wandb
+
+    # Generate random data for the table
+    data = [
+        ["car", random.uniform(0, 1)],
+        ["bus", random.uniform(0, 1)],
+        ["road", random.uniform(0, 1)],
+        ["person", random.uniform(0, 1)],
+    ]
+
+    # Create a table with the data
+    table = wandb.Table(data=data, columns=["class", "accuracy"])
+
+    # Initialize a W&B run and log the bar plot
+    with wandb.init(project="bar_chart") as run:
+        # Create a bar plot from the table
+        bar_plot = wandb.plot.bar(
+            table=table,
+            label="class",
+            value="accuracy",
+            title="Object Classification Accuracy",
+        )
+
+        # Log the bar chart to W&B
+        run.log({"bar_plot": bar_plot})
+    ```
+    """
+    return plot_table(
+        data_table=table,
+        vega_spec_name="wandb/bar/v0",
+        fields={"label": label, "value": value},
+        string_fields={"title": title},
+        split_table=split_table,
+    )

wandb/plot/confusion_matrix.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence, TypeVar
+
+import wandb
+from wandb import util
+from wandb.plot.custom_chart import plot_table
+
+if TYPE_CHECKING:
+    from wandb.plot.custom_chart import CustomChart
+
+T = TypeVar("T")
+
+
+def confusion_matrix(
+    probs: Sequence[Sequence[float]] | None = None,
+    y_true: Sequence[T] | None = None,
+    preds: Sequence[T] | None = None,
+    class_names: Sequence[str] | None = None,
+    title: str = "Confusion Matrix Curve",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a confusion matrix from a sequence of probabilities or predictions.
+
+    Args:
+        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: A sequence of true labels.
+        preds: A sequence of predicted class labels. If provided,
+            `probs` should not be provided.
+        class_names: Sequence of class names. If not
+            provided, class names will be defined as "Class_1", "Class_2", etc.
+        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`.
+
+    Returns:
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
+
+    Raises:
+        ValueError: If both `probs` and `preds` are provided or if the number of
+            predictions and true labels are not equal. If the number of unique
+            predicted classes exceeds the number of class names or if the number of
+            unique true labels exceeds the number of class names.
+        wandb.Error: If numpy is not installed.
+
+    Examples:
+    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:
+
+    ```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})
+    ```
+
+    In this example, predictions are simulated with 85% accuracy to generate a
+    confusion matrix.
+    """
+    np = util.get_module(
+        "numpy",
+        required=(
+            "numpy is required to use wandb.plot.confusion_matrix, "
+            "install with `pip install numpy`",
+        ),
+    )
+
+    if probs is not None and preds is not None:
+        raise ValueError("Only one of `probs` or `preds` should be provided, not both.")
+
+    if probs is not None:
+        preds = np.argmax(probs, axis=1).tolist()
+
+    if len(preds) != len(y_true):
+        raise ValueError("The number of predictions and true labels must be equal.")
+
+    if class_names is not None:
+        n_classes = len(class_names)
+        class_idx = list(range(n_classes))
+        if len(set(preds)) > len(class_names):
+            raise ValueError(
+                "The number of unique predicted classes exceeds the number of class names."
+            )
+
+        if len(set(y_true)) > len(class_names):
+            raise ValueError(
+                "The number of unique true labels exceeds the number of class names."
+            )
+    else:
+        class_idx = set(preds).union(set(y_true))
+        n_classes = len(class_idx)
+        class_names = [f"Class_{i + 1}" for i in range(n_classes)]
+
+    # Create a mapping from class name to index
+    class_mapping = {val: i for i, val in enumerate(sorted(list(class_idx)))}
+
+    counts = np.zeros((n_classes, n_classes))
+    for i in range(len(preds)):
+        counts[class_mapping[y_true[i]], class_mapping[preds[i]]] += 1
+
+    data = [
+        [class_names[i], class_names[j], counts[i, j]]
+        for i in range(n_classes)
+        for j in range(n_classes)
+    ]
+
+    return plot_table(
+        data_table=wandb.Table(
+            columns=["Actual", "Predicted", "nPredictions"],
+            data=data,
+        ),
+        vega_spec_name="wandb/confusion_matrix/v1",
+        fields={
+            "Actual": "Actual",
+            "Predicted": "Predicted",
+            "nPredictions": "nPredictions",
+        },
+        string_fields={"title": title},
+        split_table=split_table,
+    )

wandb/plot/custom_chart.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import wandb
+
+
+@dataclass
+class CustomChartSpec:
+    spec_name: str
+    fields: dict[str, Any]
+    string_fields: dict[str, Any]
+    key: str = ""
+    panel_type: str = "Vega2"
+    split_table: bool = False
+
+    @property
+    def table_key(self) -> str:
+        if not self.key:
+            raise wandb.Error("Key for the custom chart spec is not set.")
+        if self.split_table:
+            return f"Custom Chart Tables/{self.key}_table"
+        return f"{self.key}_table"
+
+    @property
+    def config_value(self) -> dict[str, Any]:
+        return {
+            "panel_type": self.panel_type,
+            "panel_config": {
+                "panelDefId": self.spec_name,
+                "fieldSettings": self.fields,
+                "stringSettings": self.string_fields,
+                "transform": {"name": "tableWithLeafColNames"},
+                "userQuery": {
+                    "queryFields": [
+                        {
+                            "name": "runSets",
+                            "args": [{"name": "runSets", "value": "${runSets}"}],
+                            "fields": [
+                                {"name": "id", "fields": []},
+                                {"name": "name", "fields": []},
+                                {"name": "_defaultColorIndex", "fields": []},
+                                {
+                                    "name": "summaryTable",
+                                    "args": [
+                                        {
+                                            "name": "tableKey",
+                                            "value": self.table_key,
+                                        }
+                                    ],
+                                    "fields": [],
+                                },
+                            ],
+                        }
+                    ],
+                },
+            },
+        }
+
+    @property
+    def config_key(self) -> tuple[str, str, str]:
+        return ("_wandb", "visualize", self.key)
+
+
+@dataclass
+class CustomChart:
+    table: wandb.Table
+    spec: CustomChartSpec
+
+    def set_key(self, key: str):
+        """Sets the key for the spec and updates dependent configurations."""
+        self.spec.key = key
+
+
+def plot_table(
+    vega_spec_name: str,
+    data_table: wandb.Table,
+    fields: dict[str, Any],
+    string_fields: dict[str, Any] | None = None,
+    split_table: bool = False,
+) -> CustomChart:
+    """Creates a custom charts using a Vega-Lite specification and a `wandb.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.Run.log()`.
+
+    Args:
+        vega_spec_name: The name or identifier of the Vega-Lite spec
+            that defines the visualization structure.
+        data_table: A `wandb.Table` object containing the data to be
+            visualized.
+        fields: A mapping between the fields in the Vega-Lite spec and the
+            corresponding columns in the data table to be visualized.
+        string_fields: A dictionary for providing values for any string constants
+            required by the custom visualization.
+        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 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):
+        raise wandb.Error(
+            f"Expected `data_table` to be `wandb.Table` type, instead got {type(data_table).__name__}"
+        )
+
+    return CustomChart(
+        table=data_table,
+        spec=CustomChartSpec(
+            spec_name=vega_spec_name,
+            fields=fields,
+            string_fields=string_fields or {},
+            split_table=split_table,
+        ),
+    )

wandb/plot/histogram.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+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,
+    value: str,
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a histogram chart from a W&B Table.
+
+    Args:
+        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`.
+
+    Returns:
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
+
+    Example:
+
+    ```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 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 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

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+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,
+    x: str,
+    y: str,
+    stroke: str | None = None,
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a customizable line chart.
+
+    Args:
+        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: 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`.
+
+    Returns:
+       CustomChart: A custom chart object that can be logged to W&B. To log the
+            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"])
+
+    # 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 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,
+    )