wandb 0.21.2__py3-none-macosx_12_0_x86_64.whl

wandb/plot/line_series.py

@@ -0,0 +1,173 @@
+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: 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: Sequence of y values, where each iterable represents
+            a separate line series.
+        keys: Sequence of keys for labeling each line series. If
+            not provided, keys will be automatically generated as "line_1",
+            "line_2", etc.
+        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`.
+
+    Returns:
+        CustomChart: A custom chart object that can be logged to W&B. To log the
+            chart, pass it to `wandb.log()`.
+
+    Examples:
+    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)):
+        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,
+    )

wandb/plot/pr_curve.py

@@ -0,0 +1,186 @@
+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
+
+
+T = TypeVar("T")
+
+
+def pr_curve(
+    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: True binary labels. The shape should be (`num_samples`,).
+        y_probas: 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: 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: 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: 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: Title of the plot. Defaults to "Precision-Recall Curve".
+        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:
+        wandb.Error: If NumPy, pandas, or scikit-learn is not installed.
+
+
+    Example:
+
+    ```python
+    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(
+        "numpy",
+        required="roc requires the numpy library, install with `pip install numpy`",
+    )
+    pd = util.get_module(
+        "pandas",
+        required="roc requires the pandas library, install with `pip install pandas`",
+    )
+    sklearn_metrics = util.get_module(
+        "sklearn.metrics",
+        "roc requires the scikit library, install with `pip install scikit-learn`",
+    )
+    sklearn_utils = util.get_module(
+        "sklearn.utils",
+        "roc requires the scikit library, install with `pip install scikit-learn`",
+    )
+
+    def _step(x):
+        y = np.array(x)
+        for i in range(1, len(y)):
+            y[i] = max(y[i], y[i - 1])
+        return y
+
+    y_true = np.array(y_true)
+    y_probas = np.array(y_probas)
+
+    if not test_missing(y_true=y_true, y_probas=y_probas):
+        return
+    if not test_types(y_true=y_true, y_probas=y_probas):
+        return
+
+    classes = np.unique(y_true)
+    if classes_to_plot is None:
+        classes_to_plot = classes
+
+    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:
+        if labels is not None and (
+            isinstance(classes[i], int) or isinstance(classes[0], np.integer)
+        ):
+            class_label = labels[classes[i]]
+        else:
+            class_label = classes[i]
+
+        cur_precision, cur_recall, _ = sklearn_metrics.precision_recall_curve(
+            y_true, y_probas[:, i], pos_label=classes[i]
+        )
+        # smooth the precision (monotonically increasing)
+        cur_precision = _step(cur_precision)
+
+        # reverse order so that recall in ascending
+        cur_precision = cur_precision[::-1]
+        cur_recall = cur_recall[::-1]
+        indices = np.searchsorted(cur_recall, interp_recall, side="left")
+        precision[class_label] = cur_precision[indices]
+
+    df = pd.DataFrame(
+        {
+            "class": np.hstack([[k] * len(v) for k, v in precision.items()]),
+            "precision": np.hstack(list(precision.values())),
+            "recall": np.tile(interp_recall, len(precision)),
+        }
+    ).round(3)
+
+    if len(df) > wandb.Table.MAX_ROWS:
+        wandb.termwarn(
+            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(
+            df,
+            replace=False,
+            n_samples=wandb.Table.MAX_ROWS,
+            random_state=42,
+            stratify=df["class"],
+        ).sort_values(["precision", "recall", "class"])
+
+    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,
+            "x-axis-title": "Recall",
+            "y-axis-title": "Precision",
+        },
+        split_table=split_table,
+    )

