autogluon.task

Example (image classification task):

Tell AutoGluon that task is image classification:

>>> import autogluon as ag
>>> from autogluon import ImageClassification as task

Load a toy image dataset:

>>> filename = ag.download('http://autogluon-hackathon.s3.amazonaws.com/data.zip')
>>> ag.unzip(filename)
>>> dataset = task.Dataset(train_path='data/train')

Fit classification models:

>>> classifier = task.fit(dataset, epochs=2)

Evaluate predictions on test data:

>>> test_dataset = task.Dataset('data/test', train=False)
>>> test_acc = classifier.evaluate(test_dataset)

AutoGluon Tasks

Prediction tasks built into AutoGluon such that a single call to fit() can produce high-quality trained models. For other applications, you can still use AutoGluon to tune the hyperparameters of your own custom models and training scripts.

TabularPrediction

AutoGluon Task for predicting values in column of tabular dataset (classification or regression)

ImageClassification

AutoGluon Task for classifying images based on their content

ObjectDetection

AutoGluon Task for detecting and locating objects in images

TextClassification

AutoGluon Task for classifying text snippets based on their content

TabularPrediction

class autogluon.task.TabularPrediction

AutoGluon Task for predicting values in column of tabular dataset (classification or regression)

Methods

Dataset

alias of autogluon.task.tabular_prediction.dataset.TabularDataset

Predictor

alias of autogluon.task.tabular_prediction.predictor.TabularPredictor

fit(train_data, label[, tuning_data, …])

Fit models to predict a column of data table based on the other columns.

load(output_directory[, verbosity])

Load a predictor object previously produced by fit() from file and returns this object.

Dataset

alias of autogluon.task.tabular_prediction.dataset.TabularDataset

Predictor

alias of autogluon.task.tabular_prediction.predictor.TabularPredictor

static fit(train_data, label, tuning_data=None, time_limits=None, output_directory=None, presets=None, problem_type=None, eval_metric=None, stopping_metric=None, auto_stack=False, hyperparameter_tune=False, feature_prune=False, holdout_frac=None, num_bagging_folds=0, num_bagging_sets=None, stack_ensemble_levels=0, hyperparameters=None, num_trials=None, scheduler_options=None, search_strategy='random', search_options=None, nthreads_per_trial=None, ngpus_per_trial=None, dist_ip_addrs=None, visualizer='none', verbosity=2, **kwargs)

Fit models to predict a column of data table based on the other columns.

Parameters
train_datastr or autogluon.task.tabular_prediction.TabularDataset or pandas.DataFrame

Table of the training data, which is similar to pandas DataFrame. If str is passed, train_data will be loaded using the str value as the file path.

labelstr

Name of the column that contains the target variable to predict.

tuning_datastr or autogluon.task.tabular_prediction.TabularDataset or pandas.DataFrame, default = None

Another dataset containing validation data reserved for hyperparameter tuning (in same format as training data). If str is passed, tuning_data will be loaded using the str value as the file path. Note: final model returned may be fit on this tuning_data as well as train_data. Do not provide your evaluation test data here! In particular, when num_bagging_folds > 0 or stack_ensemble_levels > 0, models will be trained on both tuning_data and train_data. If tuning_data = None, fit() will automatically hold out some random validation examples from train_data.

time_limitsint, default = None

Approximately how long fit() should run for (wallclock time in seconds). If not specified, fit() will run until all models have completed training, but will not repeatedly bag models unless num_bagging_sets or auto_stack is specified.

output_directorystr, default = None

Path to directory where models and intermediate outputs should be saved. If unspecified, a time-stamped folder called “AutogluonModels/ag-[TIMESTAMP]” will be created in the working directory to store all models. Note: To call fit() twice and save all results of each fit, you must specify different output_directory locations. Otherwise files from first fit() will be overwritten by second fit().

presetslist or str or dict, default = ‘medium_quality_faster_train’

List of preset configurations for various arguments in fit(). Can significantly impact predictive accuracy, memory-footprint, and inference latency of trained models, and various other properties of the returned predictor. It is recommended to specify presets and avoid specifying most other fit() arguments or model hyperparameters prior to becoming familiar with AutoGluon. As an example, to get the most accurate overall predictor (regardless of its efficiency), set presets=’best_quality’. To get good quality with minimal disk usage, set presets=[‘good_quality_faster_inference_only_refit’, ‘optimize_for_deployment’] Any user-specified arguments in fit() will override the values used by presets. If specifying a list of presets, later presets will override earlier presets if they alter the same argument. For precise definitions of the provided presets, see file: autogluon/tasks/tabular_prediction/presets_configs.py. Users can specify custom presets by passing in a dictionary of argument values as an element to the list.

Available Presets: [‘best_quality’, ‘best_quality_with_high_quality_refit’, ‘high_quality_fast_inference_only_refit’, ‘good_quality_faster_inference_only_refit’, ‘medium_quality_faster_train’, ‘optimize_for_deployment’, ‘ignore_text’] It is recommended to only use one quality based preset in a given call to fit() as they alter many of the same arguments and are not compatible with each-other.

In-depth Preset Info:
best_quality={‘auto_stack’: True}

Best predictive accuracy with little consideration to inference time or disk usage. Achieve even better results by specifying a large time_limits value. Recommended for applications that benefit from the best possible model accuracy.

best_quality_with_high_quality_refit={‘auto_stack’: True, ‘refit_full’: True}

Identical to best_quality but additionally trains refit_full models that have slightly lower predictive accuracy but are over 10x faster during inference and require 10x less disk space.

high_quality_fast_inference_only_refit={‘auto_stack’: True, ‘refit_full’: True, ‘set_best_to_refit_full’: True, ‘save_bagged_folds’: False}

High predictive accuracy with fast inference. ~10x-200x faster inference and ~10x-200x lower disk usage than best_quality. Recommended for applications that require reasonable inference speed and/or model size.

good_quality_faster_inference_only_refit={‘auto_stack’: True, ‘refit_full’: True, ‘set_best_to_refit_full’: True, ‘save_bagged_folds’: False, ‘hyperparameters’: ‘light’}

Good predictive accuracy with very fast inference. ~4x faster inference and ~4x lower disk usage than high_quality_fast_inference_only_refit. Recommended for applications that require fast inference speed.

medium_quality_faster_train={‘auto_stack’: False}

Medium predictive accuracy with very fast inference and very fast training time. ~20x faster training than good_quality_faster_inference_only_refit. This is the default preset in AutoGluon, but should generally only be used for quick prototyping, as good_quality_faster_inference_only_refit results in significantly better predictive accuracy and faster inference time.

optimize_for_deployment={‘keep_only_best’: True, ‘save_space’: True}

Optimizes result immediately for deployment by deleting unused models and removing training artifacts. Often can reduce disk usage by ~2-4x with no negatives to model accuracy or inference speed. This will disable numerous advanced functionality, but has no impact on inference. This will make certain functionality less informative, such as predictor.leaderboard() and predictor.fit_summary().

Because unused models will be deleted under this preset, methods like predictor.leaderboard() and predictor.fit_summary() will no longer show the full set of models that were trained during fit().

Recommended for applications where the inner details of AutoGluon’s training is not important and there is no intention of manually choosing between the final models. This preset pairs well with the other presets such as good_quality_faster_inference_only_refit to make a very compact final model. Identical to calling predictor.delete_models(models_to_keep=’best’, dry_run=False) and predictor.save_space() directly after fit().

ignore_text={‘feature_generator_kwargs’: {‘enable_text_ngram_features’: False, ‘enable_text_special_features’: False}}

Disables automated feature generation when text features are detected. This is useful to determine how beneficial text features are to the end result, as well as to ensure features are not mistaken for text when they are not.

problem_typestr, default = None

Type of prediction problem, i.e. is this a binary/multiclass classification or regression problem (options: ‘binary’, ‘multiclass’, ‘regression’). If problem_type = None, the prediction problem type is inferred based on the label-values in provided dataset.

eval_metricfunction or str, default = None

Metric by which predictions will be ultimately evaluated on test data. AutoGluon tunes factors such as hyperparameters, early-stopping, ensemble-weights, etc. in order to improve this metric on validation data.

If eval_metric = None, it is automatically chosen based on problem_type. Defaults to ‘accuracy’ for binary and multiclass classification and ‘root_mean_squared_error’ for regression. Otherwise, options for classification:

[‘accuracy’, ‘balanced_accuracy’, ‘f1’, ‘f1_macro’, ‘f1_micro’, ‘f1_weighted’, ‘roc_auc’, ‘average_precision’, ‘precision’, ‘precision_macro’, ‘precision_micro’, ‘precision_weighted’, ‘recall’, ‘recall_macro’, ‘recall_micro’, ‘recall_weighted’, ‘log_loss’, ‘pac_score’]

Options for regression:

[‘root_mean_squared_error’, ‘mean_squared_error’, ‘mean_absolute_error’, ‘median_absolute_error’, ‘r2’]

For more information on these options, see sklearn.metrics: https://scikit-learn.org/stable/modules/classes.html#sklearn-metrics-metrics

You can also pass your own evaluation function here as long as it follows formatting of the functions defined in autogluon/utils/tabular/metrics/.

stopping_metricfunction or str, default = None

Metric which iteratively-trained models use to early stop to avoid overfitting. stopping_metric is not used by weighted ensembles, instead weighted ensembles maximize eval_metric. Defaults to eval_metric value except when eval_metric=’roc_auc’, where it defaults to log_loss. Options are identical to options for eval_metric.

auto_stackbool, default = False

Whether AutoGluon should automatically utilize bagging and multi-layer stack ensembling to boost predictive accuracy. Set this = True if you are willing to tolerate longer training times in order to maximize predictive accuracy! Note: This overrides num_bagging_folds and stack_ensemble_levels arguments (selects optimal values for these parameters based on dataset properties). Note: This can increase training time (and inference time) by up to 20x, but can greatly improve predictive performance.

hyperparameter_tunebool, default = False

Whether to tune hyperparameters or just use fixed hyperparameter values for each model. Setting as True will increase fit() runtimes. It is currently not recommended to use hyperparameter_tune with auto_stack due to potential overfitting. Use auto_stack to maximize predictive accuracy; use hyperparameter_tune if you prefer to deploy just a single model rather than an ensemble.

feature_prunebool, default = False

Whether or not to perform feature selection.

hyperparametersstr or dict, default = ‘default’

Determines the hyperparameters used by the models. If str is passed, will use a preset hyperparameter configuration.

Valid str options: [‘default’, ‘light’, ‘very_light’, ‘toy’]

‘default’: Default AutoGluon hyperparameters intended to maximize accuracy without significant regard to inference time or disk usage. ‘light’: Results in smaller models. Generally will make inference speed much faster and disk usage much lower, but with worse accuracy. ‘very_light’: Results in much smaller models. Behaves similarly to ‘light’, but in many cases with over 10x less disk usage and a further reduction in accuracy. ‘toy’: Results in extremely small models. Only use this when prototyping, as the model quality will be severely reduced.

Reference autogluon/task/tabular_prediction/hyperparameter_configs.py for information on the hyperparameters associated with each preset.

Keys are strings that indicate which model types to train.

Options include: ‘NN’ (neural network), ‘GBM’ (lightGBM boosted trees), ‘CAT’ (CatBoost boosted trees), ‘RF’ (random forest), ‘XT’ (extremely randomized trees), ‘KNN’ (k-nearest neighbors), ‘LR’ (linear regression) If certain key is missing from hyperparameters, then fit() will not train any models of that type. Omitting a model key from hyperparameters is equivalent to including this model key in excluded_model_types. For example, set hyperparameters = { ‘NN’:{…} } if say you only want to train neural networks and no other types of models.

Values = dict of hyperparameter settings for each model type, or list of dicts.

Each hyperparameter can either be a single fixed value or a search space containing many possible values. Unspecified hyperparameters will be set to default values (or default search spaces if hyperparameter_tune = True). Caution: Any provided search spaces will be overridden by fixed defaults if hyperparameter_tune = False. To train multiple models of a given type, set the value to a list of hyperparameter dictionaries.

For example, hyperparameters = {‘RF’: [{‘criterion’: ‘gini’}, {‘criterion’: ‘entropy’}]} will result in 2 random forest models being trained with separate hyperparameters.

Advanced functionality: Custom models
hyperparameters can also take a special key ‘custom’, which maps to a list of model names (currently supported options = ‘GBM’).

If hyperparameter_tune = False, then these additional models will also be trained using custom pre-specified hyperparameter settings that are known to work well.

Advanced functionality: Custom stack levels

By default, AutoGluon re-uses the same models and model hyperparameters at each level during stack ensembling. To customize this behaviour, create a hyperparameters dictionary separately for each stack level, and then add them as values to a new dictionary, with keys equal to the stack level.

