wandb 0.19.1__py3-none-musllinux_1_2_aarch64.whl

wandb/plot/pr_curve.py

@@ -0,0 +1,185 @@
+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 (Iterable): True binary labels. The shape should be (`num_samples`,).
+        y_probas (Iterable): 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 (list[str] | None): 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 (list | None): 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 (int): 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 (str): Title of the plot. Defaults to "Precision-Recall Curve".
+        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 numpy, pandas, or scikit-learn is not installed.
+
+
+    Example:
+        ```
+        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 (Sequence[numbers.Number]): The true class labels (ground truth)
+            for the target variable. Shape should be (num_samples,).
+        y_probas (Sequence[Sequence[float]]): The predicted probabilities or
+            decision scores for each class. Shape should be (num_samples, num_classes).
+        labels (list[str]): 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 (list[numbers.Number]): 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 (str): Title of the ROC curve plot. Default is "ROC Curve".
+        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 numpy, pandas, or scikit-learn are not found.
+
+    Example:
+        ```
+        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 (wandb.Table): The W&B Table containing the data to visualize.
+        x (str): The name of the column used for the x-axis.
+        y (str): The name of the column used for the y-axis.
+        title (str): The title of the scatter 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:
+        ```
+        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,
+    )

wandb/plot/utils.py

@@ -0,0 +1,183 @@
+from typing import Iterable, Sequence
+
+import wandb
+from wandb import util
+
+
+def test_missing(**kwargs):
+    np = util.get_module("numpy", required="Logging plots requires numpy")
+    pd = util.get_module("pandas", required="Logging dataframes requires pandas")
+    scipy = util.get_module("scipy", required="Logging scipy matrices requires scipy")
+
+    test_passed = True
+    for k, v in kwargs.items():
+        # Missing/empty params/datapoint arrays
+        if v is None:
+            wandb.termerror("{} is None. Please try again.".format(k))
+            test_passed = False
+        if (k == "X") or (k == "X_test"):
+            if isinstance(v, scipy.sparse.csr.csr_matrix):
+                v = v.toarray()
+            elif isinstance(v, (pd.DataFrame, pd.Series)):
+                v = v.to_numpy()
+            elif isinstance(v, list):
+                v = np.asarray(v)
+
+            # Warn the user about missing values
+            missing = 0
+            missing = np.count_nonzero(pd.isnull(v))
+            if missing > 0:
+                wandb.termwarn("%s contains %d missing values. " % (k, missing))
+                test_passed = False
+            # Ensure the dataset contains only integers
+            non_nums = 0
+            if v.ndim == 1:
+                non_nums = sum(
+                    1
+                    for val in v
+                    if (
+                        not isinstance(val, (int, float, complex))
+                        and not isinstance(val, np.number)
+                    )
+                )
+            else:
+                non_nums = sum(
+                    1
+                    for sl in v
+                    for val in sl
+                    if (
+                        not isinstance(val, (int, float, complex))
+                        and not isinstance(val, np.number)
+                    )
+                )
+            if non_nums > 0:
+                wandb.termerror(
+                    f"{k} contains values that are not numbers. Please vectorize, "
+                    f"label encode or one hot encode {k} and call the plotting function again."
+                )
+                test_passed = False
+    return test_passed
+
+
+def test_fitted(model):
+    np = util.get_module("numpy", required="Logging plots requires numpy")
+    _ = util.get_module("pandas", required="Logging dataframes requires pandas")
+    _ = util.get_module("scipy", required="Logging scipy matrices requires scipy")
+    scikit_utils = util.get_module(
+        "sklearn.utils",
+        required="roc requires the scikit utils submodule, install with `pip install scikit-learn`",
+    )
+    scikit_exceptions = util.get_module(
+        "sklearn.exceptions",
+        "roc requires the scikit preprocessing submodule, install with `pip install scikit-learn`",
+    )
+
+    try:
+        model.predict(np.zeros((7, 3)))
+    except scikit_exceptions.NotFittedError:
+        wandb.termerror("Please fit the model before passing it in.")
+        return False
+    except AttributeError:
+        # Some clustering models (LDA, PCA, Agglomerative) don't implement ``predict``
+        try:
+            scikit_utils.validation.check_is_fitted(
+                model,
+                [
+                    "coef_",
+                    "estimator_",
+                    "labels_",
+                    "n_clusters_",
+                    "children_",
+                    "components_",
+                    "n_components_",
+                    "n_iter_",
+                    "n_batch_iter_",
+                    "explained_variance_",
+                    "singular_values_",
+                    "mean_",
+                ],
+                all_or_any=any,
+            )
+            return True
+        except scikit_exceptions.NotFittedError:
+            wandb.termerror("Please fit the model before passing it in.")
+            return False
+    except Exception:
+        # Assume it's fitted, since ``NotFittedError`` wasn't raised
+        return True
+
+
+def encode_labels(df):
+    _ = util.get_module("pandas", required="Logging dataframes requires pandas")
+    preprocessing = util.get_module(
+        "sklearn.preprocessing",
+        "roc requires the scikit preprocessing submodule, install with `pip install scikit-learn`",
+    )
+
+    le = preprocessing.LabelEncoder()
+    # apply le on categorical feature columns
+    categorical_cols = df.select_dtypes(
+        exclude=["int", "float", "float64", "float32", "int32", "int64"]
+    ).columns
+    df[categorical_cols] = df[categorical_cols].apply(lambda col: le.fit_transform(col))
+
+
+def test_types(**kwargs):
+    np = util.get_module("numpy", required="Logging plots requires numpy")
+    pd = util.get_module("pandas", required="Logging dataframes requires pandas")
+    _ = util.get_module("scipy", required="Logging scipy matrices requires scipy")
+
+    base = util.get_module(
+        "sklearn.base",
+        "roc requires the scikit base submodule, install with `pip install scikit-learn`",
+    )
+
+    test_passed = True
+    for k, v in kwargs.items():
+        # check for incorrect types
+        if (
+            (k == "X")
+            or (k == "X_test")
+            or (k == "y")
+            or (k == "y_test")
+            or (k == "y_true")
+            or (k == "y_probas")
+            or (k == "x_labels")
+            or (k == "y_labels")
+            or (k == "matrix_values")
+        ):
+            # FIXME: do this individually
+            if not isinstance(
+                v,
+                (
+                    Sequence,
+                    Iterable,
+                    np.ndarray,
+                    np.generic,
+                    pd.DataFrame,
+                    pd.Series,
+                    list,
+                ),
+            ):
+                wandb.termerror("{} is not an array. Please try again.".format(k))
+                test_passed = False
+        # check for classifier types
+        if k == "model":
+            if (not base.is_classifier(v)) and (not base.is_regressor(v)):
+                wandb.termerror(
+                    "{} is not a classifier or regressor. Please try again.".format(k)
+                )
+                test_passed = False
+        elif k == "clf" or k == "binary_clf":
+            if not (base.is_classifier(v)):
+                wandb.termerror("{} is not a classifier. Please try again.".format(k))
+                test_passed = False
+        elif k == "regressor":
+            if not base.is_regressor(v):
+                wandb.termerror("{} is not a regressor. Please try again.".format(k))
+                test_passed = False
+        elif k == "clusterer":
+            if not (getattr(v, "_estimator_type", None) == "clusterer"):
+                wandb.termerror("{} is not a clusterer. Please try again.".format(k))
+                test_passed = False
+    return test_passed

wandb/plot/viz.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from wandb.data_types import Table
+from wandb.errors import Error
+
+
+@dataclass
+class VisualizeSpec:
+    name: str
+    key: str = ""
+
+    @property
+    def config_value(self) -> dict[str, Any]:
+        return {
+            "id": self.name,
+            "historyFieldSettings": {"x-axis": "_step", "key": self.key},
+        }
+
+    @property
+    def config_key(self) -> tuple[str, str, str]:
+        return ("_wandb", "viz", self.key)
+
+
+@dataclass
+class Visualize:
+    table: Table
+    spec: VisualizeSpec
+
+    def set_key(self, key: str) -> None:
+        self.spec.key = key
+
+
+def visualize(id: str, value: Table) -> Visualize:
+    if not isinstance(value, Table):
+        raise Error(
+            f"Expected `value` to be `wandb.Table` type, instead got {type(value).__name__}"
+        )
+    return Visualize(table=value, spec=VisualizeSpec(name=id))