active-vision 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

active_vision/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.3.0"
+__version__ = "0.4.1"
 
 from .core import *

active_vision/core.py

@@ -1,14 +1,29 @@
-import pandas as pd
-from loguru import logger
-from fastai.vision.all import *
-import torch
-import numpy as np
 import bisect
-
+import os
 import warnings
 from typing import Callable
 
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn.functional as F
+from fastai.vision.all import (
+    CrossEntropyLossFlat,
+    ImageDataLoaders,
+    Resize,
+    ShowGraphCallback,
+    accuracy,
+    load_learner,
+    minimum,
+    slide,
+    steep,
+    valley,
+    vision_learner,
+)
+from loguru import logger
+
 warnings.filterwarnings("ignore", category=FutureWarning)
+pd.set_option("display.max_colwidth", 50)
 
 
 class ActiveLearner:
@@ -33,17 +48,61 @@ class ActiveLearner:
             eval_df (pd.DataFrame): Predictions on evaluation data
     """
 
-    def __init__(self, model_name: str | Callable):
-        self.model = self.load_model(model_name)
+    def __init__(self, name: str):
+        self.name = name
+        self.model = None
+        self.callbacks = [ShowGraphCallback()]
+        self.loss_fn = CrossEntropyLossFlat()
 
-    def load_model(self, model_name: str | Callable):
-        if isinstance(model_name, Callable):
-            logger.info(f"Loading fastai model {model_name.__name__}")
-            return model_name
+    def load_model(
+        self, model: str | Callable, pretrained: bool = True, device: str = None
+    ):
+        self.model = model
+        self.device = self._detect_optimal_device() if device is None else device
+        self.pretrained = pretrained
 
-        if isinstance(model_name, str):
-            logger.info(f"Loading timm model {model_name}")
-            return model_name
+        if isinstance(model, Callable):
+            logger.info(
+                f"Loading a {'pretrained ' if pretrained else 'non-pretrained '}fastai model `{model.__name__}` on `{self.device}`"
+            )
+
+        if isinstance(model, str):
+            logger.info(
+                f"Loading a {'pretrained ' if pretrained else 'non-pretrained '}timm model `{model}` on `{self.device}`"
+            )
+
+    def _detect_optimal_device(self):
+        """Determine the appropriate device and return device type."""
+        cuda_available = torch.cuda.is_available()
+        mps_available = (
+            hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
+        )
+
+        device = "cpu"
+        if cuda_available:
+            device = "cuda"
+            logger.info("CUDA GPU detected - will load model on GPU")
+        elif mps_available:
+            device = "mps"
+            logger.info("Apple Silicon GPU detected - will load model on MPS")
+        else:
+            logger.info("No GPU detected - will load model on CPU")
+
+        return device
+
+    def _optimize_learner(self, device):
+        """Apply optimization settings to learner based on device."""
+        if device != "cpu":
+            self.learn.to_fp16()
+            logger.info("Enabled mixed precision training")
+
+    def _finalize_setup(self):
+        """Set common attributes after learner creation."""
+        self.train_set = self.learn.dls.train_ds.items
+        self.valid_set = self.learn.dls.valid_ds.items
+        self.class_names = self.dls.vocab
+        self.num_classes = self.dls.c
+        logger.info("Done. Ready to train.")
 
     def load_dataset(
         self,
@@ -54,14 +113,23 @@ class ActiveLearner:
         batch_size: int = 16,
         image_size: int = 224,
         batch_tfms: Callable = None,
+        seed: int = None,
         learner_path: str = None,
     ):
-        logger.info(f"Loading dataset from {filepath_col} and {label_col}")
+        logger.info(f"Loading dataset from `{filepath_col}` and `{label_col}` columns")
+        self.image_size = image_size
+        self.batch_size = batch_size
+        self.seed = seed
+        self.eval_accuracy = None
+        self.train_accuracy = None
+        self.valid_accuracy = None
+
+        self.dataset = df
 
-        logger.info("Creating dataloaders")
         self.dls = ImageDataLoaders.from_df(
             df,
             path=".",
+            seed=seed,
             valid_pct=valid_pct,
             fn_col=filepath_col,
             label_col=label_col,
@@ -70,26 +138,37 @@ class ActiveLearner:
             batch_tfms=batch_tfms,
         )
 
-        if learner_path:
-            logger.info(f"Loading learner from {learner_path}")
-            gpu_available = torch.cuda.is_available()
-            if gpu_available:
-                logger.info(f"Loading learner on GPU.")
+        if self.model is None:
+            logger.info(
+                "No model loaded, using a pretrained timm `resnet18`. Load a model by calling `load_model(model_name)`"
+            )
+            self.load_model("resnet18")
+
+        try:
+            if learner_path:
+                logger.info(f"Loading learner from {learner_path}")
+                self.learn = load_learner(learner_path, cpu=(self.device == "cpu"))
+                self.learn.dls = self.dls
             else:
-                logger.info(f"Loading learner on CPU.")
+                logger.info("Creating new learner")
+                self.learn = vision_learner(
+                    self.dls,
+                    self.model,
+                    metrics=accuracy,
+                    pretrained=self.pretrained,
+                    cbs=self.callbacks,
+                    loss_func=self.loss_fn,
+                )
 
-            self.learn = load_learner(learner_path, cpu=not gpu_available)
-        else:
-            logger.info("Creating learner")
-            self.learn = vision_learner(
-                self.dls, self.model, metrics=accuracy
-            ).to_fp16()
+            self._optimize_learner(self.device)
 
-        self.train_set = self.learn.dls.train_ds.items
-        self.valid_set = self.learn.dls.valid_ds.items
-        self.class_names = self.dls.vocab
-        self.num_classes = self.dls.c
-        logger.info("Done. Ready to train.")
+        except Exception as e:
+            action = "load" if learner_path else "create"
+            logger.error(f"Failed to {action} learner")
+            logger.exception(e)
+            raise RuntimeError(f"Failed to {action} learner: {str(e)}")
+
+        self._finalize_setup()
 
     def show_batch(
         self,
@@ -128,17 +207,24 @@ class ActiveLearner:
         logger.info(f"Training head for {head_tuning_epochs} epochs")
         logger.info(f"Training model end-to-end for {epochs} epochs")
         logger.info(f"Learning rate: {lr} with one-cycle learning rate scheduler")
-        self.learn.fine_tune(
-            epochs, lr, freeze_epochs=head_tuning_epochs, cbs=[ShowGraphCallback()]
-        )
+        self.learn.fine_tune(epochs, lr, freeze_epochs=head_tuning_epochs)
 
     def predict(self, filepaths: list[str], batch_size: int = 16):
         """
         Run inference on an unlabeled dataset. Returns a df with filepaths and predicted labels, and confidence scores.
         """
         logger.info(f"Running inference on {len(filepaths)} samples")
+
         test_dl = self.dls.test_dl(filepaths, bs=batch_size)
 
+        all_features = []
+
+        def hook_fn(module, input, output):
+            all_features.append(output.detach().cpu())
+
+        penultimate_layer = self.learn.model[1][4]
+        handle = penultimate_layer.register_forward_hook(hook_fn)
+
         def identity(x):
             return x
 
@@ -146,6 +232,9 @@ class ActiveLearner:
             dl=test_dl, with_decoded=True, act=identity
         )
 
+        handle.remove()
+        features = torch.cat(all_features)
+
         self.pred_df = pd.DataFrame(
             {
                 "filepath": filepaths,
@@ -153,9 +242,21 @@ class ActiveLearner:
                 "pred_conf": torch.max(F.softmax(logits, dim=1), dim=1)[0].numpy(),
                 "probs": F.softmax(logits, dim=1).numpy().tolist(),
                 "logits": logits.numpy().tolist(),
+                "embeddings": features.numpy().tolist(),
             }
         )
 
+        self.pred_df["pred_conf"] = self.pred_df["pred_conf"].round(4)
+        self.pred_df["probs"] = self.pred_df["probs"].apply(
+            lambda x: [round(p, 4) for p in x]
+        )
+        self.pred_df["logits"] = self.pred_df["logits"].apply(
+            lambda x: [round(l, 4) for l in x]
+        )
+        self.pred_df["embeddings"] = self.pred_df["embeddings"].apply(
+            lambda x: [round(e, 4) for e in x]
+        )
+
         return self.pred_df
 
     def evaluate(
@@ -180,6 +281,7 @@ class ActiveLearner:
         )
 
         accuracy = float((self.eval_df["label"] == self.eval_df["pred_label"]).mean())
+        self.eval_accuracy = accuracy
         logger.info(f"Accuracy: {accuracy:.2%}")
         return accuracy
 
@@ -197,7 +299,7 @@ class ActiveLearner:
         """
 
         # Remove samples that is already in the training set