Example: `hyperparameters = {0: {‘RF’: rf_params1}, 1: {‘CAT’: [cat_params1, cat_params2], ‘NN’: {}}} This will result in a stack ensemble that has one custom random forest in level 0 followed by two CatBoost models with custom hyperparameters and a default neural network in level 1, for a total of 4 models.

If a level is not specified in hyperparameters, it will default to using the highest specified level to train models. This can also be explicitly controlled by adding a ‘default’ key.

Default:
hyperparameters = {

‘NN’: {}, ‘GBM’: {}, ‘CAT’: {}, ‘RF’: [

{‘criterion’: ‘gini’, ‘AG_args’: {‘name_suffix’: ‘Gini’, ‘problem_types’: [‘binary’, ‘multiclass’]}}, {‘criterion’: ‘entropy’, ‘AG_args’: {‘name_suffix’: ‘Entr’, ‘problem_types’: [‘binary’, ‘multiclass’]}}, {‘criterion’: ‘mse’, ‘AG_args’: {‘name_suffix’: ‘MSE’, ‘problem_types’: [‘regression’]}},

], ‘XT’: [

{‘criterion’: ‘gini’, ‘AG_args’: {‘name_suffix’: ‘Gini’, ‘problem_types’: [‘binary’, ‘multiclass’]}}, {‘criterion’: ‘entropy’, ‘AG_args’: {‘name_suffix’: ‘Entr’, ‘problem_types’: [‘binary’, ‘multiclass’]}}, {‘criterion’: ‘mse’, ‘AG_args’: {‘name_suffix’: ‘MSE’, ‘problem_types’: [‘regression’]}},

], ‘KNN’: [

{‘weights’: ‘uniform’, ‘AG_args’: {‘name_suffix’: ‘Unif’}}, {‘weights’: ‘distance’, ‘AG_args’: {‘name_suffix’: ‘Dist’}},

], ‘custom’: [‘GBM’]

}

Details regarding the hyperparameters you can specify for each model are provided in the following files:
NN: autogluon/utils/tabular/ml/models/tabular_nn/hyperparameters/parameters.py

Note: certain hyperparameter settings may cause these neural networks to train much slower.

GBM: autogluon/utils/tabular/ml/models/lgb/hyperparameters/parameters.py

See also the lightGBM docs: https://lightgbm.readthedocs.io/en/latest/Parameters.html

CAT: autogluon/utils/tabular/ml/models/catboost/hyperparameters/parameters.py

See also the CatBoost docs: https://catboost.ai/docs/concepts/parameter-tuning.html

RF: See sklearn documentation: https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html

Note: Hyperparameter tuning is disabled for this model.

XT: See sklearn documentation: https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.ExtraTreesClassifier.html

Note: Hyperparameter tuning is disabled for this model.

KNN: See sklearn documentation: https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KNeighborsClassifier.html

Note: Hyperparameter tuning is disabled for this model.

LR: autogluon/utils/tabular/ml/models/lr/hyperparameters/parameters.py

Note: Hyperparameter tuning is disabled for this model. Note: ‘penalty’ parameter can be used for regression to specify regularization method: ‘L1’ and ‘L2’ values are supported.

Advanced functionality: Custom AutoGluon model arguments
These arguments are optional and can be specified in any model’s hyperparameters.

Example: hyperparameters = {‘RF’: {…, ‘AG_args’: {‘name_suffix’: ‘CustomModelSuffix’, ‘disable_in_hpo’: True}}

AG_args: Dictionary of customization options related to meta properties of the model such as its name, the order it is trained, and the problem types it is valid for.
Valid keys:

name: (str) The name of the model. This overrides AutoGluon’s naming logic and all other name arguments if present. name_main: (str) The main name of the model. In ‘RandomForestClassifier’, this is ‘RandomForest’. name_prefix: (str) Add a custom prefix to the model name. Unused by default. name_type_suffix: (str) Override the type suffix of the model name. In ‘RandomForestClassifier’, this is ‘Classifier’. This comes before ‘name_suffix’. name_suffix: (str) Add a custom suffix to the model name. Unused by default. priority: (int) Determines the order in which the model is trained. Larger values result in the model being trained earlier. Default values range from 100 (RF) to 0 (custom), dictated by model type. If you want this model to be trained first, set priority = 999. problem_types: (list) List of valid problem types for the model. problem_types=[‘binary’] will result in the model only being trained if problem_type is ‘binary’. disable_in_hpo: (bool) If True, the model will only be trained if hyperparameter_tune=False.

Reference the default hyperparameters for example usage of these options.

AG_args_fit: Dictionary of model fit customization options related to how and with what constraints the model is trained. These parameters affect stacker fold models, but not stacker models themselves.

Clarification: time_limit is the internal time in seconds given to a particular model to train, which is dictated in part by the time_limits argument given during fit() but is not the same. Valid keys:

max_memory_usage_ratio: (float, default=1.0) The ratio of memory usage relative to the default to allow before early stopping or killing the model. Values greater than 1.0 will be increasingly prone to out-of-memory errors. max_time_limit_ratio: (float, default=1.0) The ratio of the provided time_limit to use during model fit(). If time_limit=10 and max_time_limit_ratio=0.3, time_limit would be changed to 3. Does not alter max_time_limit or min_time_limit values. max_time_limit: (float, default=None) Maximum amount of time to allow this model to train for (in sec). If the provided time_limit is greater than this value, it will be replaced by max_time_limit. min_time_limit: (float, default=0) Allow this model to train for at least this long (in sec), regardless of the time limit it would otherwise be granted.

If min_time_limit >= max_time_limit, time_limit will be set to min_time_limit. If min_time_limit=None, time_limit will be set to None and the model will have no training time restriction.

holdout_fracfloat

Fraction of train_data to holdout as tuning data for optimizing hyperparameters (ignored unless tuning_data = None, ignored if num_bagging_folds != 0). Default value is selected based on the number of rows in the training data. Default values range from 0.2 at 2,500 rows to 0.01 at 250,000 rows. Default value is doubled if hyperparameter_tune = True, up to a maximum of 0.2. Disabled if num_bagging_folds >= 2.

num_bagging_foldsint, default = 0

Number of folds used for bagging of models. When num_bagging_folds = k, training time is roughly increased by a factor of k (set = 0 to disable bagging). Disabled by default, but we recommend values between 5-10 to maximize predictive performance. Increasing num_bagging_folds will result in models with lower bias but that are more prone to overfitting. Values > 10 may produce diminishing returns, and can even harm overall results due to overfitting. To further improve predictions, avoid increasing num_bagging_folds much beyond 10 and instead increase num_bagging_sets.

num_bagging_setsint

Number of repeats of kfold bagging to perform (values must be >= 1). Total number of models trained during bagging = num_bagging_folds * num_bagging_sets. Defaults to 1 if time_limits is not specified, otherwise 20 (always disabled if num_bagging_folds is not specified). Values greater than 1 will result in superior predictive performance, especially on smaller problems and with stacking enabled (reduces overall variance).

stack_ensemble_levelsint, default = 0

Number of stacking levels to use in stack ensemble. Roughly increases model training time by factor of stack_ensemble_levels+1 (set = 0 to disable stack ensembling). Disabled by default, but we recommend values between 1-3 to maximize predictive performance. To prevent overfitting, this argument is ignored unless you have also set num_bagging_folds >= 2.

num_trialsint

Maximal number of different hyperparameter settings of each model type to evaluate during HPO (only matters if hyperparameter_tune = True). If both time_limits and num_trials are specified, time_limits takes precedent.

scheduler_optionsdict

Extra arguments passed to __init__ of scheduler, to configure the orchestration of training jobs during hyperparameter-tuning. Ignored if hyperparameter_tune=False.

search_strategystr

Which hyperparameter search algorithm to use (only matters if hyperparameter_tune=True). Options include: ‘random’ (random search), ‘bayesopt’ (Gaussian process Bayesian optimization), ‘skopt’ (SKopt Bayesian optimization), ‘grid’ (grid search).

search_optionsdict

Auxiliary keyword arguments to pass to the searcher that performs hyperparameter optimization.

nthreads_per_trialint

How many CPUs to use in each training run of an individual model. This is automatically determined by AutoGluon when left as None (based on available compute).

ngpus_per_trialint

How many GPUs to use in each trial (ie. single training run of a model). This is automatically determined by AutoGluon when left as None.

dist_ip_addrslist

List of IP addresses corresponding to remote workers, in order to leverage distributed computation.

visualizerstr

How to visualize the neural network training progress during fit(). Options: [‘mxboard’, ‘tensorboard’, ‘none’].

verbosityint, default = 2

Verbosity levels range from 0 to 4 and control how much information is printed during fit(). Higher levels correspond to more detailed print statements (you can set verbosity = 0 to suppress warnings). If using logging, you can alternatively control amount of information printed via logger.setLevel(L), where L ranges from 0 to 50 (Note: higher values of L correspond to fewer print statements, opposite of verbosity levels)

Kwargs can include additional arguments for advanced users:
AG_args_fitdict, default={}

Keyword arguments to pass to all models. See the AG_args_fit argument from “Advanced functionality: Custom AutoGluon model arguments” in the hyperparameters argument documentation for valid values. Identical to specifying AG_args_fit parameter for all models in hyperparameters. If a key in AG_args_fit is already specified for a model in hyperparameters, it will not be altered through this argument.

excluded_model_typeslist, default = []

Banned subset of model types to avoid training during fit(), even if present in hyperparameters. Valid values: [‘RF’, ‘XT’, ‘KNN’, ‘GBM’, ‘CAT’, ‘NN’, ‘LR’, ‘custom’]. Reference hyperparameters documentation for what models correspond to each value. Useful when a particular model type such as ‘KNN’ or ‘custom’ is not desired but altering the hyperparameters dictionary is difficult or time-consuming.

Example: To exclude both ‘KNN’ and ‘custom’ models, specify excluded_model_types=[‘KNN’, ‘custom’].

id_columnslist, default = []

Banned subset of column names that model may not use as predictive features (e.g. contains label, user-ID, etc). These columns are ignored during fit(), but DataFrame of just these columns with appended predictions may be produced, for example to submit in a ML competition.

label_count_thresholdint, default = 10

For multi-class classification problems, this is the minimum number of times a label must appear in dataset in order to be considered an output class. AutoGluon will ignore any classes whose labels do not appear at least this many times in the dataset (i.e. will never predict them).

save_bagged_foldsbool, default = True

If True, bagged models will save their fold models (the models from each individual fold of bagging). This is required to use bagged models for prediction after fit(). If False, bagged models will not save their fold models. This means that bagged models will not be valid models during inference.

This should only be set to False when planning to call predictor.refit_full() or when refit_full is set and set_best_to_refit_full=True. Particularly useful if disk usage is a concern. By not saving the fold models, bagged models will use only very small amounts of disk space during training. In many training runs, this will reduce peak disk usage by >10x.

This parameter has no effect if bagging is disabled.

keep_only_bestbool, default = False
If True, only the best model and its ancestor models are saved in the outputted predictor. All other models are deleted.

If you only care about deploying the most accurate predictor with the smallest file-size and no longer need any of the other trained models or functionality beyond prediction on new data, then set: keep_only_best=True, save_space=True. This is equivalent to calling predictor.delete_models(models_to_keep=’best’, dry_run=False) directly after fit().

If used with refit_full and set_best_to_refit_full, the best model will be the refit_full model, and the original bagged best model will be deleted.

refit_full will be automatically set to ‘best’ in this case to avoid training models which will be later deleted.

save_spacebool, default = False
If True, reduces the memory and disk size of predictor by deleting auxiliary model files that aren’t needed for prediction on new data.

This is equivalent to calling predictor.save_space() directly after fit().

This has NO impact on inference accuracy. It is recommended if the only goal is to use the trained model for prediction. Certain advanced functionality may no longer be available if save_space=True. Refer to predictor.save_space() documentation for more details.

cache_databool, default = True

When enabled, the training and validation data are saved to disk for future reuse. Enables advanced functionality in the resulting Predictor object such as feature importance calculation on the original data.

refit_fullbool or str, default = False

Whether to retrain all models on all of the data (training + validation) after the normal training procedure. This is equivalent to calling predictor.refit_full(model=refit_full) after training. If refit_full=True, it will be treated as refit_full=’all’. If refit_full=False, refitting will not occur. Valid str values:

all: refits all models. best: refits only the best model (and its ancestors if it is a stacker model). {model_name}: refits only the specified model (and its ancestors if it is a stacker model).

For bagged models:

Reduces a model’s inference time by collapsing bagged ensembles into a single model fit on all of the training data. This process will typically result in a slight accuracy reduction and a large inference speedup. The inference speedup will generally be between 10-200x faster than the original bagged ensemble model.

The inference speedup factor is equivalent to (k * n), where k is the number of folds (num_bagging_folds) and n is the number of finished repeats (num_bagging_sets) in the bagged ensemble.

The runtime is generally 10% or less of the original fit runtime.

The runtime can be roughly estimated as 1 / (k * n) of the original fit runtime, with k and n defined above.

For non-bagged models:

Optimizes a model’s accuracy by retraining on 100% of the data without using a validation set. Will typically result in a slight accuracy increase and no change to inference time. The runtime will be approximately equal to the original fit runtime.

This process does not alter the original models, but instead adds additional models. If stacker models are refit by this process, they will use the refit_full versions of the ancestor models during inference. Models produced by this process will not have validation scores, as they use all of the data for training.

Therefore, it is up to the user to determine if the models are of sufficient quality by including test data in predictor.leaderboard(dataset=test_data). If the user does not have additional test data, they should reference the original model’s score for an estimate of the performance of the refit_full model.

Warning: Be aware that utilizing refit_full models without separately verifying on test data means that the model is untested, and has no guarantee of being consistent with the original model.

The time taken by this process is not enforced by time_limits. cache_data must be set to True to enable this functionality.

set_best_to_refit_fullbool, default = False

If True, will set Trainer.best_model = Trainer.full_model_dict[Trainer.best_model] This will change the default model that Predictor uses for prediction when model is not specified to the refit_full version of the model that previously exhibited the highest validation score. Only valid if refit_full is set.

feature_generator_typeautogluon.utils.tabular.features.auto_ml_feature_generator.AbstractFeatureGenerator class, default = autogluon.utils.tabular.features.auto_ml_feature_generator.AutoMLFeatureGenerator

A FeatureGenerator class specifying which feature engineering protocol to follow Note: The file containing your FeatureGenerator class must be imported into current Python session in order to use a custom class.

feature_generator_kwargsdict, default={}

Keyword arguments to pass into the FeatureGenerator constructor. Valid autogluon.utils.tabular.features.auto_ml_feature_generator.AutoMLFeatureGenerator kwargs:

enable_text_ngram_featuresbool, default = True

If True, the vectorizer argument value is used to generate ‘text_ngram’ features from text features if present. Try setting this to False if you encounter memory issues running AutoGluon on text data and cannot access a machine with more memory.

enable_text_special_featuresbool, default = True

If True, generate ‘text_special’ features from text features if present. Examples of ‘text_special’ features include the number of whitespaces and the average word length in a text feature.

vectorizersklearn.feature_extraction.text.CountVectorizer, default = CountVectorizer(min_df=30, ngram_range=(1, 3), max_features=10000, dtype=np.uint8)

Determines the count vectorizer used during feature generation if text features are detected. If your data contain text fields and you encounter memory issues running AutoGluon (and cannot access a machine with more memory), then consider reducing max_features or setting n_gram_range=(1, 2).

trainer_typeTrainer class, default=`AutoTrainer`

A class inheriting from autogluon.utils.tabular.ml.trainer.abstract_trainer.AbstractTrainer that controls training/ensembling of many models. Note: In order to use a custom Trainer class, you must import the class file that defines it into the current Python session.

random_seedint, default = 0

Seed to use when generating data split indices such as kfold splits and train/validation splits. Caution: This seed only enables reproducible data splits (and the ability to randomize splits in each run by changing seed values). This seed is NOT used in the training of individual models, for that you need to explicitly set the corresponding seed hyperparameter (usually called ‘seed_value’) of each individual model. If stacking is enabled:

The seed used for stack level L is equal to seed+L. This means random_seed=1 will have the same split indices at L=0 as random_seed=0 will have at L=1.

If random_seed=None, a random integer is used.

Returns
autogluon.task.tabular_prediction.TabularPredictor object which can make predictions on new data and summarize what happened during fit().

Examples

>>> from autogluon import TabularPrediction as task
>>> train_data = task.Dataset(file_path='https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv')
>>> label_column = 'class'
>>> predictor = task.fit(train_data=train_data, label=label_column)
>>> test_data = task.Dataset(file_path='https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv')
>>> y_test = test_data[label_column]
>>> test_data = test_data.drop(labels=[label_column], axis=1)
>>> y_pred = predictor.predict(test_data)
>>> perf = predictor.evaluate_predictions(y_true=y_test, y_pred=y_pred)
>>> results = predictor.fit_summary()

To maximize predictive performance, use the following:

>>> eval_metric = 'roc_auc'  # set this to the metric you ultimately care about
>>> time_limits = 360  # set as long as you are willing to wait (in sec)
>>> predictor = task.fit(train_data=train_data, label=label_column, eval_metric=eval_metric, auto_stack=True, time_limits=time_limits)
static load(output_directory, verbosity=2)

Load a predictor object previously produced by fit() from file and returns this object. It is highly recommended the predictor be loaded with the exact AutoGluon version it was fit with.

Parameters
output_directorystr

Path to directory where trained models are stored (i.e. the output_directory specified in previous call to fit).

verbosityint, default = 2

Verbosity levels range from 0 to 4 and control how much information will be printed by the loaded Predictor. Higher levels correspond to more detailed print statements (you can set verbosity = 0 to suppress warnings). If using logging, you can alternatively control amount of information printed via logger.setLevel(L), where L ranges from 0 to 50 (Note: higher values L correspond to fewer print statements, opposite of verbosity levels)

Returns
autogluon.task.tabular_prediction.TabularPredictor object that can be used to make predictions.

ImageClassification

class autogluon.task.ImageClassification

AutoGluon Task for classifying images based on their content

Methods

Classifier(model, results, eval_func, …[, …])

Trained Image Classifier returned by fit() that can be used to make predictions on new images.

Dataset([path, name, train, input_size, …])

Dataset for AutoGluon image classification tasks.

fit(dataset[, net, optimizer, loss, …])

Fit image classification models to a given dataset.

class Classifier(model, results, eval_func, scheduler_checkpoint, args, ensemble=0, format_results=True, **kwargs)

Trained Image Classifier returned by fit() that can be used to make predictions on new images.

Examples

>>> from autogluon import ImageClassification as task
>>> dataset = task.Dataset(train_path='data/train',
>>>                        test_path='data/test')
>>> classifier = task.fit(dataset,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=time_limits,
>>>                       ngpus_per_trial=1,
>>>                       num_trials = 4)
>>> image = 'data/test/BabyShirt/BabyShirt_323.jpg'
>>> ind, prob = classifier.predict(image)

Methods

evaluate(self, dataset[, input_size, ctx])

Evaluate predictive performance of trained image classifier using given test data.

evaluate_predictions(self, y_true, y_pred)

Evaluate the provided list of predictions against list of ground truth labels according to the task-specific evaluation metric (self.eval_func).

fit_summary(self[, output_directory, verbosity])

Returns a summary of the fit process.

load(checkpoint)

Load trained Image Classifier from directory specified by checkpoint.

predict(self, X[, input_size, crop_ratio, …])

Predict class-index and associated class probability for each image in a given dataset (or just a single image).

predict_proba(self, X)

Produces predicted class probabilities for a given image.

save(self, checkpoint)

Save image classifier to folder specified by checkpoint.

loader

state_dict

evaluate(self, dataset, input_size=224, ctx=[cpu(0)])

Evaluate predictive performance of trained image classifier using given test data.

Parameters
datasetautogluon.task.ImageClassification.Dataset

The dataset containing test images (must be in same format as the training dataset).

input_sizeint

Size of the images (pixels).

ctxList of mxnet.context elements.

Determines whether to use CPU or GPU(s), options include: [mx.cpu()] or [mx.gpu()].

Examples

>>> from autogluon import ImageClassification as task
>>> train_data = task.Dataset(train_path='~/data/train')
>>> classifier = task.fit(train_data,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=600, ngpus_per_trial=1, num_trials = 4)
>>> test_data = task.Dataset('~/data/test', train=False)
>>> test_acc = classifier.evaluate(test_data)
evaluate_predictions(self, y_true, y_pred)

Evaluate the provided list of predictions against list of ground truth labels according to the task-specific evaluation metric (self.eval_func).

fit_summary(self, output_directory=None, verbosity=2)

Returns a summary of the fit process. Args:

verbosity (int): how much output to print: <= 0 for no output printing, 1 for just high-level summary, 2 for summary and plot, >= 3 for all information contained in results object.

classmethod load(checkpoint)

Load trained Image Classifier from directory specified by checkpoint.

predict(self, X, input_size=224, crop_ratio=0.875, set_prob_thresh=0.001, plot=False)

Predict class-index and associated class probability for each image in a given dataset (or just a single image).

Parameters
Xstr or autogluon.task.ImageClassification.Dataset or list of autogluon.task.ImageClassification.Dataset

If str, should be path to the input image (when we just want to predict on single image). If class:autogluon.task.ImageClassification.Dataset, should be dataset of multiple images in same format as training dataset. If list of autogluon.task.ImageClassification.Dataset, should be a set of test dataset with different scales of origin images.

input_sizeint

Size of the images (pixels).

plotbool

Whether to plot the image being classified.

set_prob_thresh: float

Results with probability below threshold are set to 0 by default.

Examples

>>> from autogluon import ImageClassification as task
>>> train_data = task.Dataset(train_path='~/data/train')
>>> classifier = task.fit(train_data,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=600, ngpus_per_trial=1, num_trials=4)
>>> test_data = task.Dataset('~/data/test', train=False)
>>> class_index, class_probability = classifier.predict('example.jpg')
predict_proba(self, X)

Produces predicted class probabilities for a given image.

save(self, checkpoint)

Save image classifier to folder specified by checkpoint.

static Dataset(path=None, name=None, train=True, input_size=224, crop_ratio=0.875, *args, **kwargs)
Dataset for AutoGluon image classification tasks.

May either be a autogluon.task.image_classification.ImageFolderDataset, autogluon.task.image_classification.RecordDataset, or a popular dataset already built into AutoGluon (‘mnist’, ‘fashionmnist’, ‘cifar10’, ‘cifar100’, ‘imagenet’).

Parameters
pathstr, optional

The data location. If using ImageFolderDataset, image folder`path/to/the/folder` should be provided. If using RecordDataset, the path/to/*.rec should be provided.

namestr, optional

Which built-in dataset to use, will override all other options if specified. The options are: ‘mnist’, ‘fashionmnist’, ‘cifar’, ‘cifar10’, ‘cifar100’, ‘imagenet’

trainbool, optional, default = True

Whether this dataset should be used for training or validation.

input_sizeint

The input image size.

crop_ratiofloat

Center crop ratio (for evaluation only).

Returns
Dataset object that can be passed to task.fit(), which is actually an autogluon.space.AutoGluonObject.
To interact with such an object yourself, you must first call Dataset.init() to instantiate the object in Python.
static fit(dataset, net=Categorical['ResNet50_v1b', 'ResNet18_v1b'], optimizer=AutoGluonObject -- NAG, loss=AutoGluonObject -- SoftmaxCrossEntropyLoss, split_ratio=0.8, batch_size=64, input_size=224, epochs=20, final_fit_epochs=None, ensemble=1, metric='accuracy', nthreads_per_trial=60, ngpus_per_trial=1, hybridize=True, scheduler_options=None, search_strategy='random', search_options=None, plot_results=False, verbose=False, num_trials=None, time_limits=None, resume=False, output_directory='checkpoint/', visualizer='none', dist_ip_addrs=None, auto_search=True, lr_config=Dict{'lr_mode': 'cosine', 'lr_decay': 0.1, 'lr_decay_period': 0, 'lr_decay_epoch': '40,80', 'warmup_lr': 0.0, 'warmup_epochs': 0}, tricks=Dict{'last_gamma': False, 'use_pretrained': True, 'use_se': False, 'mixup': False, 'mixup_alpha': 0.2, 'mixup_off_epoch': 0, 'label_smoothing': False, 'no_wd': False, 'teacher_name': None, 'temperature': 20.0, 'hard_weight': 0.5, 'batch_norm': False, 'use_gn': False}, **kwargs)

Fit image classification models to a given dataset.

Parameters
datasetstr or autogluon.task.ImageClassification.Dataset()

Training dataset containing images and their associated class labels. Popular image datasets built into AutoGluon can be used by specifying their name as a string (options: ‘mnist’, ‘fashionmnist’, ‘cifar’, ‘cifar10’, ‘cifar100’, ‘imagenet’).

input_sizeint

Size of images in the dataset (pixels).

netstr or autogluon.space.Categorical

Which existing neural network models to consider as candidates.

optimizerstr or autogluon.space.AutoGluonObject

Which optimizers to consider as candidates for learning the neural network weights.

batch_sizeint

How many images to group in each mini-batch during gradient computations in training.

epochs: int

How many epochs to train the neural networks for at most.

final_fit_epochs: int, default None

Final fit epochs, the same number of epochs will be used as during the HPO if not specified.

metricstr or callable object

Evaluation metric by which predictions will be ulitmately evaluated on test data.

lossmxnet.gluon.loss

Loss function used during training of the neural network weights.

num_trialsint

Maximal number of hyperparameter configurations to try out.

time_limitsint

Approximately how long fit() should run for (wallclock time in seconds). fit() will stop training new models after this amount of time has elapsed (but models which have already started training will continue to completion).

split_ratiofloat, default = 0.8

Fraction of dataset to use for training (rest of data is held-out for tuning hyperparameters). The final returned model may be fit to all of the data (after hyperparameters have been selected).

nthreads_per_trialint

How many CPUs to use in each trial (ie. single training run of a model).

ngpus_per_trialint

How many GPUs to use in each trial (ie. single training run of a model).

output_directorystr

Checkpoints of the search state are written to os.path.join(output_directory, ‘exp1.ag’)

scheduler_optionsdict

Extra arguments passed to __init__ of scheduler, to configure the orchestration of training jobs during hyperparameter-tuning.

search_strategystr

Which hyperparameter search algorithm to use. Options include: ‘random’ (random search), ‘skopt’ (SKopt Bayesian optimization), ‘grid’ (grid search), ‘hyperband’ (Hyperband random), ‘rl’ (reinforcement learner).

search_optionsdict

Auxiliary keyword arguments to pass to the searcher that performs hyperparameter optimization.

resumebool

If True, the hyperparameter search is started from state loaded from os.path.join(output_directory, ‘exp1.ag’)

dist_ip_addrslist

List of IP addresses corresponding to remote workers, in order to leverage distributed computation.

verbosebool

Whether or not to print out intermediate information during training.

plot_resultsbool

Whether or not to generate plots summarizing training process.

visualizerstr

Describes method to visualize training progress during fit(). Options: [‘mxboard’, ‘tensorboard’, ‘none’].

auto_searchbool

If True, enables automatic suggestion of network types and hyper-parameter ranges adaptively based on provided dataset.

Returns
autogluon.task.image_classification.Classifier object which can make predictions on new data and summarize what happened during fit().

Examples

>>> from autogluon import ImageClassification as task
>>> dataset = task.Dataset(train_path='data/train',
>>>                        test_path='data/test')
>>> classifier = task.fit(dataset,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=time_limits,
>>>                       ngpus_per_trial=1,
>>>                       num_trials = 4)
>>> test_data = task.Dataset('~/data/test', train=False)
>>> test_acc = classifier.evaluate(test_data)

Bag of tricks are used on image classification dataset

ObjectDetection

class autogluon.task.ObjectDetection

AutoGluon Task for detecting and locating objects in images

Methods

Dataset(\*args, \*\*kwargs)

Dataset of images in which to detect objects.

fit([dataset, net, meta_arch, lr, loss, …])

Fit object detection models.

static Dataset(*args, **kwargs)

Dataset of images in which to detect objects.

static fit(dataset='voc', net=Categorical['mobilenet1.0'], meta_arch='yolo3', lr=Categorical[0.0005, 0.0001], loss=SoftmaxCrossEntropyLoss(batch_axis=0, w=None), split_ratio=0.8, batch_size=16, epochs=50, num_trials=None, time_limits=None, nthreads_per_trial=12, num_workers=32, ngpus_per_trial=1, hybridize=True, scheduler_options=None, search_strategy='random', search_options=None, verbose=False, transfer='coco', resume='', checkpoint='checkpoint/exp1.ag', visualizer='none', dist_ip_addrs=None, auto_search=True, seed=223, data_shape=416, start_epoch=0, lr_mode='step', lr_decay=0.1, lr_decay_period=0, lr_decay_epoch='160,180', warmup_lr=0.0, warmup_epochs=2, warmup_iters=1000, warmup_factor=0.3333333333333333, momentum=0.9, wd=0.0005, log_interval=100, save_prefix='', save_interval=10, val_interval=1, num_samples=-1, no_random_shape=False, no_wd=False, mixup=False, no_mixup_epochs=20, label_smooth=False, syncbn=False, reuse_pred_weights=True, **kwargs)

Fit object detection models.

Parameters
datasetstr or autogluon.task.ObjectDectection.Dataset

Training dataset containing images and corresponding object bounding boxes.

netstr, autogluon.space.AutoGluonObject

Which existing neural network base models to consider as candidates.

meta_archstr

Meta architecture of the model. Currently support YoloV3 (Default) and FasterRCNN. YoloV3 is faster, while FasterRCNN is more accurate.

lrfloat or autogluon.space

The learning rate to use in each update of the neural network weights during training.

lossmxnet.gluon.loss

Loss function used during training of the neural network weights.

split_ratiofloat

Fraction of dataset to hold-out during training in order to tune hyperparameters (i.e. validation data). The final returned model may be fit to all of the data (after hyperparameters have been selected).

batch_sizeint

How many images to group in each mini-batch during gradient computations in training.

epochsint

How many epochs to train the neural networks for at most.

num_trialsint

Maximal number of hyperparameter configurations to try out.

time_limitsint

Approximately how long should fit() should run for (wallclock time in seconds). fit() will stop training new models after this amount of time has elapsed (but models which have already started training will continue to completion).

nthreads_per_trialint

How many CPUs to use in each trial (ie. single training run of a model).

num_workersint

How many CPUs to use for data loading during training of a model.

ngpus_per_trialint

How many GPUs to use in each trial (ie. single training run of a model).

hybridizebool

Whether or not the MXNet neural network should be hybridized (for increased efficiency).

scheduler_optionsdict

Extra arguments passed to __init__ of scheduler, to configure the orchestration of training jobs during hyperparameter-tuning.

search_strategystr

Which hyperparameter search algorithm to use. Options include: ‘random’ (random search), ‘skopt’ (SKopt Bayesian optimization), ‘grid’ (grid search), ‘hyperband’ (Hyperband random), ‘rl’ (reinforcement learner).

search_optionsdict

Auxiliary keyword arguments to pass to the searcher that performs hyperparameter optimization.

verbosebool

Whether or not to print out intermediate information during training.

resumestr

Path to checkpoint file of existing model, from which model training should resume. If not empty, we also start the hyperparameter search from the state loaded from checkpoint.

checkpointstr or None

State of hyperparameter search is stored to this local file

visualizerstr

Describes method to visualize training progress during fit(). Options: [‘mxboard’, ‘tensorboard’, ‘none’].

dist_ip_addrslist

List of IP addresses corresponding to remote workers, in order to leverage distributed computation.

auto_searchbool

If True, enables automatic suggestion of network types and hyper-parameter ranges adaptively based on provided dataset.

seedint

Random seed to set for reproducibility.

data_shapeint

Shape of the image data.

start_epochint

Which epoch we begin training from (eg. if we resume training of an existing model, then this argument may be set to the number of epochs the model has already been trained for previously).

lr_modestr

What sort of learning rate schedule should be followed during training.

lr_decayfloat

How much learning rate should be decayed during training.

lr_decay_periodint

How often learning rate should be decayed during training.

warmup_lrfloat

Learning rate to use during warm up period at the start of training.

warmup_epochsint

How many initial epochs constitute the “warm up” period of model training.

warmup_itersint

How many initial iterations constitute the “warm up” period of model training. This is used by R-CNNs

warmup_factorfloat

warmup factor of target lr. initial lr starts from target lr * warmup_factor

momentumfloat or autogluon.space

Momentum to use in optimization of neural network weights during training.

wdfloat or autogluon.space

Weight decay to use in optimization of neural network weights during training.

log_intervalint

Log results every so many epochs during training.

save_prefixstr

Prefix to append to file name for saved model.

save_intervalint

Save a copy of model every so many epochs during training.

val_intervalint

Evaluate performance on held-out validation data every so many epochs during training.

no_random_shapebool

Whether random shapes should not be used.

no_wdbool

Whether weight decay should be turned off.

mixupbool

Whether or not to utilize mixup data augmentation strategy.

no_mixup_epochsint

If using mixup, we first train model for this many epochs without mixup data augmentation.

label_smoothbool

Whether or not to utilize label smoothing.

syncbnbool

Whether or not to utilize synchronized batch normalization.

Returns
autogluon.task.object_detection.Detector object which can make predictions on new data and summarize what happened during fit().

Examples

>>> from autogluon import ObjectDetection as task
>>> detector = task.fit(dataset = 'voc', net = 'mobilenet1.0',
>>>                     time_limits = 600, ngpus_per_trial = 1, num_trials = 1)

TextClassification

class autogluon.task.TextClassification

AutoGluon Task for classifying text snippets based on their content

Methods

Dataset(\*args, \*\*kwargs)

Dataset of text examples to make predictions for.

fit([dataset, net, pretrained_dataset, lr, …])

Fit neural networks on text dataset.

static Dataset(*args, **kwargs)

Dataset of text examples to make predictions for. See autogluon.task.TextClassification.get_dataset()

static fit(dataset='SST', net=Categorical['bert_12_768_12'], pretrained_dataset=Categorical['book_corpus_wiki_en_uncased', 'openwebtext_book_corpus_wiki_en_uncased'], lr=Real: lower=2e-05, upper=0.0002, warmup_ratio=0.01, lr_scheduler='cosine', log_interval=100, seed=0, batch_size=32, dev_batch_size=32, max_len=128, dtype='float32', epochs=3, epsilon=1e-06, accumulate=1, early_stop=False, nthreads_per_trial=4, ngpus_per_trial=1, hybridize=True, scheduler_options=None, search_strategy='random', search_options=None, num_trials=None, time_limits=None, resume=False, checkpoint='checkpoint/exp1.ag', visualizer='none', dist_ip_addrs=None, auto_search=True, verbose=False, **kwargs)

Fit neural networks on text dataset.

Parameters
datasetstr or autogluon.task.TextClassification.Dataset

The Training dataset. You can specify a string to use a popular built-in text dataset.

netstr or autogluon.space.Categorical

Which existing neural network models to consider as candidates.

pretrained_datasetstr, autogluon.space.Categorical

Which existing datasets to consider as candidates for transfer learning from.

lrfloat or autogluon.space

The learning rate to use in each update of the neural network weights during training.

warmup_ratiofloat

Ratio of overall training period considered as “warm up”.

lr_schedulerstr

Describes how learning rate should be adjusted over the course of training. Options include: ‘cosine’, ‘poly’.

log_intervalint

Log results every so many epochs during training.

seedint

Random seed to set for reproducibility.

batch_sizeint

How many examples to group in each mini-batch during gradient computations in training.

dev_batch_sizeint

How many examples to group in each mini-batch during performance evalatuion over validation dataset.

max_lenint

Maximum number of words in a single training example (i.e. one text snippet).

dtypestr

Dtype used to represent data fed to neural networks.

epochs: int

How many epochs to train the neural networks for at most.

epsilonfloat

Small number.

accumulateint

How often to accumulate losses.

early_stopbool

Whether to utilize early stopping during training to avoid overfitting.

num_trialsint

Maximal number of hyperparameter configurations to try out.

time_limitsint

Approximately how long should fit() should run for (wallclock time in seconds). fit() will stop training new models after this amount of time has elapsed (but models which have already started training will continue to completion).

nthreads_per_trialint

How many CPUs to use in each trial (ie. single training run of a model).

ngpus_per_trialint

How many GPUs to use in each trial (ie. single training run of a model).

hybridizebool

Whether or not the MXNet neural network should be hybridized (for increased efficiency).

scheduler_optionsdict

Extra arguments passed to __init__ of scheduler, to configure the orchestration of training jobs during hyperparameter-tuning.

search_strategystr

Which hyperparameter search algorithm to use. Options include: ‘random’ (random search), ‘skopt’ (SKopt Bayesian optimization), ‘grid’ (grid search), ‘hyperband’ (Hyperband random), ‘rl’ (reinforcement learner).

search_optionsdict

Auxiliary keyword arguments to pass to the searcher that performs hyperparameter optimization.

verbosebool

Whether or not to print out intermediate information during training.

checkpointstr or None

State of hyperparameter search is stored to this local file

resumebool

If True, the hyperparameter search is started from state loaded from checkpoint

visualizerstr

Describes method to visualize training progress during fit(). Options: [‘mxboard’, ‘tensorboard’, ‘none’].

dist_ip_addrslist

List of IP addresses corresponding to remote workers, in order to leverage distributed computation.

auto_searchbool

If True, enables automatic suggestion of network types and hyper-parameter ranges adaptively based on provided dataset.

Returns
autogluon.task.text_classification.TextClassificationPredictor object which can make predictions on new data and summarize what happened during fit().

Examples

>>> from autogluon import TextClassification as task
>>> dataset = task.Dataset(name='ToySST')
>>> predictor = task.fit(dataset)

Additional Tabular Prediction APIs

TabularPredictor

class autogluon.task.tabular_prediction.TabularPredictor(learner)

Object returned by fit() in Tabular Prediction tasks. Use for making predictions on new data and viewing information about models trained during fit().

Examples

>>> from autogluon import TabularPrediction as task
>>> train_data = task.Dataset(file_path='https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv')
>>> predictor = task.fit(train_data=train_data, label='class')
>>> results = predictor.fit_summary()
>>> test_data = task.Dataset(file_path='https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv')
>>> perf = predictor.evaluate(test_data)
Attributes
output_directorystr

Path to directory where all models used by this Predictor are stored.

problem_typestr

What type of prediction problem this Predictor has been trained for.

eval_metricfunction or str

What metric is used to evaluate predictive performance.

label_columnstr

Name of table column that contains data from the variable to predict (often referred to as: labels, response variable, target variable, dependent variable, Y, etc).

feature_typesautogluon.utils.tabular.features.feature_types_metadata.FeatureTypesMetadata

Inferred data type of each predictive variable after preprocessing transformation (i.e. column of training data table used to predict label_column). Contains both raw dtype and special dtype information. Each feature has exactly 1 raw dtype (such as ‘int’, ‘float’, ‘category’) and zero to many special dtypes (such as ‘datetime’, ‘text’, ‘text_ngram’). Special dtypes are AutoGluon specific feature types that are used to identify features with meaning beyond what the raw dtype can convey.

feature_types.get_feature_types_raw_flattened(): Dictionary of feature name -> raw dtype mappings. feature_types.feature_types_raw: Dictionary of lists of raw feature names, grouped by raw feature dtype. feature_types.feature_types_special: Dictionary of lists of special feature names, grouped by special feature dtype.

class_labelslist

For multiclass problems, this list contains the class labels in sorted order of predict_proba() output. For binary problems, this list contains the class labels in sorted order of predict_proba(as_multiclass=True) output.

class_labels[0] corresponds to internal label = 0 (negative class), class_labels[1] corresponds to internal label = 1 (positive class). This is relevant for certain metrics such as F1 where True and False labels impact the metric score differently.

For other problem types, will equal None. For example if pred = predict_proba(x, as_multiclass=True), then ith index of pred provides predicted probability that x belongs to class given by class_labels[i].

class_labels_internallist

For multiclass problems, this list contains the internal class labels in sorted order of internal predict_proba() output. For binary problems, this list contains the internal class labels in sorted order of internal predict_proba(as_multiclass=True) output.

The value will always be class_labels_internal=[0, 1] for binary problems, with 0 as the negative class, and 1 as the positive class.

For other problem types, will equal None.

class_labels_internal_mapdict

For binary and multiclass classification problems, this dictionary contains the mapping of the original labels to the internal labels. For example, in binary classification, label values of ‘True’ and ‘False’ will be mapped to the internal representation 1 and 0.

Therefore, class_labels_internal_map would equal {‘True’: 1, ‘False’: 0}

For other problem types, will equal None. For multiclass, it is possible for not all of the label values to have a mapping.

This indicates that the internal models will never predict those missing labels, and training rows associated with the missing labels were dropped.

Methods

delete_models(self[, models_to_keep, …])

Deletes models from predictor.

distill(self[, train_data, tuning_data, …])

Distill AutoGluon’s most accurate ensemble-predictor into single models which are simpler/faster and require less memory/compute.

evaluate(self, dataset[, silent])

Report the predictive performance evaluated for a given Dataset.

evaluate_predictions(self, y_true, y_pred[, …])

Evaluate the provided predictions against ground truth labels.

feature_importance(self[, dataset, model, …])

Calculates feature importance scores for the given model.

fit_summary(self[, verbosity])

Output summary of information about models produced during fit().

fit_weighted_ensemble(self, base_models[, …])

Fits new weighted ensemble models to combine predictions of previously-trained models.

get_model_best(self)

Returns the string model name of the best model by validation score.

get_model_full_dict(self)

Returns a dictionary of original model name -> refit full model name.

get_model_names(self)

Returns the list of model names trained in this predictor object.

info(self)

[EXPERIMENTAL] Returns a dictionary of predictor metadata.

leaderboard(self[, dataset, …])

Output summary of information about models produced during fit() as a pandas DataFrame.

load(output_directory[, verbosity])

Load a predictor object previously produced by fit() from file and returns this object.

load_data_internal(self[, dataset, …])

Loads the internal data representation used during model training.

predict(self, dataset[, model, as_pandas, …])

Use trained models to produce predicted labels (in classification) or response values (in regression).

predict_proba(self, dataset[, model, …])

Use trained models to produce predicted class probabilities rather than class-labels (if task is classification).

refit_full(self[, model])

Retrain model on all of the data (training + validation).

save(self)

Save this predictor to file in directory specified by this Predictor’s output_directory.

save_space(self[, remove_data, …])

Reduces the memory and disk size of predictor by deleting auxiliary model files that aren’t needed for prediction on new data.

transform_features(self[, dataset, model, …])

Transforms dataset features through the AutoGluon feature generator.

transform_labels(self, labels[, inverse, proba])

Transforms dataset labels to the internal label representation.

delete_models(self, models_to_keep=None, models_to_delete=None, allow_delete_cascade=False, delete_from_disk=True, dry_run=True)

Deletes models from predictor. This can be helpful to minimize memory usage and disk usage, particularly for model deployment. This will remove all references to the models in predictor.

For example, removed models will not appear in predictor.leaderboard().

WARNING: If delete_from_disk=True, this will DELETE ALL FILES in the deleted model directories, regardless if they were created by AutoGluon or not.

DO NOT STORE FILES INSIDE OF THE MODEL DIRECTORY THAT ARE UNRELATED TO AUTOGLUON.

Parameters
models_to_keepstr or list, default = None

Name of model or models to not delete. All models that are not specified and are also not required as a dependency of any model in models_to_keep will be deleted. Specify models_to_keep=’best’ to keep only the best model and its model dependencies. models_to_delete must be None if models_to_keep is set. To see the list of possible model names, use: predictor.get_model_names() or predictor.leaderboard().

models_to_deletestr or list, default = None

Name of model or models to delete. All models that are not specified but depend on a model in models_to_delete will also be deleted. models_to_keep must be None if models_to_delete is set.

allow_delete_cascadebool, default = False
If False, if unspecified dependent models of models in models_to_delete exist an exception will be raised instead of deletion occurring.

An example of a dependent model is m1 if m2 is a stacker model and takes predictions from m1 as inputs. In this case, m1 would be a dependent model of m2.

If True, all dependent models of models in models_to_delete will be deleted. Has no effect if models_to_delete=None.

delete_from_diskbool, default = True

If True, deletes the models from disk if they were persisted. WARNING: This deletes the entire directory for the deleted models, and ALL FILES located there.

It is highly recommended to first run with dry_run=True to understand which directories will be deleted.

dry_runbool, default = True

If True, then deletions don’t occur, and logging statements are printed describing what would have occurred. Set dry_run=False to perform the deletions.

distill(self, train_data=None, tuning_data=None, augmentation_data=None, time_limits=None, hyperparameters=None, holdout_frac=None, teacher_preds='soft', augment_method='spunge', augment_args={'size_factor': 5, 'max_size': 100000}, models_name_suffix=None, verbosity=None)

Distill AutoGluon’s most accurate ensemble-predictor into single models which are simpler/faster and require less memory/compute. Distillation can produce a model that is more accurate than the same model fit directly on the original training data. After calling distill(), there will be more models available in this Predictor, which can be evaluated using predictor.leaderboard(test_data) and deployed with: predictor.predict(test_data, model=MODEL_NAME). This will raise an exception if cache_data=False was previously set in task.fit().

NOTE: Until catboost v0.24 is released, distill() with CatBoost students in multiclass classification requires you to first install catboost-dev: pip install catboost-dev

Parameters
train_datastr or autogluon.task.tabular_prediction.TabularDataset or pandas.DataFrame, default = None

Same as train_data argument of autogluon.task.tabular_prediction.TabularPrediction.fit(). If None, the same training data will be loaded from fit() call used to produce this Predictor.

tuning_datastr or autogluon.task.tabular_prediction.TabularDataset or pandas.DataFrame, default = None

Same as tuning_data argument of autogluon.task.tabular_prediction.TabularPrediction.fit(). If tuning_data = None and train_data = None: the same training/validation splits will be loaded from fit() call used to produce this Predictor, unless bagging/stacking was previously used in which case a new training/validation split is performed.

augmentation_dataautogluon.task.tabular_prediction.TabularDataset or pandas.DataFrame, default = None

An optional extra dataset of unlabeled rows that can be used for augmenting the dataset used to fit student models during distillation (ignored if None).

time_limitsint, default = None

Approximately how long (in seconds) the distillation process should run for. If None, no time-constraint will be enforced allowing the distilled models to fully train.

hyperparametersdict or str, default = None

Specifies which models to use as students and what hyperparameter-values to use for them. Same as hyperparameters argument of autogluon.task.tabular_prediction.TabularPrediction.fit(). If = None, then student models will use the same hyperparameters from fit() used to produce this Predictor. Note: distillation is currently only supported for [‘GBM’,’NN’,’RF’,’CAT’] student models, other models and their hyperparameters are ignored here.

holdout_fracfloat

Same as holdout_frac argument of autogluon.task.tabular_prediction.TabularPrediction.fit().

teacher_predsstr, default = ‘soft’

What form of teacher predictions to distill from (teacher refers to the most accurate AutoGluon ensemble-predictor). If None, we only train with original labels (no data augmentation). If ‘hard’, labels are hard teacher predictions given by: teacher.predict() If ‘soft’, labels are soft teacher predictions given by: teacher.predict_proba() Note: ‘hard’ and ‘soft’ are equivalent for regression problems. If augment_method is not None, teacher predictions are only used to label augmented data (training data keeps original labels). To apply label-smoothing: teacher_preds=’onehot’ will use original training data labels converted to one-hot vectors for multiclass problems (no data augmentation).

augment_methodstr, default=’spunge’

Specifies method to use for generating augmented data for distilling student models. Options include:

None : no data augmentation performed. ‘munge’ : The MUNGE algorithm (https://www.cs.cornell.edu/~caruana/compression.kdd06.pdf). ‘spunge’ : A simpler, more efficient variant of the MUNGE algorithm.

augment_argsdict, default = {‘size_factor’:5, ‘max_size’: int(1e5)}
Contains the following kwargs that control the chosen augment_method (these are ignored if augment_method=None):

‘num_augmented_samples’: int, number of augmented datapoints used during distillation. Overrides ‘size_factor’, ‘max_size’ if specified. ‘max_size’: float, the maximum number of augmented datapoints to add (ignored if ‘num_augmented_samples’ specified). ‘size_factor’: float, if n = training data sample-size, we add int(n * size_factor) augmented datapoints, up to ‘max_size’. Larger values in augment_args will slow down the runtime of distill(), and may produce worse results if provided time_limits are too small. You can also pass in kwargs for the spunge_augment, munge_augment functions in autogluon/utils/tabular/ml/augmentation/distill_utils.py.

models_name_suffixstr, default = None

Optional suffix that can be appended at the end of all distilled student models’ names. Note: all distilled models will contain ‘_DSTL’ substring in their name by default.

verbosityint, default = None

Controls amount of printed output during distillation (4 = highest, 0 = lowest). Same as verbosity argument of autogluon.task.tabular_prediction.TabularPrediction.fit(). If None, the same verbosity used in previous fit is employed again.

Returns
List of names (str) corresponding to the distilled models.

Examples

>>> from autogluon import TabularPrediction as task
>>> train_data = task.Dataset('train.csv')
>>> predictor = task.fit(train_data=train_data, label='class', auto_stack=True, cache_data=True)  # predictor is in bagged mode and `cache_data=True`.
>>> distilled_model_names = predictor.distill()
>>> test_data = task.Dataset('test.csv')
>>> ldr = predictor.leaderboard(test_data)
>>> model_todeploy = distilled_model_names[0]
>>> predictor.predict(test_data, model=model_todeploy)
evaluate(self, dataset, silent=False)

Report the predictive performance evaluated for a given Dataset. This is basically a shortcut for: pred = predict(dataset); evaluate_predictions(dataset[label_column], preds, auxiliary_metrics=False) that automatically uses predict_proba() instead of predict() when appropriate.

Parameters
datasetstr or TabularDataset or pandas.DataFrame

This Dataset must also contain the label-column with the same column-name as specified during fit(). If str is passed, dataset will be loaded using the str value as the file path.

silentbool (optional)

Should performance results be printed?

Returns
Predictive performance value on the given dataset, based on the eval_metric used by this Predictor.
evaluate_predictions(self, y_true, y_pred, silent=False, auxiliary_metrics=False, detailed_report=True)

Evaluate the provided predictions against ground truth labels. Evaluation is based on the eval_metric previously specifed to fit(), or default metrics if none was specified.

Parameters
y_truelist or numpy.array

The ordered collection of ground-truth labels.

y_predlist or numpy.array

The ordered collection of predictions. Caution: For certain types of eval_metric (such as ‘roc_auc’), y_pred must be predicted-probabilities rather than predicted labels.

silentbool (optional)

Should performance results be printed?

auxiliary_metrics: bool (optional)

Should we compute other (problem_type specific) metrics in addition to the default metric?

detailed_reportbool (optional)

Should we computed more detailed versions of the auxiliary_metrics? (requires auxiliary_metrics = True)

Returns
Scalar performance value if auxiliary_metrics = False.
If auxiliary_metrics = True, returns dict where keys = metrics, values = performance along each metric.
feature_importance(self, dataset=None, model=None, features=None, feature_stage='original', subsample_size=1000, silent=False, **kwargs)

Calculates feature importance scores for the given model. A feature’s importance score represents the performance drop that results when the model makes predictions on a perturbed copy of the dataset where this feature’s values have been randomly shuffled across rows. A feature score of 0.01 would indicate that the predictive performance dropped by 0.01 when the feature was randomly shuffled. The higher the score a feature has, the more important it is to the model’s performance. If a feature has a negative score, this means that the feature is likely harmful to the final model, and a model trained with the feature removed would be expected to achieve a better predictive performance. Note that calculating feature importance can be a very computationally expensive process, particularly if the model uses hundreds or thousands of features. In many cases, this can take longer than the original model training. To estimate how long feature_importance(model, dataset, features) will take, it is roughly the time taken by predict_proba(dataset, model) multiplied by the number of features.

Parameters
datasetstr or TabularDataset or pandas.DataFrame (optional)

This dataset must also contain the label-column with the same column-name as specified during fit(). If specified, then the dataset is used to calculate the feature importance scores. If str is passed, dataset will be loaded using the str value as the file path. If not specified, the original dataset used during fit() will be used if cache_data=True. Otherwise, an exception will be raised. Do not pass the training data through this argument, as the feature importance scores calculated will be biased due to overfitting.

More accurate feature importances will be obtained from new data that was held-out during fit().

modelstr, default = None

Model to get feature importances for, if None the best model is chosen. Valid models are listed in this predictor by calling predictor.get_model_names()

featureslist, default = None

List of str feature names that feature importances are calculated for and returned, specify None to get all feature importances. If you only want to compute feature importances for some of the features, you can pass their names in as a list of str. Valid feature names change depending on the feature_stage.

To get the list of feature names for feature_stage=’transformed’, call list(predictor.transform_features().columns). To get the list of feature names for feature_stage=`transformed_model, call list(predictor.transform_features(model={model_name}).columns).

