API documentation

Author: urbanmatthias

autoPyTorch/components/ensembles/abstract_ensemble.py

@@ -2,6 +2,8 @@
 
 
 class AbstractEnsemble(object):
+    """Ensemble interface extracted from auto-sklearn"""
+
     __metaclass__ = ABCMeta
 
     @abstractmethod

autoPyTorch/components/ensembles/ensemble_selection.py

@@ -7,6 +7,8 @@
 
 
 class EnsembleSelection(AbstractEnsemble):
+    """Ensemble Selection algorithm extracted from auto-sklearn"""
+    
     def __init__(self, ensemble_size, metric,
                  sorted_initialization_n_best=0, only_consider_n_best=0,
                  bagging=False, mode='fast'):

autoPyTorch/components/lr_scheduler/lr_schedulers.py

@@ -17,8 +17,18 @@
 __license__ = "BSD"
 
 class AutoNetLearningRateSchedulerBase(object):
-    def __new__(cls, params, config):
-        scheduler = cls._get_scheduler(cls, params, config)
+    def __new__(cls, optimizer, config):
+        """Get a new instance of the scheduler
+        
+        Arguments:
+            cls {class} -- Type of scheduler
+            optimizer {Optmizer} -- A PyTorch Optimizer
+            config {dict} -- Sampled lr_scheduler config
+        
+        Returns:
+            AutoNetLearningRateSchedulerBase -- The learning rate scheduler object
+        """
+        scheduler = cls._get_scheduler(cls, optimizer, config)
         if not hasattr(scheduler, "allows_early_stopping"):
             scheduler.allows_early_stopping = True
         if not hasattr(scheduler, "snapshot_before_restart"):

autoPyTorch/components/metrics/additional_logs.py

@@ -1,5 +1,6 @@
 
 class test_result():
+    """Log the performance on the test set"""
     def __init__(self, autonet, X_test, Y_test):
         self.autonet = autonet
         self.X_test = X_test

autoPyTorch/components/metrics/balanced_accuracy.py

@@ -5,6 +5,7 @@
 
 
 def balanced_accuracy(solution, prediction):
+    """balanced accuracy implementation of auto-sklearn"""
 
     y_type, solution, prediction = _check_targets(solution, prediction)
 

autoPyTorch/core/autonet_classes/autonet_feature_classification.py

@@ -3,6 +3,7 @@
 class AutoNetClassification(AutoNetFeatureData):
     preset_folder_name = "feature_classification"
 
+    # OVERRIDE
     @staticmethod
     def _apply_default_pipeline_settings(pipeline):
         from autoPyTorch.pipeline.nodes.network_selector import NetworkSelector

autoPyTorch/core/autonet_classes/autonet_feature_data.py

@@ -9,6 +9,11 @@ class AutoNetFeatureData(AutoNet):
 
     @classmethod
     def get_default_ensemble_pipeline(cls):
+        """Construct a default pipeline, include nodes for Ensemble.
+        
+        Returns:
+            Pipeline -- The constructed default pipeline
+        """
         from autoPyTorch.pipeline.base.pipeline import Pipeline
         from autoPyTorch.pipeline.nodes import AutoNetSettings, OptimizationAlgorithm, \
             CrossValidation, Imputation, NormalizationStrategySelector, OneHotEncoding, PreprocessorSelector, ResamplingStrategySelector, \
@@ -50,6 +55,11 @@ def get_default_ensemble_pipeline(cls):
 
     @classmethod
     def get_default_pipeline(cls):
+        """Construct a default pipeline, do not include nodes for Ensemble.
+        
+        Returns:
+            Pipeline -- The constructed default pipeline
+        """
         from autoPyTorch.pipeline.base.pipeline import Pipeline
         from autoPyTorch.pipeline.nodes import AutoNetSettings, OptimizationAlgorithm, \
             CrossValidation, Imputation, NormalizationStrategySelector, OneHotEncoding, PreprocessorSelector, ResamplingStrategySelector, \
@@ -87,6 +97,11 @@ def get_default_pipeline(cls):
 
     @staticmethod
     def _apply_default_pipeline_settings(pipeline):
