wandb 0.19.1__py3-none-musllinux_1_2_aarch64.whl

wandb/plot/confusion_matrix.py

@@ -0,0 +1,181 @@
+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 (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:
+        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.
+
+        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],
+        )
+
+        # 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,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,
+        ),
+    )

wandb/plot/histogram.py

@@ -0,0 +1,65 @@
+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 (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:
+        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)]
+
+        # 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,74 @@
+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 (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:
+       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,
+    )

wandb/plot/line_series.py

@@ -0,0 +1,176 @@
+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: 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:
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            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".
+
+    """
+    # 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] * 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)
+
+    data = [
+        [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"],
+    )
+
+    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,
+    )