feature_stagestr, default = ‘original’

What stage of feature-processing should importances be computed for. Options:

‘original’:

Compute importances of the original features. Warning: dataset must be specified with this option, otherwise an exception will be raised.

‘transformed’:

Compute importances of the post-internal-transformation features (after automated feature engineering). These features may be missing some original features, or add new features entirely. An example of new features would be ngram features generated from a text column. Warning: For bagged models, feature importance calculation is not yet supported with this option when dataset=None. Doing so will raise an exception.

‘transformed_model’:

Compute importances of the post-model-transformation features. These features are the internal features used by the requested model. They may differ greatly from the original features. If the model is a stack ensemble, this will include stack ensemble features such as the prediction probability features of the stack ensemble’s base (ancestor) models.

subsample_sizeint, default = 1000

The number of rows to sample from dataset when computing feature importance. If subsample_size=None or dataset contains fewer than subsample_size rows, all rows will be used during computation. Larger values increase the accuracy of the feature importance scores. Runtime linearly scales with subsample_size.

silentbool, default = False

Whether to suppress logging output

Returns
Pandas pandas.Series of feature importance scores.
fit_summary(self, verbosity=3)

Output summary of information about models produced during fit(). May create various generated summary plots and store them in folder: Predictor.output_directory.

Parameters
verbosityint, default = 3

