wandb 0.18.5__py3-none-macosx_11_0_arm64.whl → 0.18.6__py3-none-macosx_11_0_arm64.whl

wandb/integration/sklearn/plot/regressor.py

@@ -21,7 +21,7 @@ def regressor(model, X_train, X_test, y_train, y_test, model_name="Regressor"):
 
     Should only be called with a fitted regressor (otherwise an error is thrown).
 
-    Arguments:
+    Args:
         model: (regressor) Takes in a fitted regressor.
         X_train: (arr) Training set features.
         y_train: (arr) Training set labels.
@@ -62,7 +62,7 @@ def outlier_candidates(regressor=None, X=None, y=None):  # noqa: N803
 
     Please note this function fits the model on the training set when called.
 
-    Arguments:
+    Args:
         model: (regressor) Takes in a fitted regressor.
         X: (arr) Training set features.
         y: (arr) Training set labels.
@@ -96,7 +96,7 @@ def residuals(regressor=None, X=None, y=None):  # noqa: N803
 
     Please note this function fits variations of the model on the training set when called.
 
-    Arguments:
+    Args:
         regressor: (regressor) Takes in a fitted regressor.
         X: (arr) Training set features.
         y: (arr) Training set labels.

wandb/integration/sklearn/plot/shared.py

@@ -16,7 +16,7 @@ def summary_metrics(model=None, X=None, y=None, X_test=None, y_test=None):  # no
 
     Should only be called with a fitted model (otherwise an error is thrown).
 
-    Arguments:
+    Args:
         model: (clf or reg) Takes in a fitted regressor or classifier.
         X: (arr) Training set features.
         y: (arr) Training set labels.