-        df = df[~df["filepath"].isin(self.train_set["filepath"])].copy()
+        df = df[~df["filepath"].isin(self.dataset["filepath"])].copy()
 
         if strategy == "least-confidence":
             logger.info(
@@ -206,6 +308,7 @@ class ActiveLearner:
             df.loc[:, "score"] = 1 - (df["pred_conf"]) / (
                 self.num_classes - (self.num_classes - 1)
             )
+            df.loc[:, "strategy"] = "least-confidence"
 
         elif strategy == "margin-of-confidence":
             logger.info(
@@ -219,6 +322,7 @@ class ActiveLearner:
             df.loc[:, "score"] = df["probs"].apply(
                 lambda x: 1 - (np.sort(x)[-1] - np.sort(x)[-2])
             )
+            df.loc[:, "strategy"] = "margin-of-confidence"
 
         elif strategy == "ratio-of-confidence":
             logger.info(
@@ -232,6 +336,7 @@ class ActiveLearner:
             df.loc[:, "score"] = df["probs"].apply(
                 lambda x: np.sort(x)[-2] / np.sort(x)[-1]
             )
+            df.loc[:, "strategy"] = "ratio-of-confidence"
 
         elif strategy == "entropy":
             logger.info(f"Using entropy strategy to get top {num_samples} samples")
@@ -241,15 +346,26 @@ class ActiveLearner:
 
             # Normalize the uncertainty score to be between 0 and 1 by dividing by log2 of the number of classes
             df.loc[:, "score"] = df["score"] / np.log2(self.num_classes)
+            df.loc[:, "strategy"] = "entropy"
 
         else:
             logger.error(f"Unknown strategy: {strategy}")
             raise ValueError(f"Unknown strategy: {strategy}")
 
-        df = df[["filepath", "pred_label", "pred_conf", "score", "probs", "logits"]]
+        df = df[
+            [
+                "filepath",
+                "strategy",
+                "score",
+                "pred_label",
+                "pred_conf",
+                "probs",
+                "logits",
+                "embeddings",
+            ]
+        ]
 
-        df["score"] = df["score"].map("{:.4f}".format)
-        df["pred_conf"] = df["pred_conf"].map("{:.4f}".format)
+        df["score"] = df["score"].round(4)
 
         return df.sort_values(by="score", ascending=False).head(num_samples)
 
@@ -266,7 +382,7 @@ class ActiveLearner:
 
         """
         # Remove samples that is already in the training set
-        df = df[~df["filepath"].isin(self.train_set["filepath"])].copy()
+        df = df[~df["filepath"].isin(self.dataset["filepath"])].copy()
 
         if strategy == "model-based-outlier":
             logger.info(
@@ -286,7 +402,8 @@ class ActiveLearner:
             ]
 
             # Get the logits for the unlabeled set
-            unlabeled_set_preds = self.predict(df["filepath"].tolist())
+            # unlabeled_set_preds = self.predict(df["filepath"].tolist())
+            unlabeled_set_preds = df
 
             # For each element in the unlabeled set logits, compare it to the validation set ranked logits and get the position in the ranked logits
             unlabeled_set_logits = []
@@ -312,26 +429,159 @@ class ActiveLearner:
 
             # Add outlier scores to dataframe
             df.loc[:, "score"] = unlabeled_set_logits
+            df.loc[:, "strategy"] = "model-based-outlier"
+            df = df[
+                [
+                    "filepath",
+                    "strategy",
+                    "score",
+                    "pred_label",
+                    "pred_conf",
+                    "probs",
+                    "logits",
+                    "embeddings",
+                ]
+            ]
 
-            df = df[["filepath", "pred_label", "pred_conf", "score", "probs", "logits"]]
-
-            df["score"] = df["score"].map("{:.4f}".format)
-            df["pred_conf"] = df["pred_conf"].map("{:.4f}".format)
+            df["score"] = df["score"].round(4)
 
             # Sort by score ascending higher rank = more outlier-like compared to the validation set
             return df.sort_values(by="score", ascending=False).head(num_samples)
 
+        else:
+            logger.error(f"Unknown strategy: {strategy}")
+            raise ValueError(f"Unknown strategy: {strategy}")
+
     def sample_random(self, df: pd.DataFrame, num_samples: int, seed: int = None):
         """
         Sample `num_samples` random samples. Returns a df with filepaths and predicted labels, and confidence scores.
         """
 
         logger.info(f"Sampling {num_samples} random samples")
+        df = df[~df["filepath"].isin(self.dataset["filepath"])].copy()
+        df["strategy"] = "random"
+        df["score"] = 0.0
+
         if seed is not None:
             logger.info(f"Using seed: {seed}")
         return df.sample(n=num_samples, random_state=seed)
 
-    def label(self, df: pd.DataFrame, output_filename: str = "labeled"):
+    def sample_combination(self, df: pd.DataFrame, num_samples: int, combination: dict):
+        """
+        Sample samples based on a combination of strategies.
+
+        Args:
+            df: DataFrame with filepaths and predicted labels, and confidence scores
+            num_samples: Total number of samples to select
+            combination: Dictionary mapping strategy names to proportions, e.g.:
+                {
+                    "least-confidence": 0.4,
+                    "model-based-outlier": 0.6
+                }
+
+                Supported strategies:
+                Uncertainty-based:
+                    - least-confidence
+                    - margin-of-confidence
+                    - ratio-of-confidence
+                    - entropy
+                Diversity-based:
+                    - model-based-outlier
+                    - cluster-based
+                    - representative
+                Other:
+                    - random
+
+        Returns:
+            DataFrame containing the combined samples
+        """
+        logger.info(f"Using combination sampling to get {num_samples} samples")
+
+        # Validate total proportions sum to 1
+        if not np.isclose(sum(combination.values()), 1.0):
+            raise ValueError(
+                f"Proportions must sum to 1, got {sum(combination.values())}"
+            )
+
+        # Calculate samples per strategy and handle rounding
+        samples_per_strategy = {
+            strategy: int(proportion * num_samples)
+            for strategy, proportion in combination.items()
+        }
+
+        # Add any remaining samples to the first strategy
+        remaining = num_samples - sum(samples_per_strategy.values())
+        if remaining > 0:
+            first_strategy = list(combination.keys())[0]
+            samples_per_strategy[first_strategy] += remaining
+
+        # Get samples for each strategy
+        sampled_dfs = []
+        for strategy, n_samples in samples_per_strategy.items():
+            if n_samples == 0:
+                continue
+
+            if strategy in [
+                "least-confidence",
+                "margin-of-confidence",
+                "ratio-of-confidence",
+                "entropy",
+            ]:
+                strategy_df = self.sample_uncertain(
+                    df=df, num_samples=n_samples, strategy=strategy
+                )
+            elif strategy in ["model-based-outlier", "cluster-based", "representative"]:
+                strategy_df = self.sample_diverse(
+                    df=df, num_samples=n_samples, strategy=strategy
+                )
+            elif strategy == "random":
+                strategy_df = self.sample_random(df=df, num_samples=n_samples)
+            else:
+                raise ValueError(f"Unknown strategy: {strategy}")
+
+            sampled_dfs.append(strategy_df)
+            # Remove selected samples from the pool to avoid duplicates
+            df = df[~df["filepath"].isin(strategy_df["filepath"])]
+
+        return pd.concat(sampled_dfs, ignore_index=True)
+
+    def summary(self, filename: str = None, show: bool = True):
+        results_df = pd.DataFrame(
+            {
+                "name": [self.name],
+                "accuracy": [self.eval_accuracy],
+                "train_set_size": [len(self.train_set)],
+                "valid_set_size": [len(self.valid_set)],
+                "dataset_size": [len(self.train_set) + len(self.valid_set)],
+                "num_classes": [self.num_classes],
+                "model": [self.model],
+                "pretrained": [self.pretrained],
+                "loss_fn": [str(self.loss_fn)],
+                "device": [self.device],
+                "seed": [self.seed],
+                "batch_size": [self.batch_size],
+                "image_size": [self.image_size],
+            }
+        )
+
+        if filename is None:
+            # Generate filename with timestamp, accuracy and dataset size
+            from datetime import datetime
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            accuracy_str = f"{self.eval_accuracy:.2%}" if self.eval_accuracy is not None else "no_eval"
+            dataset_size = len(self.train_set) + len(self.valid_set)
+            filename = f"{self.name}_{timestamp}_acc_{accuracy_str}_n_{dataset_size}.parquet"
+        elif not filename.endswith(".parquet"):
+            filename = f"{filename}.parquet"
+
+        results_df.to_parquet(filename)
+        logger.info(f"Saved results to {filename}")
+        if show:
+            return results_df
+        else:
+            return None
+
+    def label(self, df: pd.DataFrame, output_filename: str):
         """
         Launch a labeling interface for the user to label the samples.
         Input is a df with filepaths listing the files to be labeled. Output is a df with filepaths and labels.
@@ -378,6 +628,10 @@ class ActiveLearner:
 
                         # Add bar plot with top 5 predictions
                         with gr.Column():
+                            filename = gr.Textbox(
+                                label="Filename", value=filepaths[0], interactive=False
+                            )
+
                             pred_plot = gr.BarPlot(
                                 x="probability",
                                 y="class",
@@ -393,9 +647,6 @@ class ActiveLearner:
                                 ).nlargest(5, "probability"),
                             )
 
-                            filename = gr.Textbox(
-                                label="Filename", value=filepaths[0], interactive=False
-                            )
                             with gr.Row():
                                 pred_label = gr.Textbox(
                                     label="Predicted Label",
@@ -405,21 +656,33 @@ class ActiveLearner:
                                     interactive=False,
                                 )
 
+                                def format_for_display(value):
+                                    return f"{value:.4f}" if pd.notnull(value) else ""
+
                                 pred_conf = gr.Textbox(
                                     label="Confidence",
-                                    value=df["pred_conf"].iloc[0]
+                                    value=format_for_display(df["pred_conf"].iloc[0])
                                     if "pred_conf" in df.columns
                                     else "",
                                     interactive=False,
                                 )
 
-                            sample_score = gr.Textbox(
-                                label="Sample Score [0-1] - Indicates how informative the sample is. Higher means more informative.",
-                                value=df["score"].iloc[0]
-                                if "score" in df.columns
-                                else "",
-                                interactive=False,
-                            )
+                            with gr.Row():
+                                strategy = gr.Textbox(
+                                    label="Sampling Strategy",
+                                    value=df["strategy"].iloc[0]
+                                    if "strategy" in df.columns
+                                    else "",
+                                    interactive=False,
+                                )
+
+                                sample_score = gr.Textbox(
+                                    label="Score",
+                                    value=format_for_display(df["score"].iloc[0])
+                                    if "score" in df.columns
+                                    else "",
+                                    interactive=False,
+                                )
 
                     category = gr.Radio(
                         choices=self.class_names,
@@ -461,6 +724,7 @@ class ActiveLearner:
                             progress,
                             pred_plot,
                             sample_score,
+                            strategy,
                         ],
                     )
 
@@ -574,6 +838,9 @@ class ActiveLearner:
                         next_idx,
                         plot_data,
                         df["score"].iloc[next_idx] if "score" in df.columns else "",
+                        df["strategy"].iloc[next_idx]
+                        if "strategy" in df.columns
+                        else "",
                     )
                 plot_data = (
                     None
@@ -601,6 +868,9 @@ class ActiveLearner:
                     current_idx,
                     plot_data,
                     df["score"].iloc[current_idx] if "score" in df.columns else "",
+                    df["strategy"].iloc[current_idx]
+                    if "strategy" in df.columns
+                    else "",
                 )
 
             def save_and_next(current_idx, selected_category):