Controls how detailed of a summary to ouput. Set <= 0 for no output printing, 1 to print just high-level summary, 2 to print summary and create plots, >= 3 to print all information produced during fit().

Returns
Dict containing various detailed information. We do not recommend directly printing this dict as it may be very large.
fit_weighted_ensemble(self, base_models: list = None, name_suffix='_custom', expand_pareto_frontier=False, time_limits=None)

Fits new weighted ensemble models to combine predictions of previously-trained models. cache_data must have been set to True during the original training to enable this functionality.

Parameters
base_modelslist, default = None

List of model names the weighted ensemble can consider as candidates. If None, all previously trained models are considered except for weighted ensemble models. As an example, to train a weighted ensemble that can only have weights assigned to the models ‘model_a’ and ‘model_b’, set base_models=[‘model_a’, ‘model_b’]

name_suffixstr, default = ‘_custom’

Name suffix to add to the name of the newly fitted ensemble model. Warning: If the name of a trained model from this function is identical to an existing model, it will overwrite the existing model. Ensure that name_suffix is unique each time fit_weighted_ensemble is called to avoid this.

expand_pareto_frontierbool, default = False

If True, will train N-1 weighted ensemble models instead of 1, where N=len(base_models). The final model trained when True is equivalent to the model trained when False. These weighted ensemble models will attempt to expand the pareto frontier. This will create many different weighted ensembles which have different accuracy/memory/inference-speed trade-offs. This is particularly useful when inference speed is an important consideration.