+        """Add the components to the pipeline
+        
+        Arguments:
+            pipeline {pipeline} -- The pipelines to add the components to
+        """
         from autoPyTorch.pipeline.nodes import NormalizationStrategySelector, PreprocessorSelector, EmbeddingSelector, NetworkSelector, \
             OptimizerSelector, LearningrateSchedulerSelector, TrainNode, CrossValidation, InitializationSelector
 
@@ -150,4 +165,4 @@ def _apply_default_pipeline_settings(pipeline):
         train_node.add_batch_loss_computation_technique("mixup", Mixup)
 
         cv = pipeline[CrossValidation.get_name()]
-        cv.add_cross_validator("k_fold", KFold)
+        cv.add_cross_validator("k_fold", KFold)

autoPyTorch/core/autonet_classes/autonet_feature_multilabel.py

@@ -3,6 +3,7 @@
 class AutoNetMultilabel(AutoNetFeatureData):
     preset_folder_name = "feature_multilabel"
 
+    # OVERRIDE
     @staticmethod
     def _apply_default_pipeline_settings(pipeline):
         from autoPyTorch.pipeline.nodes.network_selector import NetworkSelector

autoPyTorch/core/autonet_classes/autonet_feature_regression.py

@@ -8,6 +8,7 @@
 class AutoNetRegression(AutoNetFeatureData):
     preset_folder_name = "feature_regression"
 
+    # OVERRIDE
     @staticmethod
     def _apply_default_pipeline_settings(pipeline):
         from autoPyTorch.pipeline.nodes.network_selector import NetworkSelector

autoPyTorch/data_management/data_manager.py

@@ -21,7 +21,14 @@ class ProblemType(Enum):
     FeatureMultilabel = 4
 
 class DataManager(object):
+    """ Load data from multiple sources and formants"""
+
     def __init__(self, verbose=0):
+        """Construct the DataManager
+        
+        Keyword Arguments:
+            verbose {bool} -- Whether to print stuff. (default: {0})
+        """
         self.verbose = verbose
         self.X_train, self.Y_train = None, None
         self.X_test, self.Y_test = None, None
@@ -33,6 +40,16 @@ def __init__(self, verbose=0):
         self.categorical_features = None
 
     def read_data(self, file_name, test_split=0.0, is_classification=None, random_seed=0, **kwargs):
+        """Read the data.
+        
+        Arguments:
+            file_name {str} -- The name of the file to load. Different Readers are associated with different filenames.
+        
+        Keyword Arguments:
+            test_split {float} -- Amount of data to use as test split (default: {0.0})
+            is_classification {bool} -- Whether the data is a classification task (default: {None})
+            random_seed {int} -- a random seed (default: {0})
+        """
         print("Read:" + file_name)
         reader = self._get_reader(file_name, is_classification)
         reader.read()