@@ -634,6 +904,9 @@ class ActiveLearner:
                         current_idx,
                         plot_data,
                         df["score"].iloc[current_idx] if "score" in df.columns else "",
+                        df["strategy"].iloc[current_idx]
+                        if "strategy" in df.columns
+                        else "",
                     )
 
                 # Save the current annotation
@@ -669,6 +942,9 @@ class ActiveLearner:
                         current_idx,
                         plot_data,
                         df["score"].iloc[current_idx] if "score" in df.columns else "",
+                        df["strategy"].iloc[current_idx]
+                        if "strategy" in df.columns
+                        else "",
                     )
 
                 plot_data = (
@@ -695,15 +971,27 @@ class ActiveLearner:
                     next_idx,
                     plot_data,
                     df["score"].iloc[next_idx] if "score" in df.columns else "",
+                    df["strategy"].iloc[next_idx] if "strategy" in df.columns else "",
                 )
 
             def convert_csv_to_parquet():
                 try:
-                    df = pd.read_csv(f"{output_filename}.csv", header=None)
+                    csv_path = f"{output_filename}.csv"
+                    parquet_path = (
+                        f"{output_filename}.parquet"
+                        if not output_filename.endswith(".parquet")
+                        else output_filename
+                    )
+
+                    df = pd.read_csv(csv_path, header=None)
                     df.columns = ["filepath", "label"]
                     df = df.drop_duplicates(subset=["filepath"], keep="last")