time_limitsint, default = None

Time in seconds each weighted ensemble model is allowed to train for. If expand_pareto_frontier=True, the time_limits value is applied to each model. If None, the ensemble models train without time restriction.

Returns
List of newly trained weighted ensemble model names.
If an exception is encountered while training an ensemble model, that model’s name will be absent from the list.
get_model_best(self)

Returns the string model name of the best model by validation score. This is typically the same model used during inference when predictor.predict is called without specifying a model.

Returns
String model name of the best model
get_model_full_dict(self)

Returns a dictionary of original model name -> refit full model name. Empty unless refit_full=True was set during fit or predictor.refit_full() was called. This can be useful when determining the best model based off of predictor.leaderboard(), then getting the _FULL version of the model by passing its name as the key to this dictionary.

Returns
Dictionary of original model name -> refit full model name.
get_model_names(self)

Returns the list of model names trained in this predictor object.

info(self)

[EXPERIMENTAL] Returns a dictionary of predictor metadata. Warning: This functionality is currently in preview mode.

The metadata information returned may change in structure in future versions without warning. The definitions of various metadata values are not yet documented. The output of this function should not be used for programmatic decisions.

Contains information such as row count, column count, model training time, validation scores, hyperparameters, and much more.

Returns
Dictionary of predictor metadata.
leaderboard(self, dataset=None, only_pareto_frontier=False, silent=False)

Output summary of information about models produced during fit() as a pandas DataFrame. Includes information on test and validation scores for all models, model training times, inference times, and stack levels. Output DataFrame columns include:

‘model’: The name of the model. ‘score_val’: The validation score of the model on the ‘eval_metric’. ‘pred_time_val’: The inference time required to compute predictions on the validation data end-to-end.

Equivalent to the sum of all ‘pred_time_val_marginal’ values for the model and all of its base models.

‘fit_time’: The fit time required to train the model end-to-end (Including base models if the model is a stack ensemble).

Equivalent to the sum of all ‘fit_time_marginal’ values for the model and all of its base models.

‘pred_time_val_marginal’: The inference time required to compute predictions on the validation data (Ignoring inference times for base models).

Note that this ignores the time required to load the model into memory when bagging is disabled.

‘fit_time_marginal’: The fit time required to train the model (Ignoring base models). ‘stack_level’: The stack level of the model.

A model with stack level N can take any set of models with stack level less than N as input, with stack level 0 models having no model inputs.

Parameters
datasetstr or TabularDataset or pandas.DataFrame (optional)

This Dataset must also contain the label-column with the same column-name as specified during fit(). If specified, then the leaderboard returned will contain additional columns ‘score_test’, ‘pred_time_test’, and ‘pred_time_test_marginal’.

‘score_test’: The score of the model on the ‘eval_metric’ for the dataset provided. ‘pred_time_test’: The true end-to-end wall-clock inference time of the model for the dataset provided.

Equivalent to the sum of all ‘pred_time_test_marginal’ values for the model and all of its base models.

‘pred_time_test_marginal’: The inference time of the model for the dataset provided, minus the inference time for the model’s base models, if it has any.

Note that this ignores the time required to load the model into memory when bagging is disabled.

If str is passed, dataset will be loaded using the str value as the file path.

only_pareto_frontierbool (optional)

If True, only return model information of models in the Pareto frontier of the accuracy/latency trade-off (models which achieve the highest score within their end-to-end inference time). At minimum this will include the model with the highest score and the model with the lowest inference time. This is useful when deciding which model to use during inference if inference time is a consideration. Models filtered out by this process would never be optimal choices for a user that only cares about model inference time and score.

silentbool (optional)

Should leaderboard DataFrame be printed?

Returns
Pandas pandas.DataFrame of model performance summary information.
classmethod load(output_directory, verbosity=2)

Load a predictor object previously produced by fit() from file and returns this object. It is highly recommended the predictor be loaded with the exact AutoGluon version it was fit with. Is functionally equivalent to autogluon.task.tabular_prediction.TabularPrediction.load().

Parameters
output_directorystr

Path to directory where trained models are stored (i.e. the output_directory specified in previous call to fit()).

verbosityint, default = 2

Verbosity levels range from 0 to 4 and control how much information is generally printed by this Predictor. Higher levels correspond to more detailed print statements (you can set verbosity = 0 to suppress warnings). If using logging, you can alternatively control amount of information printed via logger.setLevel(L), where L ranges from 0 to 50 (Note: higher values L correspond to fewer print statements, opposite of verbosity levels)

Returns
TabularPredictor object
load_data_internal(self, dataset='train', return_X=True, return_y=True)

Loads the internal data representation used during model training. Individual AutoGluon models like the neural network may apply additional feature transformations that are not reflected in this method. This method only applies universal transforms employed by all AutoGluon models. This will raise an exception if cache_data=False was previously set in task.fit(). Warning, the internal representation may:

Have different features compared to the original data. Have different row counts compared to the original data. Have indices which do not align with the original data. Have label values which differ from those in the original data.

Internal data representations should NOT be combined with the original data, in most cases this is not possible.

Parameters
datasetstr, default = ‘train’

The dataset to load. Valid values are:

‘train’:

Load the training data used during model training. This is a transformed and augmented version of the train_data passed in task.fit().

‘val’:

Load the validation data used during model training. This is a transformed and augmented version of the tuning_data passed in task.fit(). If tuning_data=None was set in task.fit(), then tuning_data is an automatically generated validation set created by splitting train_data. Warning: Will raise an exception if called by a bagged predictor, as bagged predictors have no validation data.

return_Xbool, default = True

Whether to return the internal data features If set to False, then the first element in the returned tuple will be None.

return_ybool, default = True

Whether to return the internal data labels If set to False, then the second element in the returned tuple will be None.

Returns
Tuple of (pandas.DataFrame, pandas.Series) corresponding to the internal data features and internal data labels, respectively.
predict(self, dataset, model=None, as_pandas=False, use_pred_cache=False, add_to_pred_cache=False)

Use trained models to produce predicted labels (in classification) or response values (in regression).

Parameters
datasetstr or TabularDataset or pandas.DataFrame

The dataset to make predictions for. Should contain same column names as training Dataset and follow same format (may contain extra columns that won’t be used by Predictor, including the label-column itself). If str is passed, dataset will be loaded using the str value as the file path.

modelstr (optional)

The name of the model to get predictions from. Defaults to None, which uses the highest scoring model on the validation set. Valid models are listed in this predictor by calling predictor.get_model_names()

as_pandasbool (optional)

Whether to return the output as a pandas Series (True) or numpy array (False)

use_pred_cachebool (optional)

Whether to used previously-cached predictions for table rows we have already predicted on before (can speedup repeated runs of predict() on multiple datasets with overlapping rows between them).

add_to_pred_cachebool (optional)

Whether these predictions should be cached for reuse in future predict() calls on the same table rows (can speedup repeated runs of predict() on multiple datasets with overlapping rows between them).

Returns
Array of predictions, one corresponding to each row in given dataset. Either numpy Ndarray or pandas Series depending on as_pandas argument.
predict_proba(self, dataset, model=None, as_pandas=False, as_multiclass=False)

Use trained models to produce predicted class probabilities rather than class-labels (if task is classification). If predictor.problem_type is regression, this functions identically to predict, returning the same output.

Parameters
datasetstr or TabularDataset or pandas.DataFrame

The dataset to make predictions for. Should contain same column names as training Dataset and follow same format (may contain extra columns that won’t be used by Predictor, including the label-column itself). If str is passed, dataset will be loaded using the str value as the file path.

