classifierpromax.ClassifierOptimizer
====================================

.. py:module:: classifierpromax.ClassifierOptimizer


Functions
---------

.. autoapisummary::

   classifierpromax.ClassifierOptimizer.get_param_distributions
   classifierpromax.ClassifierOptimizer.get_scoring_metrics
   classifierpromax.ClassifierOptimizer.validate_inputs
   classifierpromax.ClassifierOptimizer.optimize_model
   classifierpromax.ClassifierOptimizer.evaluate_model
   classifierpromax.ClassifierOptimizer.ClassifierOptimizer


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

.. py:function:: get_param_distributions()

.. py:function:: get_scoring_metrics()

.. py:function:: validate_inputs(model_dict, param_dist, X_train, y_train, scoring, n_iter, cv, random_state, n_jobs)

.. py:function:: optimize_model(name, model, param_dist, X_train, y_train, scoring, n_iter, cv, random_state, n_jobs)

.. py:function:: evaluate_model(name, model, X_train, y_train, cv)

.. py:function:: ClassifierOptimizer(model_dict, X_train, y_train, scoring='f1', n_iter=100, cv=5, random_state=42, n_jobs=-1)

   Optimizes a dictionary of scikit-learn Pipeline classifiers using RandomizedSearchCV
   and evaluates their performance.

   Parameters:
   -----------
   model_dict : dict
       A dictionary where keys are model names (str) and values are scikit-learn Pipeline objects.
       Each pipeline must contain a classifier whose hyperparameters are defined in `param_dist`.

   X_train : pandas.DataFrame or numpy.ndarray
       The feature matrix for training the classifiers. Must have the same number of samples as `y_train`.

   y_train : pandas.Series or numpy.ndarray
       The target labels for training the classifiers. Must have the same number of samples as `X_train`.

   scoring : str, optional, default='f1'
       The scoring metric to use for hyperparameter optimization and model evaluation.
       Must be one of the following:
       - "accuracy"
       - "precision"
       - "recall"
       - "f1"

   n_iter : int, optional, default=100
       The number of parameter settings sampled for RandomizedSearchCV.

   cv : int, optional, default=5
       The number of cross-validation folds for both RandomizedSearchCV and cross_validate.

   random_state : int, optional, default=42
       Random seed for reproducibility of RandomizedSearchCV.

   n_jobs : int, optional, default=-1
       The number of jobs to run in parallel for RandomizedSearchCV (-1 uses all available processors).

   Returns:
   --------
   optimized_model_dict : dict
       A dictionary containing the best estimators for each classifier after hyperparameter optimization.

   scoring_dict : dict
       A dictionary containing cross-validation results for each optimized model, with
       metrics aggregated by mean and standard deviation.

   Raises:
   -------
   ValueError
       If the input parameters are invalid (e.g., empty model dictionary, mismatched data shapes,
       unsupported scoring metric).

   Examples:
   ---------
   >>> from sklearn.pipeline import Pipeline
   >>> from sklearn.linear_model import LogisticRegression
   >>> from sklearn.svm import SVC
   >>> from sklearn.ensemble import RandomForestClassifier
   >>> from sklearn.preprocessing import StandardScaler
   >>> model_dict = {
   ...     'logreg': Pipeline([
   ...         ('scaler', StandardScaler()),
   ...         ('logisticregression', LogisticRegression())
   ...     ]),
   ...     'svc': Pipeline([
   ...         ('scaler', StandardScaler()),
   ...         ('svc', SVC())
   ...     ]),
   ...     'random_forest': Pipeline([
   ...         ('randomforestclassifier', RandomForestClassifier())
   ...     ])
   ... }
   >>> optimized_models, scoring_results = ClassifierOptimizer(model_dict, X_train, y_train)