spacr.deep_spacr

Module Contents

spacr.deep_spacr.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.

Parameters:

• src (str or sequence) – Path to the input image directory or collection of image paths.

• model_path (str) – Path to the saved PyTorch model.

• image_size (int) – Final square crop size used before inference.

• batch_size (int) – Number of images processed per batch.

• normalize (bool) – Whether to normalize the image channels using mean 0.5 and standard deviation 0.5.

• n_jobs (int) – Number of worker processes used by the DataLoader.

Returns:

DataFrame with image paths and predicted positive-class probabilities.

Return type:

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.

spacr.deep_spacr.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.

Parameters:

settings (dict) – Dictionary of inference settings. Expected keys include tar_path, model_path, image_size, batch_size, normalize, n_jobs, verbose, and score_threshold.

Returns:

DataFrame with processed prediction results.

Return type:

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.

spacr.deep_spacr.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)

Return type:

data_dict (dict)

spacr.deep_spacr.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.

spacr.deep_spacr.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)

spacr.deep_spacr.train_test_model(settings)

spacr.deep_spacr.train_test_model_v1(settings)

spacr.deep_spacr.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).

spacr.deep_spacr.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).

spacr.deep_spacr.generate_activation_map(settings)

spacr.deep_spacr.visualize_classes(model, dtype, class_names, **kwargs)

spacr.deep_spacr.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')

class spacr.deep_spacr.SmoothGrad(model, n_samples=50, stdev_spread=0.15)

model

n_samples = 50

stdev_spread = 0.15

compute_smooth_grad(input_tensor, target_class)

spacr.deep_spacr.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')

spacr.deep_spacr.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)

Parameters:

• df (pd.DataFrame) – Must contain columns ‘path’ (tar member name) and ‘pred’ (probability).

• tar_path (str) – Path to the tar archive that holds the images.

• dst (str) – Root folder where class subfolders will be created.

• n (int) – Number of top images to keep per class.

• classes (list or None) – Explicit class labels. If None, defaults to binary [0, 1].

spacr.deep_spacr.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.

spacr.deep_spacr.deep_spacr_v1(settings={})

spacr.deep_spacr.deep_spacr(settings={})

spacr.deep_spacr.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)

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

spacr.deep_spacr.annotate_filter_vision(settings)