modelstr (optional)

The name of the model to get prediction probabilities from. Defaults to None, which uses the highest scoring model on the validation set. Valid models are listed in this predictor by calling predictor.get_model_names()

as_pandasbool (optional)

Whether to return the output as a pandas object (True) or numpy array (False). Pandas object is a DataFrame if this is a multiclass problem or as_multiclass=True, otherwise it is a Series. If the output is a DataFrame, the column order will be equivalent to predictor.class_labels.

as_multiclassbool (optional)
Whether to return binary classification probabilities as if they were for multiclass classification.

Output will contain two columns, and if as_pandas=True, the column names will correspond to the binary class labels. The columns will be the same order as predictor.class_labels.

Only impacts output for binary classification problems.

Returns
Array of predicted class-probabilities, corresponding to each row in the given dataset.
May be a numpy ndarray or pandas Series/DataFrame depending on as_pandas and as_multiclass arguments and the type of prediction problem.
For binary classification problems, the output contains for each datapoint only the predicted probability of the positive class, unless you specify as_multiclass=True.
refit_full(self, model='all')

Retrain model on all of the data (training + validation). For bagged models:

Optimizes a model’s inference time by collapsing bagged ensembles into a single model fit on all of the training data. This process will typically result in a slight accuracy reduction and a large inference speedup. The inference speedup will generally be between 10-200x faster than the original bagged ensemble model.

The inference speedup factor is equivalent to (k * n), where k is the number of folds (num_bagging_folds) and n is the number of finished repeats (num_bagging_sets) in the bagged ensemble.

The runtime is generally 10% or less of the original fit runtime.

The runtime can be roughly estimated as 1 / (k * n) of the original fit runtime, with k and n defined above.

For non-bagged models:

Optimizes a model’s accuracy by retraining on 100% of the data without using a validation set. Will typically result in a slight accuracy increase and no change to inference time. The runtime will be approximately equal to the original fit runtime.

This process does not alter the original models, but instead adds additional models. If stacker models are refit by this process, they will use the refit_full versions of the ancestor models during inference. Models produced by this process will not have validation scores, as they use all of the data for training.

Therefore, it is up to the user to determine if the models are of sufficient quality by including test data in predictor.leaderboard(dataset=test_data). If the user does not have additional test data, they should reference the original model’s score for an estimate of the performance of the refit_full model.

Warning: Be aware that utilizing refit_full models without separately verifying on test data means that the model is untested, and has no guarantee of being consistent with the original model.

cache_data must have been set to True during the original training to enable this functionality.

Parameters
modelstr, default = ‘all’
Model name of model to refit.

If ‘all’ then all models are refitted. If ‘best’ then the model with the highest validation score is refit.

All ancestor models will also be refit in the case that the selected model is a weighted or stacker ensemble. Valid models are listed in this predictor by calling predictor.get_model_names().

Returns
Dictionary of original model names -> refit_full model names.
save(self)

Save this predictor to file in directory specified by this Predictor’s output_directory. Note that fit() already saves the predictor object automatically (we do not recommend modifying the Predictor object yourself as it tracks many trained models).

save_space(self, remove_data=True, remove_fit_stack=True, requires_save=True, reduce_children=False)

Reduces the memory and disk size of predictor by deleting auxiliary model files that aren’t needed for prediction on new data. This function has NO impact on inference accuracy. It is recommended to invoke this method if the only goal is to use the trained model for prediction. However, certain advanced functionality may no longer be available after save_space() has been called.

Parameters
remove_databool, default = True

Whether to remove cached files of the original training and validation data. Only reduces disk usage, it has no impact on memory usage. This is especially useful when the original data was large. This is equivalent to setting cache_data=False during the original fit().

Will disable all advanced functionality that requires cache_data=True.

remove_fit_stackbool, default = True

Whether to remove information required to fit new stacking models and continue fitting bagged models with new folds. Only reduces disk usage, it has no impact on memory usage. This includes:

out-of-fold (OOF) predictions

This is useful for multiclass problems with many classes, as OOF predictions can become very large on disk. (1 GB per model in extreme cases) This disables predictor.refit_full() for stacker models.

requires_savebool, default = True

Whether to remove information that requires the model to be saved again to disk. Typically this only includes flag variables that don’t have significant impact on memory or disk usage, but should technically be updated due to the removal of more important information.

An example is the is_data_saved boolean variable in trainer, which should be updated to False if remove_data=True was set.

reduce_childrenbool, default = False

Whether to apply the reduction rules to bagged ensemble children models. These are the models trained for each fold of the bagged ensemble. This should generally be kept as False since the most important memory and disk reduction techniques are automatically applied to these models during the original fit() call.

transform_features(self, dataset=None, model=None, base_models=None, return_original_features=True)

