stouputils 1.14.0__py3-none-any.whl

stouputils/data_science/scripts/routine.py

@@ -0,0 +1,168 @@
+
+# Imports
+import argparse
+import itertools
+from typing import Any, Literal
+
+from ...decorators import handle_error, measure_time
+from ...print import info, error, progress
+from ...io import clean_path
+from ..config.get import DataScienceConfig
+from ..dataset import LOWER_GS, Dataset, DatasetLoader, GroupingStrategy, XyTuple
+from ..models.all import ALL_MODELS, CLASS_MAP, ModelInterface
+
+# Constants
+MODEL_HELP: str             = "Model(s) name or alias to use"
+INPUT_HELP: str             = "Path to the dataset, e.g. 'data/aug_hip_implant'"
+BASED_OF_HELP: str          = "Path to the base dataset for filtering train/test, e.g. 'data/hip_implant'"
+TRANSFER_LEARNING_HELP: str = "Transfer learning source (imagenet, None, 'data/dataset_folder')"
+GROUPING_HELP: str          = "Grouping strategy for the dataset"
+K_FOLD_HELP: str            = "Number of folds for k-fold cross validation (0 = no k-fold, negative = LeavePOut)"
+GRID_SEARCH_HELP: str       = "If grid search should be performed on hyperparameters"
+VERBOSE_HELP: str           = "Verbosity level sent to functions"
+PARSER_DESCRIPTION: str     = "Command-line interface for training and evaluating machine learning models."
+
+
+# Main function
+@measure_time(printer=info, message="Total execution time of the script")
+@handle_error(exceptions=(KeyboardInterrupt, Exception), error_log=DataScienceConfig.ERROR_LOG)
+def routine(
+	default_input: str = f"{DataScienceConfig.DATA_FOLDER}/aug_hip_implant_preprocessed",
+	default_based_of: str = "auto",
+	default_transfer_learning: str = "imagenet",
+	default_grouping_strategy: str = "none",
+	default_kfold: int = 0,
+	default_verbose: int = 100,
+
+	loading_type: Literal["image"] = "image",
+	grid_search_param_grid: dict[str, list[Any]] | None = None,
+	add_to_train_only: list[str] | None = None,
+) -> None:
+	""" Main function of the script for training and evaluating machine learning models.
+
+	This function handles the entire workflow for model training and evaluation, including:
+	- Parsing command-line arguments (default values are set in the function signature)
+	- Loading and preparing datasets with configurable grouping strategies
+	- Supporting transfer learning from various sources
+	- Enabling K-fold cross-validation, LeavePOut or LeaveOneOut
+	- Providing grid search capabilities for hyperparameter optimization
+	- Incorporating additional training data from specified paths
+
+	Args:
+		default_input             (str):              Default path to the dataset to use.
+		default_based_of          (str):              Default path to the base dataset for filtering train/test data.
+		default_transfer_learning (str):              Default transfer learning source.
+		default_grouping_strategy (str):              Default grouping strategy for the dataset.
+		default_kfold             (int):              Default number of folds for k-fold cross validation.
+		default_verbose           (int):              Default verbosity level.
+		loading_type              (Literal["image"]):             Type of data to load, currently only supports "image".
+		grid_search_param_grid    (dict[str, list[Any]] | None):  Parameters grid for hyperparameter optimization.
+		add_to_train_only         (list[str] | None):             List of paths to additional training datasets.
+
+	Returns:
+		None: This function does not return anything.
+	"""
+	if grid_search_param_grid is None:
+		grid_search_param_grid = {"batch_size": [8, 16, 32, 64]}
+	if add_to_train_only is None:
+		add_to_train_only = []
+
+	info("Starting the script...")
+
+	# Parse the arguments
+	parser = argparse.ArgumentParser(description=PARSER_DESCRIPTION)
+	parser.add_argument("--model",             type=str, choices=ALL_MODELS, required=True, help=MODEL_HELP)
+	parser.add_argument("--input",             type=str, default=default_input, help=INPUT_HELP)
+	parser.add_argument("--based_of",          type=str, default=default_based_of, help=BASED_OF_HELP)
+	parser.add_argument("--transfer_learning", type=str, default=default_transfer_learning, help=TRANSFER_LEARNING_HELP)
+	parser.add_argument("--grouping_strategy", type=str, default=default_grouping_strategy, choices=LOWER_GS, help=GROUPING_HELP)
+	parser.add_argument("--kfold", type=int, default=default_kfold, help=K_FOLD_HELP)
+	parser.add_argument("--grid_search", action="store_true", help=GRID_SEARCH_HELP)
+	parser.add_argument("--verbose", type=int, default=default_verbose, help=VERBOSE_HELP)
+	args: argparse.Namespace = parser.parse_args()
+	model: str = args.model.lower()
+	kfold: int = args.kfold
+	input_path: str = clean_path(args.input, trailing_slash=False)
+	based_of: str = clean_path(args.based_of, trailing_slash=False)
+	transfer_learning: str = clean_path(args.transfer_learning, trailing_slash=False)
+	verbose: int = args.verbose
+	grouping_strategy: str = args.grouping_strategy
+	grid_search: bool = args.grid_search
+
+	# If based_of is "auto", set it to the input path without the "aug"
+	if based_of == "auto":
+		prefix: str = "/" + DataScienceConfig.AUGMENTED_DIRECTORY_PREFIX
+		if prefix in input_path:
+			based_of = input_path.replace(prefix, "/")
+		else:
+			based_of = ""
+
+	# Load the dataset
+	kwargs: dict[str, Any] = {}
+	if grouping_strategy == "concatenate":
+		kwargs["color_mode"] = "grayscale"
+	dataset: Dataset = DatasetLoader.from_path(
+		path=input_path,
+		loading_type=loading_type,
+		seed=DataScienceConfig.SEED,
+		test_size=DataScienceConfig.TEST_SIZE,
+		grouping_strategy=next(x for x in GroupingStrategy if x.name.lower() == grouping_strategy),
+		based_of=based_of,
+		**kwargs
+	)
+	info(dataset)
+
+	# Define parameter combinations
+	param_combinations: list[dict[str, Any]] = [{}]  # Default empty params
+	if grid_search:
+
+		# Generate all parameter combinations
+		param_combinations.clear()
+		for values in itertools.product(*grid_search_param_grid.values()):
+			param_combinations.append(dict(zip(grid_search_param_grid.keys(), values, strict=False)))
+
+	# Load additional training data from provided paths
+	additional_training_data: XyTuple = XyTuple.empty()
+	for path in add_to_train_only:
+		try:
+			additional_dataset: Dataset = DatasetLoader.from_path(
+				path=path,
+				loading_type=loading_type,
+				seed=DataScienceConfig.SEED,
+				test_size=0,  # Use all data for training
+				**kwargs
+			)
+			additional_training_data += additional_dataset.training_data
+		except Exception as e:
+			error(f"Failed to load additional training data from '{path}': {e}")
+
+	# Prepare the initialization arguments
+	# (num_classes: int, kfold: int = 0, transfer_learning: str = "imagenet", **override_params: Any)
+	initialization_args: dict[str, Any] = {
+
+		# Mandatory arguments
+		"num_classes": dataset.num_classes,
+		"kfold": kfold,
+		"transfer_learning": transfer_learning,
+
+		# Optional arguments (override_params)
+		"additional_training_data": additional_training_data
+	}
+
+	# Collect all class routines that match the model name
+	classes: list[type[ModelInterface]] = [key for key, values in CLASS_MAP.items() if model in values]
+
+	# For each parameter combination
+	for i, params in enumerate(param_combinations):
+		if grid_search:
+			progress(f"Grid search {i+1}/{len(param_combinations)}, Training with parameters:\n{params}")
+			initialization_args["override_params"] = params
+
+		# Launch all class routines
+		for class_to_process in classes:
+			model_instance: ModelInterface = class_to_process(**initialization_args)
+			trained_model: ModelInterface = model_instance.routine_full(dataset, verbose)
+			info(trained_model)
+			del trained_model
+	return
+