wandb/plot/roc_curve.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import numbers
+from typing import TYPE_CHECKING, Sequence
+
+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
+
+
+def roc_curve(
+    y_true: Sequence[numbers.Number],
+    y_probas: Sequence[Sequence[float]] | None = None,
+    labels: list[str] | None = None,
+    classes_to_plot: list[numbers.Number] | None = None,
+    title: str = "ROC Curve",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs Receiver Operating Characteristic (ROC) curve chart.
+
+    Args:
+        y_true: The true class labels (ground truth)
+            for the target variable. Shape should be (num_samples,).
+        y_probas: The predicted probabilities or
+            decision scores for each class. Shape should be (num_samples, num_classes).
+        labels: Human-readable labels corresponding to the class
+            indices in `y_true`. For example, if `labels=['dog', 'cat']`,
+            class 0 will be displayed as 'dog' and class 1 as 'cat' in the plot.
+            If None, the raw class indices from `y_true` will be used.
+            Default is None.
+        classes_to_plot: A subset of unique class labels
+            to include in the ROC curve. If None, all classes in `y_true` will
+            be plotted. Default is None.
+        title: Title of the ROC curve plot. Default is "ROC Curve".
+        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:
+        wandb.Error: If numpy, pandas, or scikit-learn are not found.
+
+    Example:
+    ```python
+    import numpy as np
+    import wandb
+
+    # Simulate a medical diagnosis classification problem with three diseases
+    n_samples = 200
+    n_classes = 3
+
+    # True labels: assign "Diabetes", "Hypertension", or "Heart Disease" to
+    # each sample
+    disease_labels = ["Diabetes", "Hypertension", "Heart Disease"]
+    # 0: Diabetes, 1: Hypertension, 2: Heart Disease
+    y_true = np.random.choice([0, 1, 2], size=n_samples)
+
+    # Predicted probabilities: simulate predictions, ensuring they sum to 1
+    # for each sample
+    y_probas = np.random.dirichlet(np.ones(n_classes), size=n_samples)
+
+    # Specify classes to plot (plotting all three diseases)
+    classes_to_plot = [0, 1, 2]
+
+    # Initialize a W&B run and log a ROC curve plot for disease classification
+    with wandb.init(project="medical_diagnosis") as run:
+        roc_plot = wandb.plot.roc_curve(
+            y_true=y_true,
+            y_probas=y_probas,
+            labels=disease_labels,
+            classes_to_plot=classes_to_plot,
+            title="ROC Curve for Disease Classification",
+        )
+        run.log({"roc-curve": roc_plot})
+    ```
+    """
+    np = util.get_module(
+        "numpy",
+        required="roc requires the numpy library, install with `pip install numpy`",
+    )
+    pd = util.get_module(
+        "pandas",
+        required="roc requires the pandas library, install with `pip install pandas`",
+    )
+    sklearn_metrics = util.get_module(
+        "sklearn.metrics",
+        "roc requires the scikit library, install with `pip install scikit-learn`",
+    )
+    sklearn_utils = util.get_module(
+        "sklearn.utils",
+        "roc requires the scikit library, install with `pip install scikit-learn`",
+    )
+
+    y_true = np.array(y_true)
+    y_probas = np.array(y_probas)
+
+    if not test_missing(y_true=y_true, y_probas=y_probas):
+        return
+    if not test_types(y_true=y_true, y_probas=y_probas):
+        return
+
+    classes = np.unique(y_true)
+    if classes_to_plot is None:
+        classes_to_plot = classes
+
+    fpr = {}
+    tpr = {}
+    indices_to_plot = np.where(np.isin(classes, classes_to_plot))[0]
+    for i in indices_to_plot:
+        if labels is not None and (
+            isinstance(classes[i], int) or isinstance(classes[0], np.integer)
+        ):
+            class_label = labels[classes[i]]
+        else:
+            class_label = classes[i]
+
+        fpr[class_label], tpr[class_label], _ = sklearn_metrics.roc_curve(
+            y_true, y_probas[..., i], pos_label=classes[i]
+        )
+
+    df = pd.DataFrame(
+        {
+            "class": np.hstack([[k] * len(v) for k, v in fpr.items()]),
+            "fpr": np.hstack(list(fpr.values())),
+            "tpr": np.hstack(list(tpr.values())),
+        }
+    ).round(3)
+
+    if len(df) > wandb.Table.MAX_ROWS:
+        wandb.termwarn(
+            f"wandb uses only {wandb.Table.MAX_ROWS} data points to create the plots."
+        )
+        # different sampling could be applied, possibly to ensure endpoints are kept
+        df = sklearn_utils.resample(
+            df,
+            replace=False,
+            n_samples=wandb.Table.MAX_ROWS,
+            random_state=42,
+            stratify=df["class"],
+        ).sort_values(["fpr", "tpr", "class"])
+
+    return plot_table(
+        data_table=wandb.Table(dataframe=df),
+        vega_spec_name="wandb/area-under-curve/v0",
+        fields={
+            "x": "fpr",
+            "y": "tpr",
+            "class": "class",
+        },
+        string_fields={
+            "title": title,
+            "x-axis-title": "False positive rate",
+            "y-axis-title": "True positive rate",
+        },
+        split_table=split_table,
+    )

wandb/plot/scatter.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 scatter(
+    table: wandb.Table,
+    x: str,
+    y: str,
+    title: str = "",
+    split_table: bool = False,
+) -> CustomChart:
+    """Constructs a scatter plot from a wandb.Table of data.
+
+    Args:
+        table: The W&B Table containing the data to visualize.
+        x: The name of the column used for the x-axis.
+        y: The name of the column used for the y-axis.
+        title: The title of the scatter 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
+
+    # Simulate temperature variations at different altitudes over time
+    data = [
+        [i, random.uniform(-10, 20) - 0.005 * i + 5 * math.sin(i / 50)]
+        for i in range(300)
+    ]
+
+    # Create W&B table with altitude (m) and temperature (°C) columns
+    table = wandb.Table(data=data, columns=["altitude (m)", "temperature (°C)"])
+
+    # Initialize W&B run and log the scatter plot
+    with wandb.init(project="temperature-altitude-scatter") as run:
+        # Create and log the scatter plot
+        scatter_plot = wandb.plot.scatter(
+            table=table,
+            x="altitude (m)",
+            y="temperature (°C)",
+            title="Altitude vs Temperature",
+        )
+        run.log({"altitude-temperature-scatter": scatter_plot})
+    ```
+    """
+    return plot_table(
+        data_table=table,
+        vega_spec_name="wandb/scatter/v0",
+        fields={"x": x, "y": y},
+        string_fields={"title": title},
+        split_table=split_table,
+    )