@@ -53,6 +70,18 @@ def read_data(self, file_name, test_split=0.0, is_classification=None, random_se
         self._split_data(test_split, random_seed)
 
     def _get_reader(self, file_name, is_classification):
+        """Get the reader associated with the filename.
+        
+        Arguments:
+            file_name {str} -- The file to load
+            is_classification {bool} -- Whether the data is a classification task or not
+        
+        Raises:
+            ValueError: The given file type is not supported
+        
+        Returns:
+            DataReader -- A reader that is able to read the data type
+        """
         if file_name.endswith(".csv"):
             reader = CSVReader(file_name, is_classification=is_classification)
         elif file_name.startswith("openml:"):
@@ -65,6 +94,17 @@ def _get_reader(self, file_name, is_classification):
         return reader
 
     def generate_classification(self, num_classes, num_features, num_samples, test_split=0.1, seed=0):
+        """Generate a classification task
+        
+        Arguments:
+            num_classes {int} -- Number of classes
+            num_features {int} -- Number of features
+            num_samples {int} -- Number of samples
+        
+        Keyword Arguments:
+            test_split {float} -- Size of test split (default: {0.1})
+            seed {int} -- A random seed (default: {0})
+        """
         #X, Y = make_classification(n_samples=800, n_features=num_feats, n_classes=num_classes, n_informative=4)
         X, y = make_multilabel_classification(
             n_samples=num_samples, n_features=num_features, n_classes=num_classes, n_labels=0.01,
@@ -78,13 +118,29 @@ def generate_classification(self, num_classes, num_features, num_samples, test_s
         self._split_data(test_split, seed)
 
     def generate_regression(self, num_features, num_samples, test_split=0.1, seed=0):
+        """Generate a regression task
+        
+        Arguments:
+            num_features {int} -- Number of features
+            num_samples {int} -- Number of samples
+        
+        Keyword Arguments:
+            test_split {float} -- Size of test split (default: {0.1})
+            seed {int} -- a random seed (default: {0})
+        """
         X, Y = make_regression(n_samples=num_samples, n_features=num_features, random_state=seed)
         self.categorical_features = [False] * num_features
         self.problem_type = ProblemType.FeatureRegression
         self.X, self.Y = X, Y
         self._split_data(test_split, seed)
 
     def _split_data(self, test_split, seed):
+        """Split the data in test (, valid) and training set.
+        
+        Arguments:
+            test_split {[type]} -- [description]
+            seed {[type]} -- [description]
+        """
         valid_specified = self.X_valid is not None and self.Y_valid is not None
         test_specified = self.X_test is not None and self.Y_test is not None
 
@@ -101,6 +157,17 @@ def _split_data(self, test_split, seed):
         self.Y_train = self.Y
 
 def deterministic_shuffle_and_split(X, Y, split, seed):
+    """Split the data deterministically given the seed
+    
+    Arguments:
+        X {array} -- The feature data
+        Y {array} -- The targets
+        split {float} -- The size of the split
+        seed {int} -- A random seed
+    
+    Returns:
+        tuple -- Tuple of full data and the two splits
+    """
     rng = np.random.RandomState(seed)
     p = rng.permutation(X.shape[0])
 
@@ -110,4 +177,4 @@ def deterministic_shuffle_and_split(X, Y, split, seed):
         split = int(split * X.shape[0])
         return X, Y, X[0:-split], Y[0:-split], X[-split:], Y[-split:]
     else:
-        return X, Y, X, Y, None, None
+        return X, Y, X, Y, None, None

autoPyTorch/pipeline/base/node.py

@@ -14,17 +14,41 @@ def __init__(self):
         self.predict_output = None
 
     def fit(self, **kwargs):
+        """Fit pipeline node.
+        Each node computes its fit function in linear order by fit_traverse()..
+        All args have to be specified in a parent node fit output.
+
+        Returns:
+            dict -- output values that will be passed to child nodes, if required
+        """
         return dict()
 
     def predict(self, **kwargs):
+        """Predict pipeline node.
+        Each node computes its predict function in linear order by predict_traverse().
+        All args have to be specified in a parent node predict output or in the fit output of this node
+
+        Returns:
+            dict -- output values that will be passed to child nodes, if required
+        """
         return dict()
 
     def get_fit_argspec(self):
+        """Get the necessary keywords of the fit method for this node
+        
+        Returns:
+            tuple -- The keywords and their defaults
+        """
         possible_keywords, _, _, defaults, _, _, _ = inspect.getfullargspec(self.fit)
         possible_keywords = [k for k in possible_keywords if k != 'self']
         return possible_keywords, defaults
 
     def get_predict_argspec(self):
+        """Get the necessary keywords of the predict method for this node
+        
+        Returns:
+            tuple -- The keywords and their defaults
+        """
         possible_keywords, _, _, defaults, _, _, _ = inspect.getfullargspec(self.predict)
         possible_keywords = [k for k in possible_keywords if k != 'self']
         return possible_keywords, defaults
@@ -39,10 +63,15 @@ def clean_fit_data(self):
             node = node.child_node
 
     def fit_traverse(self, **kwargs):
-        """Calls fit function of child nodes.
+        """
+        Calls fit function of child nodes.
         The fit function can have different keyword arguments.
         All keywords have to be either defined in kwargs or in an fit output of a parent node.
-        
+
+        The fit method of each node specifies a list of keyword arguments.
+        The fit method of each node returns a dictionary of values for keywords of follwing nodes.
+
+        This method collects the results of each fit method call and calls the fit methods with the collected values.
         """
 
         self.clean_fit_data()
@@ -51,32 +80,38 @@ def fit_traverse(self, **kwargs):
         base = Node()
         base.fit_output = kwargs
 
+        # map all collected kwargs to node whose result the kwarg was
         available_kwargs = {key: base for key in kwargs.keys()}
 
         node = self
         prev_node = base
 
         while (node is not None):
             prev_node = node
+            # get necessary kwargs of current node
             possible_keywords, defaults = node.get_fit_argspec()
 
             last_required_keyword_index = len(possible_keywords) - len(defaults or [])
             required_kwargs = dict()
+
+            # get the values to the necessary keywords if available. Use default if not.
             for index, keyword in enumerate(possible_keywords):
                 if (keyword in available_kwargs):
                     required_kwargs[keyword] = available_kwargs[keyword].fit_output[keyword]
 
                 elif index >= last_required_keyword_index:
                     required_kwargs[keyword] = defaults[index - last_required_keyword_index]
 
-                else:
+                else:  # Neither default specified nor keyword available
                     print ("Available keywords:", sorted(available_kwargs.keys()))
                     raise ValueError('Node ' + str(type(node)) + ' requires keyword ' + str(keyword) + ' which is not available.')
 
+            # call fit method
             node.fit_output = node.fit(**required_kwargs)
             if (not isinstance(node.fit_output, dict)):
                 raise ValueError('Node ' + str(type(node)) + ' does not return a dictionary.')
 
+            # collect resulting keyword-value pairs
             for keyword in node.fit_output.keys():
                 if keyword in available_kwargs:
                     # delete old values
@@ -92,13 +127,20 @@ def fit_traverse(self, **kwargs):
     def predict_traverse(self, **kwargs):
         """Calls predict function of child nodes.
         The predict function can have different keyword arguments.
-        All keywords have to be either defined in kwargs, in a predict output of a parent node or in the nodes own fit output
+        All keywords have to be either defined in kwargs, in a predict output of a parent node or in the nodes own fit output.
+
+        The predict method of each node specifies a list of keyword arguments.
+        The predict method of each node returns a dictionary of values for keywords of follwing nodes.
+
+        This method collects the results of each predict method call and calls the predict methods with the collected values.
+        For each node, the results of the fit call can also be passed to the predict method
         
         """
 
         base = Node()
         base.predict_output = kwargs
 
+        # map all collected kwargs to node whose whose result the kwarg was
         available_kwargs = {key: base for key in kwargs.keys()}
 
         node = self
@@ -115,10 +157,13 @@ def predict_traverse(self, **kwargs):
 
         while (node is not None):
             prev_node = node
+            # get necessary kwargs of current node
             possible_keywords, defaults = node.get_predict_argspec()
 
             last_required_keyword_index = len(possible_keywords) - len(defaults or [])
             required_kwargs = dict()
+
+            # get the values to the necessary keywords if available. Use fit result or default if not.
             for index, keyword in enumerate(possible_keywords):
                 if (keyword in available_kwargs):
                     if (available_kwargs[keyword].predict_output is None):
@@ -131,13 +176,14 @@ def predict_traverse(self, **kwargs):
                 elif index >= last_required_keyword_index:
                     required_kwargs[keyword] = defaults[index - last_required_keyword_index]
 
-                else:
+                else:  # Neither default specified nor keyword available nor available in fit result of the node
                     raise ValueError('Node ' + str(type(node)) + ' requires keyword ' + keyword + ' which is not available.')
 
             node.predict_output = node.predict(**required_kwargs)
             if (not isinstance(node.predict_output, dict)):
                 raise ValueError('Node ' + str(type(node)) + ' does not return a dictionary.')
 
+            # collect keyword arguments
             for keyword in node.predict_output.keys():
                 if keyword in available_kwargs:
                     # delete old values