-                    df.to_parquet(f"{output_filename}.parquet")
-                    gr.Info(f"Annotation saved to {output_filename}.parquet")
+                    df.reset_index(drop=True, inplace=True)
+                    df.to_parquet(parquet_path)
+                    gr.Info(f"Annotation saved to {parquet_path}")
+
+                    # remove csv file
+                    os.remove(csv_path)
                 except Exception as e:
                     logger.error(e)
                     return
@@ -721,6 +1009,7 @@ class ActiveLearner:
                     progress,
                     pred_plot,
                     sample_score,
+                    strategy,
                 ],
             )
 
@@ -737,6 +1026,7 @@ class ActiveLearner:
                     progress,
                     pred_plot,
                     sample_score,
+                    strategy,
                 ],
             )
 
@@ -753,6 +1043,7 @@ class ActiveLearner:
                     progress,
                     pred_plot,
                     sample_score,
+                    strategy,
                 ],
             )
 
@@ -760,19 +1051,18 @@ class ActiveLearner:
 
         demo.launch(height=1000)
 
-    def add_to_train_set(self, df: pd.DataFrame, output_filename: str):
+    def add_to_dataset(self, labeled_df: pd.DataFrame, output_filename: str):
         """
-        Add samples to the training set.
+        Add samples to the dataset used for training - include train and validation sets.
         """
