classifierpromax.ClassifierTrainer
==================================

.. py:module:: classifierpromax.ClassifierTrainer


Functions
---------

.. autoapisummary::

   classifierpromax.ClassifierTrainer.validate_preprocessor
   classifierpromax.ClassifierTrainer.validate_data
   classifierpromax.ClassifierTrainer.get_scoring_metrics
   classifierpromax.ClassifierTrainer.define_models
   classifierpromax.ClassifierTrainer.train_and_evaluate
   classifierpromax.ClassifierTrainer.ClassifierTrainer


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

.. py:function:: validate_preprocessor(preprocessor)

   Validate if the preprocessor has the required `fit` and `transform` methods.

   :raises TypeError: If the preprocessor does not have 'fit' and 'transform' methods.

   .. rubric:: Example

   >>> from sklearn.preprocessing import StandardScaler
   >>> validate_preprocessor(StandardScaler())  # No error
   >>> validate_preprocessor("invalid")  # Raises TypeError


.. py:function:: validate_data(X_train, y_train)

   Ensure that X_train and y_train have the same number of samples.

   :raises ValueError: If the number of samples in X_train and y_train do not match.

   .. rubric:: Example

   >>> import numpy as np
   >>> X_train = np.random.rand(100, 5)
   >>> y_train = np.random.randint(0, 2, size=100)
   >>> validate_data(X_train, y_train)  # No error
   >>> y_train = np.random.randint(0, 2, size=50)
   >>> validate_data(X_train, y_train)  # Raises ValueError


.. py:function:: get_scoring_metrics()

   Return a dictionary of default scoring metrics for model evaluation.

   :returns: A dictionary containing accuracy, precision, recall, and F1-score.
   :rtype: dict

   .. rubric:: Example

   >>> metrics = get_scoring_metrics()
   >>> print(metrics.keys())  # dict_keys(['accuracy', 'precision', 'recall', 'f1'])


.. py:function:: define_models(preprocessor, seed)

   Define a set of machine learning models with preprocessing pipelines.

   :param preprocessor: Preprocessing pipeline applied before training the models.
   :type preprocessor: sklearn.pipeline.Pipeline or transformer
   :param seed: Random seed for reproducibility.
   :type seed: int

   :returns: A dictionary containing model names as keys and pipelines as values.
   :rtype: dict

   .. rubric:: Example

   >>> from sklearn.preprocessing import StandardScaler
   >>> from sklearn.pipeline import Pipeline
   >>> preprocessor = Pipeline([("scaler", StandardScaler())])
   >>> models = define_models(preprocessor, seed=42)
   >>> print(models.keys())  # dict_keys(['dummy', 'logreg', 'svc', 'random_forest'])


.. py:function:: train_and_evaluate(models, X_train, y_train, cv, metrics)

   Train models using cross-validation and return trained models with their evaluation metrics.

   :param models: Dictionary of model pipelines to train.
   :type models: dict
   :param X_train: Training input data.
   :type X_train: array-like
   :param y_train: Training target labels.
   :type y_train: array-like
   :param cv: Number of cross-validation folds.
   :type cv: int
   :param metrics: Scoring metrics for evaluation.
   :type metrics: dict

   :returns: * **trained_models** (*dict*) -- Dictionary containing trained models.
             * **scoring_results** (*dict*) -- Dictionary of DataFrames summarizing mean and std of cross-validation scores.

   :raises ValueError: If training fails due to misaligned data.

   .. rubric:: Example

   >>> from sklearn.datasets import make_classification
   >>> X_train, y_train = make_classification(n_samples=100, n_features=5, random_state=42)
   >>> preprocessor = Pipeline([("scaler", StandardScaler())])
   >>> models = define_models(preprocessor, seed=42)
   >>> trained_models, scoring_results = train_and_evaluate(models, X_train, y_train, cv=5, metrics=get_scoring_metrics())
   >>> print(scoring_results['logreg'])  # DataFrame with mean/std scores


.. py:function:: ClassifierTrainer(preprocessor, X_train, y_train, seed, cv=5, metrics=None)

   Train multiple machine learning classifiers using cross-validation.

   :param preprocessor: A preprocessing pipeline or transformer object with `fit` and `transform` methods.
   :type preprocessor: sklearn.pipeline.Pipeline or transformer
   :param X_train: Training input data.
   :type X_train: array-like
   :param y_train: Target labels corresponding to the training data.
   :type y_train: array-like
   :param seed: Random seed for reproducibility.
   :type seed: int
   :param cv: Number of folds for cross-validation.
   :type cv: int, default=5
   :param metrics: Dictionary of scoring metrics. If None, default metrics are used.
   :type metrics: dict, optional

   :returns: * **trained_models** (*dict*) -- Dictionary of trained model instances.
             * **scoring_results** (*dict*) -- Dictionary of evaluation results as pandas DataFrames.

   :raises TypeError: If preprocessor is not a valid transformer.
   :raises ValueError: If X_train and y_train have inconsistent sample sizes.

   .. rubric:: Example

   >>> from sklearn.datasets import make_classification
   >>> from sklearn.pipeline import Pipeline
   >>> from sklearn.preprocessing import StandardScaler
   >>> X_train, y_train = make_classification(n_samples=100, n_features=5, random_state=42)
   >>> preprocessor = Pipeline([("scaler", StandardScaler())])
   >>> seed = 42
   >>> trained_models, scoring_results = ClassifierTrainer(preprocessor, X_train, y_train, seed)
   >>> print(scoring_results['logreg'])  # DataFrame with mean/std scores