Transforms dataset features through the AutoGluon feature generator. This is useful to gain an understanding of how AutoGluon interprets the dataset features. The output of this function can be used to train further models, even outside of AutoGluon. This can be useful for training your own models on the same data representation as AutoGluon. Individual AutoGluon models like the neural network may apply additional feature transformations that are not reflected in this method. This method only applies universal transforms employed by all AutoGluon models. When dataset=None, `base_models=[{best_model}], and bagging was enabled during fit():

This returns the out-of-fold predictions of the best model, which can be used as training input to a custom user stacker model.

Parameters
datasetstr or TabularDataset or pandas.DataFrame (optional)

The dataset to apply feature transformation to. This dataset does not require the label column. If str is passed, dataset will be loaded using the str value as the file path. If not specified, the original dataset used during fit() will be used if fit() was previously called with cache_data=True. Otherwise, an exception will be raised.

For non-bagged mode predictors:

The dataset used when not specified is the validation set. This can either be an automatically generated validation set or the user-defined tuning_data if passed during fit(). If all parameters are unspecified, then the output is equivalent to predictor.load_data_internal(dataset=’val’, return_X=True, return_y=False)[0]. To get the label values of the output, call predictor.load_data_internal(dataset=’val’, return_X=False, return_y=True)[1]. If the original training set is desired, it can be passed in through dataset.

Warning: Do not pass the original training set if model or base_models are set. This will result in overfit feature transformation.

For bagged mode predictors:

The dataset used when not specified is the full training set. If all parameters are unspecified, then the output is equivalent to predictor.load_data_internal(dataset=’train’, return_X=True, return_y=False)[0]. To get the label values of the output, call predictor.load_data_internal(dataset=’train’, return_X=False, return_y=True)[1]. base_model features generated in this instance will be from out-of-fold predictions. Note that the training set may differ from the training set originally passed during fit(), as AutoGluon may choose to drop or duplicate rows during training. Warning: Do not pass the original training set through dataset if model or base_models are set. This will result in overfit feature transformation. Instead set dataset=None.

modelstr, default = None

Model to generate input features for. The output data will be equivalent to the input data that would be sent into model.predict_proba(data).

Note: This only applies to cases where dataset is not the training data.

If None, then only return generically preprocessed features prior to any model fitting. Valid models are listed in this predictor by calling predictor.get_model_names(). Specifying a refit_full model will cause an exception if dataset=None. base_models=None is a requirement when specifying model.

base_modelslist, default = None

List of model names to use as base_models for a hypothetical stacker model when generating input features. If None, then only return generically preprocessed features prior to any model fitting. Valid models are listed in this predictor by calling predictor.get_model_names(). If a stacker model S exists with base_models=M, then setting base_models=M is equivalent to setting model=S. model=None is a requirement when specifying base_models.

return_original_featuresbool, default = True

Whether to return the original features. If False, only returns the additional output columns from specifying model or base_models.

This is useful to set to False if the intent is to use the output as input to further stacker models without the original features.

Returns
Pandas pandas.DataFrame of the provided dataset after feature transformation has been applied.
This output does not include the label column, and will remove it if present in the supplied dataset.
If a transformed label column is desired, use predictor.transform_labels.

Examples

>>> from autogluon import TabularPrediction as task
>>> train_data = task.Dataset('train.csv')
>>> predictor = task.fit(train_data=train_data, label='class', auto_stack=True, cache_data=True)  # predictor is in bagged mode and `cache_data=True`.
>>> model = 'weighted_ensemble_k0_l1'
>>> test_data = task.Dataset('test.csv')
>>> train_data_transformed = predictor.transform_features(model=model)  # Internal training DataFrame used as input to `model.fit()` during `predictor = task.fit(train_data=train_data, ...)`
>>> test_data_transformed = predictor.transform_features(dataset=test_data, model=model)  # Internal test DataFrame used as input to `model.predict_proba()` during `predictor.predict_proba(test_data, model=model)`
transform_labels(self, labels, inverse=False, proba=False)

Transforms dataset labels to the internal label representation. This can be useful for training your own models on the same data label representation as AutoGluon. Regression problems do not differ between original and internal representation, and thus this method will return the provided labels. Warning: When inverse=False, it is possible for the output to contain NaN label values in multiclass problems if the provided label was dropped during training.

Parameters
labelsnumpy.ndarray or pandas.Series

Labels to transform. If proba=False, an example input would be the output of predictor.predict(test_data). If proba=True, an example input would be the output of predictor.predict_proba(test_data).

inverseboolean, default = False

When True, the input labels are treated as being in the internal representation and the original representation is outputted.

probaboolean, default = False
When True, the input labels are treated as probabilities and the output will be the internal representation of probabilities.

In this case, it is expected that labels be a numpy.ndarray. If the problem_type is multiclass:

The input column order must be equal to predictor.class_labels. The output column order will be equal to predictor.class_labels_internal. if inverse=True, the same logic applies, but with input and output columns interchanged.

When False, the input labels are treated as actual labels and the output will be the internal representation of the labels.

In this case, it is expected that labels be a pandas.Series or numpy.ndarray.

Returns
Pandas pandas.Series of labels if proba=False or Numpy numpy.ndarray of label probabilities if proba=True

TabularDataset

class autogluon.task.tabular_prediction.TabularDataset(*args, **kwargs)

A dataset in tabular format (with rows = samples, columns = features/variables). This object is essentially a pandas DataFrame (with some extra attributes) and all existing pandas methods can be applied to it. For full list of methods/attributes, see pandas Dataframe documentation: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html

Parameters
file_pathstr (optional)

Path to the data file (may be on local filesystem or URL to cloud s3 bucket). At least one of file_path and df arguments must be specified when constructing a new TabularDataset.

dfpandas.DataFrame (optional)

If you already have your data in a pandas Dataframe, you can directly provide it by specifying df. At least one of file_path and df arguments must be specified when constructing new TabularDataset.

feature_typesdict (optional)

Mapping from column_names to string describing data type of each column. If not specified, AutoGluon’s fit() will automatically infer what type of data each feature contains.

subsampleint (optional)

If specified = k, we only keep first k rows of the provided dataset.

namestr (optional)

Optional name to assign to dataset (has no effect beyond being accessible via TabularDataset.name).

copybool (optional, default=False)

If True and df is passed, then df will be deep copied, resulting in two instances of the provided data in memory. If False, the original df and the new TabularDataset will share the same underlying data. Set copy=True if you don’t want AutoGluon to be able to modify the original DataFrame during it’s training process (and your machine has enough memory).

Examples

>>> from autogluon import TabularPrediction as task  # Note: TabularPrediction.Dataset == TabularDataset.
>>> train_data = task.Dataset(file_path='https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv')
>>> test_data = task.Dataset(file_path='https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv')
>>> train_data.head(30)
>>> train_data.columns
Attributes
name: (str)

An optional name assigned to this TabularDataset.

file_path: (str)

Path to data file from which this TabularDataset was created.

feature_types: (dict)

Maps column-names to string describing the data type of each column in this TabularDataset.

subsample: (int)

Describes size of subsample retained in this TabularDataset (None if this is original dataset).

Note: In addition to these attributes, `TabularDataset` also shares all the same attributes and methods of a pandas Dataframe.
For detailed list, see: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html

Methods

abs(self)

Return a Series/DataFrame with absolute numeric value of each element.

add(self, other[, axis, level, fill_value])

Get Addition of dataframe and other, element-wise (binary operator add).

add_prefix(self, prefix)

Prefix labels with string prefix.

add_suffix(self, suffix)

Suffix labels with string suffix.

agg(self, func[, axis])

Aggregate using one or more operations over the specified axis.

aggregate(self, func[, axis])

Aggregate using one or more operations over the specified axis.

align(self, other[, join, axis, level, …])

Align two objects on their axes with the specified join method for each axis Index.

all(self[, axis, bool_only, skipna, level])

Return whether all elements are True, potentially over an axis.

any(self[, axis, bool_only, skipna, level])

Return whether any element is True, potentially over an axis.

append(self, other[, ignore_index, …])

Append rows of other to the end of caller, returning a new object.

apply(self, func[, axis, broadcast, raw, …])

Apply a function along an axis of the DataFrame.

applymap(self, func)

Apply a function to a Dataframe elementwise.

as_blocks(self[, copy])

Convert the frame to a dict of dtype -> Constructor Types that each has a homogeneous dtype.

as_matrix(self[, columns])

Convert the frame to its Numpy-array representation.

asfreq(self, freq[, method, how, normalize, …])

Convert TimeSeries to specified frequency.

asof(self, where[, subset])

Return the last row(s) without any NaNs before where.

assign(self, \*\*kwargs)

Assign new columns to a DataFrame.

astype(self, dtype[, copy, errors])

Cast a pandas object to a specified dtype dtype.

at_time(self, time[, asof, axis])

Select values at particular time of day (e.g.

between_time(self, start_time, end_time[, …])

Select values between particular times of the day (e.g., 9:00-9:30 AM).

bfill(self[, axis, inplace, limit, downcast])

Synonym for DataFrame.fillna() with method='bfill'.

bool(self)

Return the bool of a single element PandasObject.

boxplot(self[, column, by, ax, fontsize, …])

Make a box plot from DataFrame columns.

clip(self[, lower, upper, axis, inplace])

Trim values at input threshold(s).

clip_lower(self, threshold[, axis, inplace])

Trim values below a given threshold.

clip_upper(self, threshold[, axis, inplace])

Trim values above a given threshold.

combine(self, other, func[, fill_value, …])

Perform column-wise combine with another DataFrame.

combine_first(self, other)

Update null elements with value in the same location in other.

compound(self[, axis, skipna, level])

Return the compound percentage of the values for the requested axis.

copy(self[, deep])

Make a copy of this object’s indices and data.

corr(self[, method, min_periods])

Compute pairwise correlation of columns, excluding NA/null values.

corrwith(self, other[, axis, drop, method])

Compute pairwise correlation between rows or columns of DataFrame with rows or columns of Series or DataFrame.

count(self[, axis, level, numeric_only])

Count non-NA cells for each column or row.

cov(self[, min_periods])

Compute pairwise covariance of columns, excluding NA/null values.

cummax(self[, axis, skipna])

Return cumulative maximum over a DataFrame or Series axis.

cummin(self[, axis, skipna])

Return cumulative minimum over a DataFrame or Series axis.

cumprod(self[, axis, skipna])

Return cumulative product over a DataFrame or Series axis.

cumsum(self[, axis, skipna])

Return cumulative sum over a DataFrame or Series axis.

describe(self[, percentiles, include, exclude])

Generate descriptive statistics that summarize the central tendency, dispersion and shape of a dataset’s distribution, excluding NaN values.

diff(self[, periods, axis])

First discrete difference of element.

div(self, other[, axis, level, fill_value])

Get Floating division of dataframe and other, element-wise (binary operator truediv).

divide(self, other[, axis, level, fill_value])

Get Floating division of dataframe and other, element-wise (binary operator truediv).

dot(self, other)

Compute the matrix multiplication between the DataFrame and other.

drop(self[, labels, axis, index, columns, …])

Drop specified labels from rows or columns.

drop_duplicates(self[, subset, keep, inplace])

Return DataFrame with duplicate rows removed, optionally only considering certain columns.

droplevel(self, level[, axis])

Return DataFrame with requested index / column level(s) removed.

dropna(self[, axis, how, thresh, subset, …])

Remove missing values.

duplicated(self[, subset, keep])

Return boolean Series denoting duplicate rows, optionally only considering certain columns.

eq(self, other[, axis, level])

Get Equal to of dataframe and other, element-wise (binary operator eq).

equals(self, other)

Test whether two objects contain the same elements.

eval(self, expr[, inplace])

Evaluate a string describing operations on DataFrame columns.

ewm(self[, com, span, halflife, alpha, …])

Provide exponential weighted functions.

expanding(self[, min_periods, center, axis])

Provide expanding transformations.

explode(self, column, Tuple])

Transform each element of a list-like to a row, replicating the index values.

ffill(self[, axis, inplace, limit, downcast])

Synonym for DataFrame.fillna() with method='ffill'.

fillna(self[, value, method, axis, inplace, …])

Fill NA/NaN values using the specified method.

filter(self[, items, like, regex, axis])

Subset rows or columns of dataframe according to labels in the specified index.

first(self, offset)

Convenience method for subsetting initial periods of time series data based on a date offset.

first_valid_index(self)

Return index for first non-NA/null value.

floordiv(self, other[, axis, level, fill_value])

Get Integer division of dataframe and other, element-wise (binary operator floordiv).

from_dict(data[, orient, dtype, columns])

Construct DataFrame from dict of array-like or dicts.

from_items(items[, columns, orient])

Construct a DataFrame from a list of tuples.

from_records(data[, index, exclude, …])

Convert structured or record ndarray to DataFrame.

ge(self, other[, axis, level])

Get Greater than or equal to of dataframe and other, element-wise (binary operator ge).

get(self, key[, default])

Get item from object for given key (ex: DataFrame column).

get_dtype_counts(self)

Return counts of unique dtypes in this object.

get_ftype_counts(self)

Return counts of unique ftypes in this object.

get_value(self, index, col[, takeable])

Quickly retrieve single value at passed column and index.

get_values(self)

Return an ndarray after converting sparse values to dense.

groupby(self[, by, axis, level, as_index, …])

Group DataFrame or Series using a mapper or by a Series of columns.

gt(self, other[, axis, level])

Get Greater than of dataframe and other, element-wise (binary operator gt).

head(self[, n])

Return the first n rows.

hist(data[, column, by, grid, xlabelsize, …])

Make a histogram of the DataFrame’s.

idxmax(self[, axis, skipna])

Return index of first occurrence of maximum over requested axis.

idxmin(self[, axis, skipna])

Return index of first occurrence of minimum over requested axis.

infer_objects(self)

Attempt to infer better dtypes for object columns.

info(self[, verbose, buf, max_cols, …])

Print a concise summary of a DataFrame.

insert(self, loc, column, value[, …])

Insert column into DataFrame at specified location.

interpolate(self[, method, axis, limit, …])

Interpolate values according to different methods.

isin(self, values)

Whether each element in the DataFrame is contained in values.

isna(self)

Detect missing values.

isnull(self)

Detect missing values.

items(self)

Iterator over (column name, Series) pairs.

iteritems(self)

Iterator over (column name, Series) pairs.

iterrows(self)

Iterate over DataFrame rows as (index, Series) pairs.

itertuples(self[, index, name])

Iterate over DataFrame rows as namedtuples.

join(self, other[, on, how, lsuffix, …])

Join columns of another DataFrame.

keys(self)

Get the ‘info axis’ (see Indexing for more)

kurt(self[, axis, skipna, level, numeric_only])

Return unbiased kurtosis over requested axis using Fisher’s definition of kurtosis (kurtosis of normal == 0.0).

kurtosis(self[, axis, skipna, level, …])

Return unbiased kurtosis over requested axis using Fisher’s definition of kurtosis (kurtosis of normal == 0.0).

last(self, offset)

Convenience method for subsetting final periods of time series data based on a date offset.

last_valid_index(self)

Return index for last non-NA/null value.

le(self, other[, axis, level])

Get Less than or equal to of dataframe and other, element-wise (binary operator le).

lookup(self, row_labels, col_labels)

Label-based “fancy indexing” function for DataFrame.

lt(self, other[, axis, level])

Get Less than of dataframe and other, element-wise (binary operator lt).

mad(self[, axis, skipna, level])

Return the mean absolute deviation of the values for the requested axis.

mask(self, cond[, other, inplace, axis, …])

Replace values where the condition is True.

max(self[, axis, skipna, level, numeric_only])

Return the maximum of the values for the requested axis.

mean(self[, axis, skipna, level, numeric_only])

Return the mean of the values for the requested axis.

median(self[, axis, skipna, level, numeric_only])

Return the median of the values for the requested axis.

melt(self[, id_vars, value_vars, var_name, …])

Unpivot a DataFrame from wide format to long format, optionally leaving identifier variables set.

memory_usage(self[, index, deep])

Return the memory usage of each column in bytes.

merge(self, right[, how, on, left_on, …])

Merge DataFrame or named Series objects with a database-style join.

min(self[, axis, skipna, level, numeric_only])

Return the minimum of the values for the requested axis.

mod(self, other[, axis, level, fill_value])

Get Modulo of dataframe and other, element-wise (binary operator mod).

mode(self[, axis, numeric_only, dropna])

Get the mode(s) of each element along the selected axis.

mul(self, other[, axis, level, fill_value])

Get Multiplication of dataframe and other, element-wise (binary operator mul).

multiply(self, other[, axis, level, fill_value])

Get Multiplication of dataframe and other, element-wise (binary operator mul).

ne(self, other[, axis, level])

Get Not equal to of dataframe and other, element-wise (binary operator ne).

nlargest(self, n, columns[, keep])

Return the first n rows ordered by columns in descending order.

notna(self)

Detect existing (non-missing) values.

notnull(self)

Detect existing (non-missing) values.

nsmallest(self, n, columns[, keep])

Return the first n rows ordered by columns in ascending order.

nunique(self[, axis, dropna])

Count distinct observations over requested axis.

pct_change(self[, periods, fill_method, …])

Percentage change between the current and a prior element.

pipe(self, func, \*args, \*\*kwargs)

Apply func(self, *args, **kwargs).

pivot(self[, index, columns, values])

Return reshaped DataFrame organized by given index / column values.

pivot_table(self[, values, index, columns, …])

Create a spreadsheet-style pivot table as a DataFrame.

plot

alias of pandas.plotting._core.PlotAccessor

pop(self, item)

Return item and drop from frame.

pow(self, other[, axis, level, fill_value])

Get Exponential power of dataframe and other, element-wise (binary operator pow).

prod(self[, axis, skipna, level, …])

Return the product of the values for the requested axis.

product(self[, axis, skipna, level, …])

Return the product of the values for the requested axis.

quantile(self[, q, axis, numeric_only, …])

Return values at the given quantile over requested axis.

query(self, expr[, inplace])

Query the columns of a DataFrame with a boolean expression.

radd(self, other[, axis, level, fill_value])

Get Addition of dataframe and other, element-wise (binary operator radd).

rank(self[, axis, method, numeric_only, …])

Compute numerical data ranks (1 through n) along axis.

rdiv(self, other[, axis, level, fill_value])

Get Floating division of dataframe and other, element-wise (binary operator rtruediv).

reindex(self[, labels, index, columns, …])

Conform DataFrame to new index with optional filling logic, placing NA/NaN in locations having no value in the previous index.

reindex_like(self, other[, method, copy, …])

Return an object with matching indices as other object.

rename(self[, mapper, index, columns, axis, …])

Alter axes labels.

rename_axis(self[, mapper, index, columns, …])

Set the name of the axis for the index or columns.

reorder_levels(self, order[, axis])

Rearrange index levels using input order.

replace(self[, to_replace, value, inplace, …])

Replace values given in to_replace with value.

resample(self, rule[, how, axis, …])

Resample time-series data.

reset_index(self[, level, drop, inplace, …])

Reset the index, or a level of it.

rfloordiv(self, other[, axis, level, fill_value])

Get Integer division of dataframe and other, element-wise (binary operator rfloordiv).

rmod(self, other[, axis, level, fill_value])

Get Modulo of dataframe and other, element-wise (binary operator rmod).

rmul(self, other[, axis, level, fill_value])

Get Multiplication of dataframe and other, element-wise (binary operator rmul).

rolling(self, window[, min_periods, center, …])

Provide rolling window calculations.

round(self[, decimals])

Round a DataFrame to a variable number of decimal places.

rpow(self, other[, axis, level, fill_value])

Get Exponential power of dataframe and other, element-wise (binary operator rpow).

rsub(self, other[, axis, level, fill_value])

Get Subtraction of dataframe and other, element-wise (binary operator rsub).

rtruediv(self, other[, axis, level, fill_value])

Get Floating division of dataframe and other, element-wise (binary operator rtruediv).

sample(self[, n, frac, replace, weights, …])

Return a random sample of items from an axis of object.

select_dtypes(self[, include, exclude])

Return a subset of the DataFrame’s columns based on the column dtypes.

sem(self[, axis, skipna, level, ddof, …])

Return unbiased standard error of the mean over requested axis.

set_axis(self, labels[, axis, inplace])

Assign desired index to given axis.

set_index(self, keys[, drop, append, …])

Set the DataFrame index using existing columns.

set_value(self, index, col, value[, takeable])

Put single value at passed column and index.

shift(self[, periods, freq, axis, fill_value])

Shift index by desired number of periods with an optional time freq.

skew(self[, axis, skipna, level, numeric_only])

Return unbiased skew over requested axis Normalized by N-1.

slice_shift(self[, periods, axis])

Equivalent to shift without copying data.

sort_index(self[, axis, level, ascending, …])

Sort object by labels (along an axis).

sort_values(self, by[, axis, ascending, …])

Sort by the values along either axis.

sparse

alias of pandas.core.arrays.sparse.SparseFrameAccessor

squeeze(self[, axis])

Squeeze 1 dimensional axis objects into scalars.

stack(self[, level, dropna])

Stack the prescribed level(s) from columns to index.

std(self[, axis, skipna, level, ddof, …])

Return sample standard deviation over requested axis.

sub(self, other[, axis, level, fill_value])

Get Subtraction of dataframe and other, element-wise (binary operator sub).

subtract(self, other[, axis, level, fill_value])

Get Subtraction of dataframe and other, element-wise (binary operator sub).

sum(self[, axis, skipna, level, …])

Return the sum of the values for the requested axis.

swapaxes(self, axis1, axis2[, copy])

Interchange axes and swap values axes appropriately.

swaplevel(self[, i, j, axis])

Swap levels i and j in a MultiIndex on a particular axis.

tail(self[, n])

Return the last n rows.

take(self, indices[, axis, is_copy])

Return the elements in the given positional indices along an axis.

to_clipboard(self[, excel, sep])

Copy object to the system clipboard.

to_csv(self[, path_or_buf, sep, na_rep, …])

Write object to a comma-separated values (csv) file.

to_dense(self)

Return dense representation of Series/DataFrame (as opposed to sparse).

to_dict(self[, orient, into])

Convert the DataFrame to a dictionary.

to_excel(self, excel_writer[, sheet_name, …])

Write object to an Excel sheet.

to_feather(self, fname)

Write out the binary feather-format for DataFrames.

to_gbq(self, destination_table[, …])

Write a DataFrame to a Google BigQuery table.

to_hdf(self, path_or_buf, key, \*\*kwargs)

Write the contained data to an HDF5 file using HDFStore.

to_html(self[, buf, columns, col_space, …])

Render a DataFrame as an HTML table.

to_json(self[, path_or_buf, orient, …])

Convert the object to a JSON string.

to_latex(self[, buf, columns, col_space, …])

Render an object to a LaTeX tabular environment table.

to_msgpack(self[, path_or_buf, encoding])

Serialize object to input file path using msgpack format.

to_numpy(self[, dtype, copy])

Convert the DataFrame to a NumPy array.

to_parquet(self, fname[, engine, …])

Write a DataFrame to the binary parquet format.

to_period(self[, freq, axis, copy])

Convert DataFrame from DatetimeIndex to PeriodIndex with desired frequency (inferred from index if not passed).

to_pickle(self, path[, compression, protocol])

Pickle (serialize) object to file.

to_records(self[, index, …])

Convert DataFrame to a NumPy record array.

to_sparse(self[, fill_value, kind])

Convert to SparseDataFrame.

to_sql(self, name, con[, schema, if_exists, …])

Write records stored in a DataFrame to a SQL database.

to_stata(self, fname[, convert_dates, …])

Export DataFrame object to Stata dta format.

to_string(self[, buf, columns, col_space, …])

Render a DataFrame to a console-friendly tabular output.

to_timestamp(self[, freq, how, axis, copy])

Cast to DatetimeIndex of timestamps, at beginning of period.

to_xarray(self)

Return an xarray object from the pandas object.

transform(self, func[, axis])

Call func on self producing a DataFrame with transformed values and that has the same axis length as self.

transpose(self, \*args, \*\*kwargs)

Transpose index and columns.

truediv(self, other[, axis, level, fill_value])

Get Floating division of dataframe and other, element-wise (binary operator truediv).

truncate(self[, before, after, axis, copy])

Truncate a Series or DataFrame before and after some index value.

tshift(self[, periods, freq, axis])

Shift the time index, using the index’s frequency if available.

tz_convert(self, tz[, axis, level, copy])

Convert tz-aware axis to target time zone.

tz_localize(self, tz[, axis, level, copy, …])

Localize tz-naive index of a Series or DataFrame to target time zone.

unstack(self[, level, fill_value])

Pivot a level of the (necessarily hierarchical) index labels, returning a DataFrame having a new level of column labels whose inner-most level consists of the pivoted index labels.

update(self, other[, join, overwrite, …])

Modify in place using non-NA values from another DataFrame.

var(self[, axis, skipna, level, ddof, …])

Return unbiased variance over requested axis.

where(self, cond[, other, inplace, axis, …])

Replace values where the condition is False.

xs(self, key[, axis, level, drop_level])

Return cross-section from the Series/DataFrame.

Additional Image Classification APIs

Classifier

class autogluon.task.image_classification.Classifier(model, results, eval_func, scheduler_checkpoint, args, ensemble=0, format_results=True, **kwargs)

Trained Image Classifier returned by fit() that can be used to make predictions on new images.

Examples

>>> from autogluon import ImageClassification as task
>>> dataset = task.Dataset(train_path='data/train',
>>>                        test_path='data/test')
>>> classifier = task.fit(dataset,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=time_limits,
>>>                       ngpus_per_trial=1,
>>>                       num_trials = 4)
>>> image = 'data/test/BabyShirt/BabyShirt_323.jpg'
>>> ind, prob = classifier.predict(image)

Methods

evaluate(self, dataset[, input_size, ctx])

Evaluate predictive performance of trained image classifier using given test data.

load(checkpoint)

Load trained Image Classifier from directory specified by checkpoint.

predict(self, X[, input_size, crop_ratio, …])

Predict class-index and associated class probability for each image in a given dataset (or just a single image).

save(self, checkpoint)

Save image classifier to folder specified by checkpoint.

evaluate(self, dataset, input_size=224, ctx=[cpu(0)])

Evaluate predictive performance of trained image classifier using given test data.

Parameters
datasetautogluon.task.ImageClassification.Dataset

The dataset containing test images (must be in same format as the training dataset).

input_sizeint

Size of the images (pixels).

ctxList of mxnet.context elements.

Determines whether to use CPU or GPU(s), options include: [mx.cpu()] or [mx.gpu()].

Examples

>>> from autogluon import ImageClassification as task
>>> train_data = task.Dataset(train_path='~/data/train')
>>> classifier = task.fit(train_data,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=600, ngpus_per_trial=1, num_trials = 4)
>>> test_data = task.Dataset('~/data/test', train=False)
>>> test_acc = classifier.evaluate(test_data)
classmethod load(checkpoint)

Load trained Image Classifier from directory specified by checkpoint.

predict(self, X, input_size=224, crop_ratio=0.875, set_prob_thresh=0.001, plot=False)

Predict class-index and associated class probability for each image in a given dataset (or just a single image).

Parameters
Xstr or autogluon.task.ImageClassification.Dataset or list of autogluon.task.ImageClassification.Dataset

If str, should be path to the input image (when we just want to predict on single image). If class:autogluon.task.ImageClassification.Dataset, should be dataset of multiple images in same format as training dataset. If list of autogluon.task.ImageClassification.Dataset, should be a set of test dataset with different scales of origin images.

input_sizeint

Size of the images (pixels).

plotbool

Whether to plot the image being classified.

set_prob_thresh: float

Results with probability below threshold are set to 0 by default.

Examples

>>> from autogluon import ImageClassification as task
>>> train_data = task.Dataset(train_path='~/data/train')
>>> classifier = task.fit(train_data,
>>>                       nets=ag.space.Categorical['resnet18_v1', 'resnet34_v1'],
>>>                       time_limits=600, ngpus_per_trial=1, num_trials=4)
>>> test_data = task.Dataset('~/data/test', train=False)
>>> class_index, class_probability = classifier.predict('example.jpg')
save(self, checkpoint)

Save image classifier to folder specified by checkpoint.

get_dataset

autogluon.task.image_classification.get_dataset(path=None, train=True, name=None, input_size=224, crop_ratio=0.875, jitter_param=0.4, scale_ratio_choice=[], *args, **kwargs)

Method to produce image classification dataset for AutoGluon, can either be a ImageFolderDataset, RecordDataset, or a popular dataset already built into AutoGluon (‘mnist’, ‘cifar10’, ‘cifar100’, ‘imagenet’).

Parameters
namestr, optional

Which built-in dataset to use, will override all other options if specified. The options are (‘mnist’, ‘cifar’, ‘cifar10’, ‘cifar100’, ‘imagenet’)

trainbool, default = True

Whether this dataset should be used for training or validation.

pathstr

The training data location. If using ImageFolderDataset, image folder`path/to/the/folder` should be provided. If using RecordDataset, the path/to/*.rec should be provided.

input_sizeint

The input image size.

crop_ratiofloat

Center crop ratio (for evaluation only)

scale_ratio_choice: list

List of crop_ratio, only in the test dataset, the set of scaling ratios obtained is scaled to the original image, and then cut a fixed size (input_size) and get a set of predictions for averaging.

Returns
Dataset object that can be passed to task.fit(), which is actually an autogluon.space.AutoGluonObject.
To interact with such an object yourself, you must first call Dataset.init() to instantiate the object in Python.

ImageFolderDataset

class autogluon.task.image_classification.ImageFolderDataset(*args, **kwargs)

A generic data loader where the images are arranged in this way on your local filesystem:

root/dog/a.png
root/dog/b.png
root/dog/c.png

root/cat/x.png
root/cat/y.png
root/cat/z.png

Here, folder-names dog and cat are the class labels and the images with file-names ‘a’, b, c belong to the dog class while the others are cat images.

Parameters
rootstring

Root directory path to the folder containing all of the data.

transformcallable (optional)

A function/transform that takes in an PIL image and returns a transformed version. E.g, transforms.RandomCrop

is_valid_filecallable (optional)

A function that takes path of an Image file and check if the file is a valid file (used to check of corrupt files)

Attributes
classeslist

List of the class names.

class_to_idxdict

Dict with items (class_name, class_index).

imgslist

List of (image path, class_index) tuples

Methods

__call__(self, \*args, \*\*kwargs)

Convenience method for interacting with AutoGluonObject.

init(self)

Instantiate an actual instance of this AutoGluonObject.

sample

property cs

ConfigSpace representation of this search space.

property default

Return default value for hyperparameter corresponding to this search space.

init(self)

Instantiate an actual instance of this AutoGluonObject. In order to interact with such an object, you must always first call: object.init().

property rand

Randomly sample configuration from this nested search space.

RecordDataset

class autogluon.task.image_classification.RecordDataset(*args, **kwargs)
A dataset wrapping over a RecordIO file containing images.

Each sample is an image and its corresponding label.

Parameters
filenamestr

Local path to the .rec file.

gray_scaleFalse

If True, always convert images to greyscale. If False, always convert images to colored (RGB).

transformfunction, default None

A user defined callback that transforms each sample.

classesiterable of str, default is None

User provided class names. If None is provide, will use a list of increasing natural number [‘0’, ‘1’, …, ‘N’] by default.

Attributes
cs

ConfigSpace representation of this search space.

default

Return default value for hyperparameter corresponding to this search space.

rand

Randomly sample configuration from this nested search space.

Methods

__call__(self, \*args, \*\*kwargs)

Convenience method for interacting with AutoGluonObject.

init(self)

Instantiate an actual instance of this AutoGluonObject.

sample

property cs

ConfigSpace representation of this search space.

property default

Return default value for hyperparameter corresponding to this search space.

init(self)

Instantiate an actual instance of this AutoGluonObject. In order to interact with such an object, you must always first call: object.init().

property rand

Randomly sample configuration from this nested search space.

Additional Object Detection APIs

Detector

class autogluon.task.object_detection.Detector(model, results, scheduler_checkpoint, args, format_results=True, **kwargs)

Trained Object Detector returned by task.fit()

Methods

evaluate(self, dataset[, ctx])

Evaluate performance of this object detector’s predictions on test data.

predict(self, X[, input_size, thresh, plot])

Use this object detector to make predictions on test data.

evaluate(self, dataset, ctx=[cpu(0)])

Evaluate performance of this object detector’s predictions on test data.

Parameters
dataset: `Dataset`

Test dataset (must be in the same format as training data previously provided to fit).

ctxList of mxnet.context elements.

Determines whether to use CPU or GPU(s), options include: [mx.cpu()] or [mx.gpu()].

predict(self, X, input_size=224, thresh=0.15, plot=True)

Use this object detector to make predictions on test data.

Parameters
XTest data with image(s) to make predictions for.
input_sizeint

Size of images in test data (pixels).

threshfloat

Confidence Threshold above which detector outputs bounding box for object.

plotbool

Whether or not to plot the bounding box of detected objects on top of the original images.

Returns
Tuple containing the class-IDs of detected objects, the confidence-scores associated with
these detectiions, and the corresponding predicted bounding box locations.

get_dataset

autogluon.task.object_detection.dataset.get_dataset(root='~/.mxnet/datasets/voc', index_file_name='trainval', name=None, classes=None, format='voc', Train=True, **kwargs)

Load dataset to use for object detection, which must be in either VOC or COCO format.

Parameters
rootstr

Path to folder storing the dataset.

index_file_namestr

Name of file containing the training/validation indices of each text example. The name of the .txt file which constains images for training or testing. this is only for custom dataset.

name: str

name for built-in dataset, (‘voc’, ‘voc2007’ or ‘voc2012’) when use built-in dataset, the index_file_name should be None.

classestuple of classes, default = None

users can specify classes for custom dataset ex. classes = (‘bike’, ‘bird’, ‘cat’, …) We reuse the neural network weights if the corresponding class appears in the pretrained model. Otherwise, we randomly initialize the neural network weights for new classes.

formatstr

Format of the object detection dataset, either: ‘voc’ or ‘coco’. For details, see: autogluon/task/object_detection/dataset/voc.py, autogluon/task/object_detection/dataset/coco.py

Trainbool, default = True

pecify Train/Test mode. It is only valid when name is not None.

kwargskeyword arguments

Passed to either: autogluon.task.object_detection.dataset.CustomVOCDetection() or autogluon.task.object_detection.dataset.COCO().

Returns
Dataset object that can be passed to task.fit(), which is actually an autogluon.space.AutoGluonObject.
To interact with such an object yourself, you must first call Dataset.init() to instantiate the object in Python.

CustomVOCDetection

class autogluon.task.object_detection.dataset.CustomVOCDetection(*args, **kwargs)

Custom Dataset which follows protocol/formatting of the well-known VOC object detection dataset.

Parameters
rootstr, default ‘~/mxnet/datasets/voc’

Path to folder storing the dataset.

splitslist of tuples

List of combinations of (year, name) to indicate how to split data into training, validation, and test sets. For the original VOC dataset, the year candidates can be: 2007, 2012. For the original VOC dataset, the name candidates can be: ‘train’, ‘val’, ‘trainval’, ‘test’. For the original VOC dataset, one might use for example: ((2007, ‘trainval’), (2012, ‘trainval’))

classes: tuple of classes

We reuse the neural network weights if the corresponding class appears in the pretrained model. Otherwise, we randomly initialize the neural network weights for new classes.

Returns
Dataset object that can be passed to task.fit(), which is actually an autogluon.space.AutoGluonObject.
To interact with such an object yourself, you must first call Dataset.init() to instantiate the object in Python.
Attributes
cs

ConfigSpace representation of this search space.

default

Return default value for hyperparameter corresponding to this search space.

rand

Randomly sample configuration from this nested search space.

Methods

__call__(self, \*args, \*\*kwargs)

Convenience method for interacting with AutoGluonObject.

init(self)

Instantiate an actual instance of this AutoGluonObject.

sample

CustomVOCDetectionBase

class autogluon.task.object_detection.dataset.CustomVOCDetectionBase(classes=None, root='~/.mxnet/datasets/voc', splits=((2007, 'trainval'), (2012, 'trainval')), transform=None, index_map=None, preload_label=True)

Base class for custom Dataset which follows protocol/formatting of the well-known VOC object detection dataset.

Parameters
class: tuple of classes, default = None

We reuse the neural network weights if the corresponding class appears in the pretrained model. Otherwise, we randomly initialize the neural network weights for new classes.

rootstr, default ‘~/mxnet/datasets/voc’

Path to folder storing the dataset.

splitslist of tuples, default ((2007, ‘trainval’), (2012, ‘trainval’))

List of combinations of (year, name) For years, candidates can be: 2007, 2012. For names, candidates can be: ‘train’, ‘val’, ‘trainval’, ‘test’.

transformcallable, default = None

A function that takes data and label and transforms them. Refer to ./transforms for examples. A transform function for object detection should take label into consideration, because any geometric modification will require label to be modified.

index_mapdict, default = None

By default, the 20 classes are mapped into indices from 0 to 19. We can customize it by providing a str to int dict specifying how to map class names to indices. This is only for advanced users, when you want to swap the orders of class labels.

preload_labelbool, default = True

If True, then parse and load all labels into memory during initialization. It often accelerate speed but require more memory usage. Typical preloaded labels took tens of MB. You only need to disable it when your dataset is extremely large.

Attributes
classes

Category names.

num_class

Number of categories.

Methods

filter(self, fn)

Returns a new dataset with samples filtered by the filter function fn.

sample(self, sampler)

Returns a new dataset with elements sampled by the sampler.

shard(self, num_shards, index)

Returns a new dataset includes only 1/num_shards of this dataset.

take(self, count)

Returns a new dataset with at most count number of samples in it.

transform(self, fn[, lazy])

Returns a new dataset with each sample transformed by the transformer function fn.

transform_first(self, fn[, lazy])

Returns a new dataset with the first element of each sample transformed by the transformer function fn.

COCO

class autogluon.task.object_detection.dataset.COCO(*args, **kwargs)

Built-in class to work with the well-known COCO dataset for object detection.

Returns
Dataset object that can be passed to task.fit(), which is actually an autogluon.space.AutoGluonObject.
To interact with such an object yourself, you must first call Dataset.init() to instantiate the object in Python.
Attributes
cs

ConfigSpace representation of this search space.

default

Return default value for hyperparameter corresponding to this search space.

rand

Randomly sample configuration from this nested search space.

Methods

__call__(self, \*args, \*\*kwargs)

Convenience method for interacting with AutoGluonObject.

init(self)

Instantiate an actual instance of this AutoGluonObject.

sample

Additional Text Classification APIs

TextClassificationPredictor

class autogluon.task.text_classification.TextClassificationPredictor(model, transform, test_transform, results, scheduler_checkpoint, args)

Trained Text Classifier returned by fit() that can be used to make predictions on new text data.

Methods

evaluate(self, dataset[, ctx])

Evaluate predictive performance of trained text classifier using given test data.

predict(self, X)

Predict class-index of a given sentence / text-snippet.

predict_proba(self, X)

Predict class-probabilities of a given sentence / text-snippet.

evaluate(self, dataset, ctx=[cpu(0)])

Evaluate predictive performance of trained text classifier using given test data.

Parameters
datasetautogluon.task.TextClassification.Dataset

The dataset containing test sentences (must be in same format as the training dataset provided to fit).

ctxList of mxnet.context elements.

Determines whether to use CPU or GPU(s), options include: [mx.cpu()] or [mx.gpu()].

Examples

>>> from autogluon import TextClassification as task
>>> dataset = task.Dataset(test_path='~/data/test')
>>> test_performance = predictor.evaluate(dataset)
predict(self, X)

Predict class-index of a given sentence / text-snippet.

Parameters
Xstr

The input sentence we should classify.

Returns
Int corresponding to index of the predicted class.

Examples

>>> class_index = predictor.predict('this is cool')
predict_proba(self, X)

Predict class-probabilities of a given sentence / text-snippet.

Parameters
Xstr

The input sentence we should classify.

Returns
mxnet.NDArray containing predicted probabilities of each class.

Examples

>>> class_probs = predictor.predict_proba('this is cool')

get_dataset

autogluon.task.text_classification.get_dataset(name=None, *args, **kwargs)

Load a text classification dataset to train AutoGluon models on.

Parameters
namestr

Name describing which built-in popular text dataset to use (mostly from the GLUE NLP benchmark). Options include: ‘mrpc’, ‘qqp’, ‘qnli’, ‘rte’, ‘sts-b’, ‘cola’, ‘mnli’, ‘wnli’, ‘sst’, ‘toysst’. Detailed descriptions can be found in the file: autogluon/task/text_classification/dataset.py

**kwargssome keyword arguments when using custom dataset as below.
kwargs[‘label’]: str or int Default: last column

Index or column name of the label/target column.