-        new_train_set = df.copy()
-
-        logger.info(f"Adding {len(new_train_set)} samples to training set")
-        self.train_set = pd.concat([self.train_set, new_train_set])
+        labeled_df = labeled_df.copy()
 
-        self.train_set = self.train_set.drop_duplicates(
-            subset=["filepath"], keep="last"
-        )
-        self.train_set.reset_index(drop=True, inplace=True)
+        logger.info(f"Adding {len(labeled_df)} samples to dataset")
+        self.dataset = pd.concat([self.dataset, labeled_df])
+        self.dataset = self.dataset.drop_duplicates(subset=["filepath"], keep="last")
+        self.dataset.reset_index(drop=True, inplace=True)
 
-        self.train_set.to_parquet(f"{output_filename}.parquet")
-        logger.info(f"Saved training set to {output_filename}.parquet")
+        if not output_filename.endswith(".parquet"):
+            output_filename = f"{output_filename}.parquet"
+        self.dataset.to_parquet(output_filename)
+        logger.info(f"Saved dataset to {output_filename}")

{active_vision-0.3.0.dist-info → active_vision-0.4.1.dist-info}/METADATA

@@ -1,10 +1,11 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: active-vision
-Version: 0.3.0
+Version: 0.4.1
 Summary: Active learning for computer vision.
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
+Project-URL: Homepage, https://github.com/dnth/active-vision
+Project-URL: Bug Tracker, https://github.com/dnth/active-vision/issues
 License-File: LICENSE