stouputils/data_science/utils.py

@@ -0,0 +1,285 @@
+"""
+This module contains the Utils class, which provides static methods for common operations.
+
+This class contains static methods for:
+
+- Safe division (with 0 as denominator or None)
+- Safe multiplication (with None)
+- Converting between one-hot encoding and class indices
+- Calculating ROC curves and AUC scores
+"""
+# pyright: reportUnknownMemberType=false
+# pyright: reportUnknownVariableType=false
+
+# Imports
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..ctx import Muffle
+from ..decorators import handle_error
+from .config.get import DataScienceConfig
+
+
+# Class
+class Utils:
+	""" Utility class providing common operations. """
+
+	@staticmethod
+	def safe_divide_float(a: float, b: float) -> float:
+		""" Safe division of two numbers, return 0 if denominator is 0.
+
+		Args:
+			a  (float):  First number
+			b  (float):  Second number
+		Returns:
+			float: Result of the division
+
+		Examples:
+			>>> Utils.safe_divide_float(10, 2)
+			5.0
+			>>> Utils.safe_divide_float(0, 5)
+			0.0
+			>>> Utils.safe_divide_float(10, 0)
+			0
+			>>> Utils.safe_divide_float(-10, 2)
+			-5.0
+		"""
+		return a / b if b > 0 else 0
+
+	@staticmethod
+	def safe_divide_none(a: float | None, b: float | None) -> float | None:
+		""" Safe division of two numbers, return None if either number is None or denominator is 0.
+
+		Args:
+			a  (float | None):  First number
+			b  (float | None):  Second number
+		Returns:
+			float | None: Result of the division or None if denominator is None
+
+		Examples:
+			>>> None == Utils.safe_divide_none(None, 2)
+			True
+			>>> None == Utils.safe_divide_none(10, None)
+			True
+			>>> None == Utils.safe_divide_none(10, 0)
+			True
+			>>> Utils.safe_divide_none(10, 2)
+			5.0
+		"""
+		return a / b if a is not None and b is not None and b > 0 else None
+
+	@staticmethod
+	def safe_multiply_none(a: float | None, b: float | None) -> float | None:
+		""" Safe multiplication of two numbers, return None if either number is None.
+
+		Args:
+			a  (float | None):  First number
+			b  (float | None):  Second number
+		Returns:
+			float | None: Result of the multiplication or None if either number is None
+
+		Examples:
+			>>> None == Utils.safe_multiply_none(None, 2)
+			True
+			>>> None == Utils.safe_multiply_none(10, None)
+			True
+			>>> Utils.safe_multiply_none(10, 2)
+			20
+			>>> Utils.safe_multiply_none(-10, 2)
+			-20
+		"""
+		return a * b if a is not None and b is not None else None
+
+	@staticmethod
+	@handle_error(error_log=DataScienceConfig.ERROR_LOG)
+	def convert_to_class_indices(y: NDArray[np.intc | np.single] | list[NDArray[np.intc | np.single]]) -> NDArray[Any]:
+		""" Convert array from one-hot encoded format to class indices.
+		If the input is already class indices, it returns the same array.
+
+		Args:
+			y (NDArray[intc | single] | list[NDArray[intc | single]]): Input array (either one-hot encoded or class indices)
+		Returns:
+			NDArray[Any]: Array of class indices: [[0, 0, 1, 0], [1, 0, 0, 0]] -> [2, 0]
+
+		Examples:
+			>>> Utils.convert_to_class_indices(np.array([[0, 0, 1, 0], [1, 0, 0, 0]])).tolist()
+			[2, 0]
+			>>> Utils.convert_to_class_indices(np.array([2, 0, 1])).tolist()
+			[2, 0, 1]
+			>>> Utils.convert_to_class_indices(np.array([[1], [0]])).tolist()
+			[[1], [0]]
+			>>> Utils.convert_to_class_indices(np.array([])).tolist()
+			[]
+		"""
+		y = np.array(y)
+		if y.ndim > 1 and y.shape[1] > 1:
+			return np.argmax(y, axis=1)
+		return y
+
+	@staticmethod
+	@handle_error(error_log=DataScienceConfig.ERROR_LOG)
+	def convert_to_one_hot(
+		y: NDArray[np.intc | np.single] | list[NDArray[np.intc | np.single]], num_classes: int
+	) -> NDArray[Any]:
+		""" Convert array from class indices to one-hot encoded format.
+		If the input is already one-hot encoded, it returns the same array.
+
+		Args:
+			y            (NDArray[intc|single] | list[NDArray[intc|single]]):  Input array (either class indices or one-hot encoded)
+			num_classes  (int):                                                Total number of classes
+		Returns:
+			NDArray[Any]:	One-hot encoded array: [2, 0] -> [[0, 0, 1, 0], [1, 0, 0, 0]]
+
+		Examples:
+			>>> Utils.convert_to_one_hot(np.array([2, 0]), 4).tolist()
+			[[0.0, 0.0, 1.0, 0.0], [1.0, 0.0, 0.0, 0.0]]
+			>>> Utils.convert_to_one_hot(np.array([[0, 0, 1, 0], [1, 0, 0, 0]]), 4).tolist()
+			[[0, 0, 1, 0], [1, 0, 0, 0]]
+			>>> Utils.convert_to_one_hot(np.array([0, 1, 2]), 3).shape
+			(3, 3)
+			>>> Utils.convert_to_one_hot(np.array([]), 3)
+			array([], shape=(0, 3), dtype=float32)
+
+			>>> array = np.array([[0.1, 0.9], [0.2, 0.8]])
+			>>> array = Utils.convert_to_class_indices(array)
+			>>> array = Utils.convert_to_one_hot(array, 2)
+			>>> array.tolist()
+			[[0.0, 1.0], [0.0, 1.0]]
+		"""
+		y = np.array(y)
+		if y.ndim == 1 or y.shape[1] != num_classes:
+
+			# Get the number of samples and create a one-hot encoded array
+			n_samples: int = len(y)
+			one_hot: NDArray[np.float32] = np.zeros((n_samples, num_classes), dtype=np.float32)
+			if n_samples > 0:
+				# Create a one-hot encoding by setting specific positions to 1.0:
+				# - np.arange(n_samples) creates an array [0, 1, 2, ..., n_samples-1] for row indices
+				# - y.astype(int) contains the class indices that determine which column gets the 1.0
+				# - Together they form coordinate pairs (row_idx, class_idx) where we set values to 1.0
+				row_indices: NDArray[np.intc] = np.arange(n_samples)
+				one_hot[row_indices, y.astype(int)] = 1.0
+			return one_hot
+		return y
+
+	@staticmethod
+	@handle_error(error_log=DataScienceConfig.ERROR_LOG)
+	def get_roc_curve_and_auc(
+		y_true: NDArray[np.intc | np.single],
+		y_pred: NDArray[np.single]
+	) -> tuple[float, NDArray[np.single], NDArray[np.single], NDArray[np.single]]:
+		""" Calculate ROC curve and AUC score.
+
+		Args:
+			y_true  (NDArray[intc | single]):   True class labels (either one-hot encoded or class indices)
+			y_pred  (NDArray[single]):           Predicted probabilities (must be probability scores, not class indices)
+		Returns:
+			tuple[float, NDArray[np.single], NDArray[np.single], NDArray[np.single]]:
+				Tuple containing AUC score, False Positive Rate, True Positive Rate, and Thresholds
+
+		Examples:
+			>>> # Binary classification example
+			>>> y_true = np.array([0.0, 1.0, 0.0, 1.0, 0.0])
+			>>> y_pred = np.array([[0.2, 0.8], [0.1, 0.9], [0.8, 0.2], [0.2, 0.8], [0.7, 0.3]])
+			>>> auc_value, fpr, tpr, thresholds = Utils.get_roc_curve_and_auc(y_true, y_pred)
+			>>> round(auc_value, 2)
+			0.92
+			>>> [round(x, 2) for x in fpr.tolist()]
+			[0.0, 0.0, 0.33, 0.67, 1.0]
+			>>> [round(x, 2) for x in tpr.tolist()]
+			[0.0, 0.5, 1.0, 1.0, 1.0]
+			>>> [round(x, 2) for x in thresholds.tolist()]
+			[inf, 0.9, 0.8, 0.3, 0.2]
+		"""
+		# For predictions, assert they are probabilities (one-hot encoded)
+		assert y_pred.ndim > 1 and y_pred.shape[1] > 1, "Predictions must be probability scores in one-hot format"
+		pred_probs: NDArray[np.single] = y_pred[:, 1]  # Take probability of positive class only
+
+		# Calculate ROC curve and AUC score using probabilities
+		with Muffle(mute_stderr=True):	# Suppress "UndefinedMetricWarning: No positive samples in y_true [...]"
+
+			# Import functions
+			try:
+				from sklearn.metrics import roc_auc_score, roc_curve
+			except ImportError as e:
+				raise ImportError("scikit-learn is required for ROC curve calculation. Install with 'pip install scikit-learn'") from e
+
+			# Convert y_true to class indices for both functions
+			y_true_indices: NDArray[np.intc] = Utils.convert_to_class_indices(y_true)
+
+			# Calculate AUC score directly using roc_auc_score
+			auc_value: float = float(roc_auc_score(y_true_indices, pred_probs))
+
+			# Calculate ROC curve points
+			results: tuple[Any, Any, Any] = roc_curve(y_true_indices, pred_probs, drop_intermediate=False)
+			fpr: NDArray[np.single] = results[0]
+			tpr: NDArray[np.single] = results[1]
+			thresholds: NDArray[np.single] = results[2]
+
+		return auc_value, fpr, tpr, thresholds
+
+	@staticmethod
+	@handle_error(error_log=DataScienceConfig.ERROR_LOG)
+	def get_pr_curve_and_auc(
+		y_true: NDArray[np.intc | np.single],
+		y_pred: NDArray[np.single],
+		negative: bool = False
+	) -> tuple[float, float, NDArray[np.single], NDArray[np.single], NDArray[np.single]]:
+		""" Calculate Precision-Recall Curve (or Negative Precision-Recall Curve) and AUC score.
+
+		Args:
+			y_true  (NDArray[intc | single]):   True class labels (either one-hot encoded or class indices)
+			y_pred  (NDArray[single]):          Predicted probabilities (must be probability scores, not class indices)
+			negative (bool):                    Whether to calculate the negative Precision-Recall Curve
+		Returns:
+			tuple[float, NDArray[np.single], NDArray[np.single], NDArray[np.single]]:
+				Tuple containing either:
+					- AUC score, Average Precision, Precision, Recall, and Thresholds
+					- AUC score, Average Precision, Negative Predictive Value, Specificity, and Thresholds for the negative class
+
+		Examples:
+			>>> # Binary classification example
+			>>> y_true = np.array([0.0, 1.0, 0.0, 1.0, 0.0])
+			>>> y_pred = np.array([[0.2, 0.8], [0.1, 0.9], [0.8, 0.2], [0.2, 0.8], [0.7, 0.3]])
+			>>> auc_value, average_precision, precision, recall, thresholds = Utils.get_pr_curve_and_auc(y_true, y_pred)
+			>>> round(auc_value, 2)
+			0.92
+			>>> round(average_precision, 2)
+			0.83
+			>>> [round(x, 2) for x in precision.tolist()]
+			[0.4, 0.5, 0.67, 1.0, 1.0]
+			>>> [round(x, 2) for x in recall.tolist()]
+			[1.0, 1.0, 1.0, 0.5, 0.0]
+			>>> [round(x, 2) for x in thresholds.tolist()]
+			[0.2, 0.3, 0.8, 0.9]
+		"""
+		# For predictions, assert they are probabilities (one-hot encoded)
+		assert y_pred.ndim > 1 and y_pred.shape[1] > 1, "Predictions must be probability scores in one-hot format"
+		pred_probs: NDArray[np.single] = y_pred[:, 1] if not negative else y_pred[:, 0]
+
+		# Calculate Precision-Recall Curve and AUC score using probabilities
+		with Muffle(mute_stderr=True):	# Suppress "UndefinedMetricWarning: No positive samples in y_true [...]"
+
+			# Import functions
+			try:
+				from sklearn.metrics import auc, average_precision_score, precision_recall_curve
+			except ImportError as e:
+				raise ImportError("scikit-learn is required for PR Curve calculation. Install with 'pip install scikit-learn'") from e
+
+			# Convert y_true to class indices for both functions
+			y_true_indices: NDArray[np.intc] = Utils.convert_to_class_indices(y_true)
+
+			results: tuple[Any, Any, Any] = precision_recall_curve(
+				y_true_indices,
+				pred_probs,
+				pos_label=1 if not negative else 0
+			)
+			precision: NDArray[np.single] = results[0]
+			recall: NDArray[np.single] = results[1]
+			thresholds: NDArray[np.single] = results[2]
+			auc_value: float = float(auc(recall, precision))
+			average_precision: float = float(average_precision_score(y_true_indices, pred_probs))
+		return auc_value, average_precision, precision, recall, thresholds
+