@@ -60,7 +60,7 @@ def learning_curve(
 
     Please note this function fits the model to datasets of varying sizes when called.
 
-    Arguments:
+    Args:
         model: (clf or reg) Takes in a fitted regressor or classifier.
         X: (arr) Dataset features.
         y: (arr) Dataset labels.

wandb/integration/tensorboard/log.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 
 import wandb
 import wandb.util
-from wandb.plot.viz import custom_chart
+from wandb.plot import plot_table
 from wandb.sdk.lib import telemetry
 
 if TYPE_CHECKING:
@@ -200,7 +200,7 @@ def tf_summary_to_dict(  # noqa: C901
                 data_table = wandb.Table(data=data, columns=["recall", "precision"])
                 name = namespaced_tag(value.tag, namespace)
 
-                values[name] = custom_chart(
+                values[name] = plot_table(
                     "wandb/line/v0",
                     data_table,
                     {"x": "recall", "y": "precision"},

wandb/integration/ultralytics/callback.py

@@ -114,7 +114,7 @@ class WandBUltralyticsCallback:
         model(["img1.jpeg", "img2.jpeg"])
         ```
 
-    Arguments:
+    Args:
         model: (ultralytics.yolo.engine.model.YOLO) YOLO Model of type
             `ultralytics.yolo.engine.model.YOLO`.
         epoch_logging_interval: (int) interval to log the prediction visualizations
@@ -466,7 +466,7 @@ def add_wandb_callback(
         model(["img1.jpeg", "img2.jpeg"])
         ```
 
-    Arguments:
+    Args:
         model: (ultralytics.yolo.engine.model.YOLO) YOLO Model of type
             `ultralytics.yolo.engine.model.YOLO`.
         epoch_logging_interval: (int) interval to log the prediction visualizations

wandb/integration/xgboost/xgboost.py

@@ -55,7 +55,7 @@ def wandb_callback() -> "Callable":
 class WandbCallback(xgb.callback.TrainingCallback):
     """`WandbCallback` automatically integrates XGBoost with wandb.
 
-    Arguments:
+    Args:
         log_model: (boolean) if True save and upload the model to Weights & Biases Artifacts
         log_feature_importance: (boolean) if True log a feature importance bar plot
         importance_type: (str) one of {weight, gain, cover, total_gain, total_cover} for tree model. weight for linear model.

wandb/jupyter.py

@@ -512,4 +512,3 @@ class Notebook:
                 write(nb, f, version=4)
         except (OSError, validator.NotebookValidationError) as e:
             logger.error("Unable to save ipython session history:\n%s", e)
-            pass

wandb/plot/__init__.py

@@ -1,11 +1,9 @@
-from wandb.plot.bar import bar
-from wandb.plot.confusion_matrix import confusion_matrix
-from wandb.plot.histogram import histogram
-from wandb.plot.line import line
-from wandb.plot.line_series import line_series
-from wandb.plot.pr_curve import pr_curve
-from wandb.plot.roc_curve import roc_curve
-from wandb.plot.scatter import scatter
+"""Chart Visualization Utilities
+
+This module offers a collection of predefined chart types, along with functionality
+for creating custom charts, enabling flexible visualization of your data beyond the
+built-in options.
+"""
 
 __all__ = [
     "line",
@@ -17,3 +15,14 @@ __all__ = [
     "confusion_matrix",
     "line_series",
 ]
+
+from wandb.plot.bar import bar
+from wandb.plot.confusion_matrix import confusion_matrix
+from wandb.plot.custom_chart import CustomChart, plot_table
+from wandb.plot.histogram import histogram
+from wandb.plot.line import line
+from wandb.plot.line_series import line_series
+from wandb.plot.pr_curve import pr_curve
+from wandb.plot.roc_curve import roc_curve
+from wandb.plot.scatter import scatter
+from wandb.plot.viz import Visualize, visualize

wandb/plot/bar.py

@@ -1,45 +1,71 @@
-from typing import TYPE_CHECKING, Optional
+from __future__ import annotations
 
-from .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 bar(
-    table: "wandb.Table",
+    table: wandb.Table,
     label: str,
     value: str,
-    title: Optional[str] = None,
-    split_table: Optional[bool] = False,
-):
-    """Construct a bar plot.
-
-    Arguments:
-        table (wandb.Table): Table of data.
-        label (string): Name of column to use as each bar's label.
-        value (string): Name of column to use as each bar's value.
-        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.
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a bar chart from a wandb.Table of data.
+
+    Args:
+        table (wandb.Table): A table containing the data for the bar chart.
+        label (str): The name of the column to use for the labels of each bar.
+        value (str): The name of the column to use for the values of each bar.
+        title (str): The title of the bar 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:
         ```
-        table = wandb.Table(data=[
-            ['car', random.random()],
-            ['bus', random.random()],
-            ['road', random.random()],
-            ['person', random.random()],
-            ], columns=["class", "acc"])
-        wandb.log({'bar-plot1': wandb.plot.bar(table, "class", "acc")})
+        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 custom_chart(
-        "wandb/bar/v0",
-        table,
-        {"label": label, "value": value},
-        {"title": title},
+    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

@@ -1,100 +1,181 @@
-from typing import Optional, Sequence
+from __future__ import annotations
 
+from typing import TYPE_CHECKING, Sequence, TypeVar
+
+import wandb
 from wandb import util
-from wandb.data_types import Table
-from wandb.plot.viz import custom_chart
+from wandb.plot.custom_chart import plot_table
+
+if TYPE_CHECKING:
+    from wandb.plot.custom_chart import CustomChart
 
-chart_limit = Table.MAX_ROWS
+T = TypeVar("T")
 
 
 def confusion_matrix(
-    probs: Optional[Sequence[Sequence]] = None,
-    y_true: Optional[Sequence] = None,
-    preds: Optional[Sequence] = None,
-    class_names: Optional[Sequence[str]] = None,
-    title: Optional[str] = None,
-    split_table: Optional[bool] = False,
-):
-    """Compute a multi-run confusion matrix.
-
-    Arguments:
-        probs (2-d arr): Shape [n_examples, n_classes]
-        y_true (arr): Array of label indices.
-        preds (arr): Array of predicted label indices.
-        class_names (arr): Array of class names.
-        split_table (bool): If True, adds "Custom Chart Tables/" to the key of the table so that it's logged in a different section.
+    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 (Sequence[Sequence[float]] | None): 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,
+            `probs` should not be provided.
+        class_names (Sequence[str] | None): 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
+            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:
+        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:
+        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,
+        )
+
+        # 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.
 
-    Example:
+        2. Logging a confusion matrix with simulated model predictions and 85%
+        accuracy:
         ```
-        vals = np.random.uniform(size=(10, 5))
-        probs = np.exp(vals)/np.sum(np.exp(vals), keepdims=True, axis=1)
-        y_true = np.random.randint(0, 5, size=(10))
-        labels = ["Cat", "Dog", "Bird", "Fish", "Horse"]
-        wandb.log({'confusion_matrix': wandb.plot.confusion_matrix(probs, y_true=y_true, class_names=labels)})
+        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="confusion matrix requires the numpy library, install with `pip install numpy`",
-    )
-    # change warning
-    assert probs is None or len(probs.shape) == 2, (
-        "confusion_matrix has been updated to accept"
-        " probabilities as the default first argument. Use preds=..."
+        required=(
+            "numpy is required to use wandb.plot.confusion_matrix, "
+            "install with `pip install numpy`",
+        ),
     )
 
-    assert (probs is None or preds is None) and not (
-        probs is None and preds is None
-    ), "Must provide probabilities or predictions but not both to confusion matrix"
+    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()
 
-    assert len(preds) == len(
-        y_true
-    ), "Number of predictions and label indices must match"
+    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_inds = [i for i in range(n_classes)]
-        assert max(preds) <= len(
-            class_names
-        ), "Higher predicted index than number of classes"
-        assert max(y_true) <= len(
-            class_names
-        ), "Higher label class index than number of classes"
+        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_inds = set(preds).union(set(y_true))
-        n_classes = len(class_inds)
-        class_names = [f"Class_{i}" for i in range(1, n_classes + 1)]
-
-    # get mapping of inds to class index in case user has weird prediction indices
-    class_mapping = {}
-    for i, val in enumerate(sorted(list(class_inds))):
-        class_mapping[val] = i
+        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 = []
-    for i in range(n_classes):
-        for j in range(n_classes):
-            data.append([class_names[i], class_names[j], counts[i, j]])
-
-    fields = {
-        "Actual": "Actual",
-        "Predicted": "Predicted",
-        "nPredictions": "nPredictions",
-    }
-    title = title or ""
-    return custom_chart(
-        "wandb/confusion_matrix/v1",
-        Table(columns=["Actual", "Predicted", "nPredictions"], data=data),
-        fields,
-        {"title": title},
+    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,124 @@
+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.log()`.
+
+    Args:
+        vega_spec_name (str): 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
+            visualized.
+        fields (dict[str, Any]): 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
+            required by the custom visualization.
+        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:
+        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 `data_table` is not a `wandb.Table` object.
+    """
+
+    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,
+        ),
+    )