+Requires-Python: >=3.10
 Requires-Dist: accelerate>=1.2.1
 Requires-Dist: datasets>=3.2.0
 Requires-Dist: fastai>=2.7.18
@@ -16,14 +17,57 @@ Requires-Dist: seaborn>=0.13.2
 Requires-Dist: timm>=1.0.13
 Requires-Dist: transformers>=4.48.0
 Requires-Dist: xinfer>=0.3.2
+Provides-Extra: dev
+Requires-Dist: black>=22.0; extra == 'dev'
+Requires-Dist: flake8>=4.0; extra == 'dev'
+Requires-Dist: isort>=5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: ansi2html; extra == 'docs'
+Requires-Dist: ipykernel; extra == 'docs'
+Requires-Dist: jupyter; extra == 'docs'
+Requires-Dist: livereload; extra == 'docs'
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-plugin; extra == 'docs'
+Requires-Dist: mkdocs-jupyter>=0.24.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.1.3; extra == 'docs'
+Requires-Dist: mkdocs-mermaid2-plugin; extra == 'docs'
+Requires-Dist: mkdocs-pdf-export-plugin; extra == 'docs'
+Requires-Dist: mkdocstrings; extra == 'docs'
+Requires-Dist: mkdocstrings-crystal; extra == 'docs'
+Requires-Dist: mkdocstrings-python-legacy; extra == 'docs'
+Requires-Dist: nbconvert; extra == 'docs'
+Requires-Dist: nbformat; extra == 'docs'
+Requires-Dist: pygments; extra == 'docs'
+Requires-Dist: pymdown-extensions; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: watchdog; extra == 'docs'
+Description-Content-Type: text/markdown
 
 [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/active-vision/)
 [![PyPI](https://img.shields.io/pypi/v/active-vision?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/active-vision/)
 [![Downloads](https://img.shields.io/pepy/dt/active-vision?style=for-the-badge&logo=pypi&logoColor=white&label=Downloads&color=purple)](https://pypi.org/project/active-vision/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg?style=for-the-badge&logo=apache&logoColor=white)](https://github.com/dnth/active-vision/blob/main/LICENSE)
 
+[colab_badge]: https://img.shields.io/badge/Open%20In-Colab-blue?style=for-the-badge&logo=google-colab
+[kaggle_badge]: https://img.shields.io/badge/Open%20In-Kaggle-blue?style=for-the-badge&logo=kaggle
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/dnth/active-vision/main/assets/logo.png" alt="active-vision">
+    <br />
+    <br />
+    <a href="https://dnth.github.io/active-vision" target="_blank" rel="noopener noreferrer"><strong>Explore the docs »</strong></a>
+    <br />
+    <a href="#️-quickstart" target="_blank" rel="noopener noreferrer">Quickstart</a>
+    ·
+    <a href="https://github.com/dnth/active-vision/issues/new?assignees=&labels=Feature+Request&projects=&template=feature_request.md" target="_blank" rel="noopener noreferrer">Feature Request</a>
+    ·
+    <a href="https://github.com/dnth/active-vision/issues/new?assignees=&labels=bug&projects=&template=bug_report.md" target="_blank" rel="noopener noreferrer">Report Bug</a>
+    ·
+    <a href="https://github.com/dnth/active-vision/discussions" target="_blank" rel="noopener noreferrer">Discussions</a>
+    ·
+    <a href="https://dicksonneoh.com/" target="_blank" rel="noopener noreferrer">About</a>
 </p>
 
 The goal of this project is to create a framework for the active learning loop for computer vision. The diagram below shows a general workflow of how the active learning loop works.
@@ -89,41 +133,52 @@ pip install -e .
 > uv pip install active-vision
 > ```
 
-## 🛠️ Usage
-See the [notebook](./nbs/04_relabel_loop.ipynb) for a complete example.
+## 🚀 Quickstart
 
-Be sure to prepared 3 subsets of the dataset:
-- [Initial samples](./nbs/initial_samples.parquet): A dataframe of a labeled images to train an initial model. If you don't have any labeled data, you can label some images yourself.
-- [Unlabeled samples](./nbs/unlabeled_samples.parquet): A dataframe of *unlabeled* images. We will continuously sample from this set using active learning strategies.
-- [Evaluation samples](./nbs/evaluation_samples.parquet): A dataframe of *labeled* images. We will use this set to evaluate the performance of the model. This is the test set, DO NOT use it for active learning. Split this out in the beginning.
+[![Open In Colab][colab_badge]](https://colab.research.google.com/github/dnth/active-vision/blob/main/nbs/imagenette/quickstart.ipynb)
+[![Open In Kaggle][kaggle_badge]](https://kaggle.com/kernels/welcome?src=https://github.com/dnth/active-vision/blob/main/nbs/imagenette/quickstart.ipynb)
 
-As a toy example I created the above 3 datasets from the imagenette dataset.
+The following are code snippets for the active learning loop in active-vision. I recommend running the quickstart notebook in Colab or Kaggle to see the full workflow.
 
 ```python
 from active_vision import ActiveLearner
-import pandas as pd
 
-# Create an active learner instance with a model
-al = ActiveLearner("resnet18")
+# Create an active learner instance
+al = ActiveLearner(name="cycle-1")
+
+# Load model
+al.load_model(model="resnet18", pretrained=True)
 
 # Load dataset 
-train_df = pd.read_parquet("training_samples.parquet")
-al.load_dataset(df, filepath_col="filepath", label_col="label")
+al.load_dataset(train_df, filepath_col="filepath", label_col="label", batch_size=8)
 
 # Train model
-al.train(epochs=3, lr=1e-3)
+al.train(epochs=10, lr=5e-3)
 
 # Evaluate the model on a *labeled* evaluation set
 accuracy = al.evaluate(eval_df, filepath_col="filepath", label_col="label")
 
+# Get summary of the active learning cycle
+al.summary()
+
 # Get predictions from an *unlabeled* set
 pred_df = al.predict(filepaths)
 
-# Sample low confidence predictions from unlabeled set
-uncertain_df = al.sample_uncertain(pred_df, num_samples=10)
-
-# Launch a Gradio UI to label the low confidence samples, save the labeled samples to a file
-al.label(uncertain_df, output_filename="uncertain")
+# Sample images using a combination of active learning strategies
+samples = al.sample_combination(
+    pred_df,
+    num_samples=50,
+    combination={
+        "least-confidence": 0.4,
+        "ratio-of-confidence": 0.2,
+        "entropy": 0.2,
+        "model-based-outlier": 0.1,
+        "random": 0.1,
+    },
+)
+
+# Launch a Gradio UI to label the samples, save the labeled samples to a file
+al.label(samples, output_filename="samples.parquet")
 ```
 
 ![Gradio UI](https://raw.githubusercontent.com/dnth/active-vision/main/assets/labeling_ui.png)
@@ -136,18 +191,11 @@ Once complete, the labeled samples will be save into a new df.
 We can now add the newly labeled data to the training set.
 
 ```python
-# Add newly labeled data to training set and save as a new file active_labeled
-al.add_to_train_set(labeled_df, output_filename="active_labeled")
+al.add_to_dataset(labeled_df, output_filename="active_labeled.parquet")
 ```
 
 Repeat the process until the model is good enough. Use the dataset to train a larger model and deploy.
 
-> [!TIP]
-> For the toy dataset, I got to about 93% accuracy on the evaluation set with 200+ labeled images. The best performing model on the [leaderboard](https://github.com/fastai/imagenette) got 95.11% accuracy training on all 9469 labeled images.
-> 
-> This took me about 6 iterations of relabeling. Each iteration took about 5 minutes to complete including labeling and model training (resnet18). See the [notebook](./nbs/04_relabel_loop.ipynb) for more details.
->
-> But using the dataset of 200+ images, I trained a more capable model (convnext_small_in22k) and got 99.3% accuracy on the evaluation set. See the [notebook](./nbs/05_retrain_larger.ipynb) for more details.
 
 
 ## 📊 Benchmarks

active_vision-0.4.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+active_vision/__init__.py,sha256=vauWDAlrr6fiIylIKSzErXOEopRtTsBk8G4hC9418M0,43
+active_vision/core.py,sha256=ZDRylM3KsoLxy9qA9bld4WxzcKcyCwH8IJ1cFxtz5mE,41607
+active_vision-0.4.1.dist-info/METADATA,sha256=LpgLc_E7jJVXxUHrIPv-1RZq_CEE3enyb0O2PDZMrJM,17262
+active_vision-0.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+active_vision-0.4.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+active_vision-0.4.1.dist-info/RECORD,,

{active_vision-0.3.0.dist-info → active_vision-0.4.1.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

active_vision-0.3.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-active_vision/__init__.py,sha256=hbFzCBVh_5qm0XuZh_I07cRmmDZ_cDx5n-6mf-tFB6s,43
-active_vision/core.py,sha256=8kYsA0cHNty1oOXg0yvvlT2Tau7m_AS9DJ7Sc0RB30k,31096
-active_vision-0.3.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-active_vision-0.3.0.dist-info/METADATA,sha256=B8t28CcxeXFLAonjFV6zoVwAAOOR1mSn_YtJVEzKqcg,15710
-active_vision-0.3.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-active_vision-0.3.0.dist-info/top_level.txt,sha256=7qUQvccN2UU63z5S9vrgJmqK-8sFGrtpf1e9Z86nihE,14
-active_vision-0.3.0.dist-info/RECORD,,

active_vision-0.3.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-active_vision