spacr.deep_spacr
================

.. py:module:: spacr.deep_spacr






Module Contents
---------------

.. py:function:: apply_model(src, model_path, image_size=224, batch_size=64, normalize=True, n_jobs=10)

   Apply a trained PyTorch model to images in a directory.

   The function loads a saved model, builds a dataset from the input images,
   runs batched inference, and saves prediction scores to a CSV file.

   :param src: Path to the input image directory or collection of image paths.
   :type src: str or sequence
   :param model_path: Path to the saved PyTorch model.
   :type model_path: str
   :param image_size: Final square crop size used before inference.
   :type image_size: int
   :param batch_size: Number of images processed per batch.
   :type batch_size: int
   :param normalize: Whether to normalize the image channels using mean 0.5
       and standard deviation 0.5.
   :type normalize: bool
   :param n_jobs: Number of worker processes used by the DataLoader.
   :type n_jobs: int
   :return: DataFrame with image paths and predicted positive-class
       probabilities.
   :rtype: pandas.DataFrame

   The returned DataFrame contains the columns ``path`` and ``pred``.
   Results are also written to a CSV file derived from ``model_path`` and the
   current date. The model output is interpreted as a binary logit and
   converted to probabilities with ``torch.sigmoid``.


.. py:function:: apply_model_to_tar(settings={})

   Apply a trained PyTorch model to images stored in a tar archive.

   The function loads a saved model, reads images from a tar-based dataset,
   performs batched inference, post-processes prediction scores, and saves the
   results to a CSV file.

   :param settings: Dictionary of inference settings. Expected keys include
       ``tar_path``, ``model_path``, ``image_size``, ``batch_size``,
       ``normalize``, ``n_jobs``, ``verbose``, and ``score_threshold``.
   :type settings: dict
   :return: DataFrame with processed prediction results.
   :rtype: pandas.DataFrame

   The returned DataFrame contains at least the columns ``path`` and ``pred``.
   Additional columns may be added by ``process_vision_results``. If the model
   output has shape ``(N, 2)``, the probability of class 1 is computed with
   ``torch.softmax``. Otherwise, outputs are treated as binary logits and
   converted with ``torch.sigmoid``.


.. py:function:: evaluate_model_performance(model, loader, epoch, loss_type='auto', loss_fn=None, num_classes=None)

   Evaluates performance for binary or multiclass models.

   :returns: metrics + loss + epoch
             [prediction_probs, all_labels]
               - binary: probs shape (N,)
               - multiclass: probs shape (N, C)
   :rtype: data_dict (dict)


.. py:function:: test_model_core(model, loader, loader_name, epoch, loss_type)

   Core test loop returning both summary metrics and a row-per-image dataframe,
   compatible with binary & multiclass.


.. py:function:: test_model_performance(loaders, model, loader_name_list, epoch, loss_type)

   Wrapper kept for API compatibility with your caller.
   Returns (summary_metrics_dataframe, per_file_results_dataframe)


.. py:function:: train_test_model(settings)

.. py:function:: train_test_model_v1(settings)

.. py:function:: train_model(src, dst, model_type, train_loaders, epochs=100, learning_rate=0.0001, weight_decay=0.05, amsgrad=False, optimizer_type='adamw', use_checkpoint=False, dropout_rate=0, n_jobs=20, val_loaders=None, test_loaders=None, init_weights='imagenet', intermedeate_save=None, chan_dict=None, schedule=None, loss_type='auto', gradient_accumulation=False, gradient_accumulation_steps=4, channels=['r', 'g', 'b'], verbose=False, num_classes=2, early_stopping_patience=0)

   Trains a model (supports 2-class and >2-class via CrossEntropy).

   New parameters:
       early_stopping_patience: number of epochs with no val improvement before stopping.
                                Set to 0 to disable (original behavior).


.. py:function:: train_model_v1(src, dst, model_type, train_loaders, epochs=100, learning_rate=0.0001, weight_decay=0.05, amsgrad=False, optimizer_type='adamw', use_checkpoint=False, dropout_rate=0, n_jobs=20, val_loaders=None, test_loaders=None, init_weights='imagenet', intermedeate_save=None, chan_dict=None, schedule=None, loss_type='auto', gradient_accumulation=False, gradient_accumulation_steps=4, channels=['r', 'g', 'b'], verbose=False, num_classes=2)

   Trains a model (supports 2-class and >2-class via CrossEntropy; BCE only for true single-logit binary).


.. py:function:: generate_activation_map(settings)

.. py:function:: visualize_classes(model, dtype, class_names, **kwargs)

.. py:function:: visualize_integrated_gradients(src, model_path, target_label_idx=0, image_size=224, channels=[1, 2, 3], normalize=True, save_integrated_grads=False, save_dir='integrated_grads')

.. py:class:: SmoothGrad(model, n_samples=50, stdev_spread=0.15)

   .. py:attribute:: model


   .. py:attribute:: n_samples
      :value: 50



   .. py:attribute:: stdev_spread
      :value: 0.15



   .. py:method:: compute_smooth_grad(input_tensor, target_class)


.. py:function:: visualize_smooth_grad(src, model_path, target_label_idx, image_size=224, channels=[1, 2, 3], normalize=True, save_smooth_grad=False, save_dir='smooth_grad')

.. py:function:: save_top_class_examples(df, tar_path, dst, n=20, classes=None)

   Extract the N most confident images per class from the tar and save
   them into class-labelled subfolders under dst.

   For binary classification (classes=[0, 1]):
     - class_0/  ← the 20 images with the LOWEST  pred  (closest to 0)
     - class_1/  ← the 20 images with the HIGHEST pred  (closest to 1)

   :param df: Must contain columns 'path' (tar member name) and 'pred' (probability).
   :type df: pd.DataFrame
   :param tar_path: Path to the tar archive that holds the images.
   :type tar_path: str
   :param dst: Root folder where class subfolders will be created.
   :type dst: str
   :param n: Number of top images to keep per class.
   :type n: int
   :param classes: Explicit class labels. If None, defaults to binary [0, 1].
   :type classes: list or None


.. py:function:: merge_predictions_into_db(df, db_path, table='png_list', pred_col='pred', class_col='cv_predictions')

   Merge prediction scores back into the SQLite database.

   Matching on basename of png_path (DB) vs path (tar member name),
   since the tar stores relative member names while the DB stores
   full disk paths.


.. py:function:: deep_spacr_v1(settings={})

.. py:function:: deep_spacr(settings={})

.. py:function:: model_knowledge_transfer(teacher_paths, student_save_path, data_loader, device='cpu', student_model_name='maxvit_t', pretrained=True, dropout_rate=None, use_checkpoint=False, alpha=0.5, temperature=2.0, lr=0.0001, epochs=10)

.. py:function:: model_fusion(model_paths, save_path, device='cpu', model_name='maxvit_t', pretrained=True, dropout_rate=None, use_checkpoint=False, aggregator='mean')

.. py:function:: annotate_filter_vision(settings)

