lumin.nn.ensemble package

Submodules

lumin.nn.ensemble.ensemble module

class lumin.nn.ensemble.ensemble.Ensemble(input_pipe=None, output_pipe=None, model_builder=None)

Bases: AbsEnsemble

Standard class for building an ensemble of collection of trained networks producedd by fold_train_ensemble() Input and output pipelines can be added. to provide easy saving and loaded of exported ensembles. Currently, the input pipeline is not used, so input data is expected to be preprocessed. However the output pipeline will be used to deprocess model predictions.

Once instanciated, lumin.nn.ensemble.ensemble.Ensemble.build_ensemble() or :meth:load should be called. Alternatively, class_methods lumin.nn.ensemble.ensemble.Ensemble.from_save() or lumin.nn.ensemble.ensemble.Ensemble.from_results() may be used.

# TODO: check whether model_builder is necessary here # TODO: Standardise pipeline treatment: currently inputs not processed, but outputs are

Parameters:

• input_pipe (Optional[Pipeline]) – Optional input pipeline, alternatively call lumin.nn.ensemble.ensemble.Ensemble.add_input_pipe()

• output_pipe (Optional[Pipeline]) – Optional output pipeline, alternatively call lumin.nn.ensemble.ensemble.Ensemble.add_output_pipe()

• model_builder (Optional[ModelBuilder]) – Optional ModelBuilder for constructing models from saved weights.

Examples::

>>> ensemble = Ensemble()
>>>
>>> ensemble = Ensemble(input_pipe, output_pipe, model_builder)

add_input_pipe(pipe)

Add input pipeline for saving

Parameters:

pipe (Pipeline) – pipeline used for preprocessing input data

Return type:

None

add_output_pipe(pipe)

Add output pipeline for saving

Parameters:

pipe (Pipeline) – pipeline used for preprocessing target data

Return type:

None

export2onnx(base_name, bs=1)

Export all Model contained in Ensemble to ONNX format. Note that ONNX expects a fixed batch size (bs) which is the number of datapoints your wish to pass through the model concurrently.

Parameters:

• base_name (str) – Exported models will be called {base_name}_{model_num}.onnx

• bs (int) – batch size for exported models

Return type:

None

export2tfpb(base_name, bs=1)

Export all Model contained in Ensemble to Tensorflow ProtocolBuffer format, via ONNX. Note that ONNX expects a fixed batch size (bs) which is the number of datapoints your wish to pass through the model concurrently.

Parameters:

• base_name (str) – Exported models will be called {base_name}_{model_num}.pb

• bs (int) – batch size for exported models

Return type:

None

classmethod from_models(models, weights=None, results=None, input_pipe=None, output_pipe=None, model_builder=None)

Instantiate Ensemble from a list of Model, and the associated ModelBuilder.

Parameters:

• models (List[AbsModel]) – list of Model

• weights (Union[ndarray, List[float], None]) – Optional list of weights, otherwise models will be weighted uniformly

• results (Optional[List[Dict[str, float]]]) – Optional results saved/returned by fold_train_ensemble()

• input_pipe (Optional[Pipeline]) – Optional input pipeline, alternatively call lumin.nn.ensemble.ensemble.Ensemble.add_input_pipe()

• output_pipe (Optional[Pipeline]) – Optional output pipeline, alternatively call lumin.nn.ensemble.ensemble.Ensemble.add_output_pipe()

• model_builder (Optional[ModelBuilder]) – Optional ModelBuilder for constructing models from saved weights.

Return type:

AbsEnsemble

Returns:

Built Ensemble

Examples::

>>> ensemble = Ensemble.from_models(models)
>>>
>>> ensemble = Ensemble.from_models(models, weights)
>>>
>>> ensemble = Ensemble(models, weights, input_pipe, output_pipe, model_builder)

classmethod from_results(results, size, model_builder, metric='loss', weighting='reciprocal', higher_metric_better=False, snapshot_args=None, verbose=True)

Instantiate Ensemble from a outputs of fold_train_ensemble(). If cycle models are loaded, then only uniform weighting between models is supported.

Parameters:

• results (List[Dict[str, float]]) – results saved/returned by fold_train_ensemble()

• size (int) – number of models to load as ranked by metric

• model_builder (ModelBuilder) – ModelBuilder used for building Model from saved models

• metric (str) – metric name listed in results to use for ranking and weighting trained models

• weighting (str) – ‘reciprocal’ or ‘uniform’ how to weight model predictions during predicition. ‘reciprocal’ = models weighted by 1/metric ‘uniform’ = models treated with equal weighting

• higher_metric_better (bool) – whether metric should be maximised or minimised

• snapshot_args (Optional[Dict[str, Any]]) –

  Dictionary potentially containing: ‘cycle_losses’: returned/save by fold_train_ensemble() when using an AbsCyclicCallback ‘patience’: patience value that was passed to fold_train_ensemble() ‘n_cycles’: number of cycles to load per model ‘load_cycles_only’: whether to only load cycles, or also the best performing model ‘weighting_pwr’: weight cycles according to (n+1)**weighting_pwr, where n is the number of cycles loaded so far.

  Models are loaded youngest to oldest

• verbose (bool) – whether to print out information of models loaded

Return type:

AbsEnsemble

Returns:

Built Ensemble

Examples::

>>> ensemble = Ensemble.from_results(results, 10, model_builder,
...                                  location=Path('train_weights'))
>>>
>>> ensemble = Ensemble.from_results(
...     results, 1,  model_builder,
...     location=Path('train_weights'),
...     snapshot_args={'cycle_losses':cycle_losses,
...                    'patience':patience,
...                    'n_cycles':8,
...                    'load_cycles_only':True,
...                    'weighting_pwr':0})

classmethod from_save(name)

Instantiate Ensemble from a saved Ensemble

Parameters:

name (str) – base filename of ensemble

Return type:

AbsEnsemble

Returns:

Loaded Ensemble

Examples::

>>> ensemble = Ensemble.from_save('weights/ensemble')

get_feat_importance(fy, bs=None, eval_metric=None, savename=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)

Call get_ensemble_feat_importance(), passing this Ensemble and provided arguments

Parameters:

• fy (FoldYielder) – FoldYielder interfacing to data on which to evaluate importance

• bs (Optional[int]) – If set, will evaluate model in batches of data, rather than all at once

• eval_metric (Optional[EvalMetric]) – Optional EvalMetric to use to quantify performance in place of loss

• savename (Optional[str]) – Optional name of file to which to save the plot of feature importances

• plot_settings (PlotSettings) – PlotSettings class to control figure appearance

Return type:

DataFrame

load(name)

Load an instantiated Ensemble with weights and Model from save.

Return type:

None

Arguments;

name: base name for saved objects

Examples::

>>> ensemble.load('weights/ensemble')

static load_trained_model(name, model_builder)

Load trained model from save file of the form {name}{model_idx}.h5

Arguments

name: name of file from which to load model model_builder: ModelBuilder used to build the model

Return type:

Model

Returns:

Model loaded from save

predict(inputs, n_models=None, pred_name='pred', pred_cb=<lumin.nn.callbacks.pred_handlers.PredHandler object>, cbs=None, verbose=True, bs=None, auto_deprocess=False)

Apply ensemble to inputed data and compute predictions.

Parameters:

• inputs (Union[ndarray, FoldYielder, List[ndarray]]) – input data as Numpy array, Pandas DataFrame, or tensor on device, or FoldYielder interfacing to data

• as_np – whether to return predictions as Numpy array (otherwise tensor) if inputs are a Numpy array, Pandas DataFrame, or tensor

• pred_name (str) – name of group to which to save predictions if inputs are a FoldYielder

• pred_cb (PredHandler) – PredHandler callback to determin how predictions are computed. Default simply returns the model predictions. Other uses could be e.g. running argmax on a multiclass classifier

• cbs (Optional[List[AbsCallback]]) – list of any instantiated callbacks to use during prediction

• bs (Optional[int]) – if not None, will run prediction in batches of specified size to save of memory

• auto_deprocess (bool) – if true and ensemble has an output_pipe, will inverse-transform predictions

Return type:

Optional[ndarray]

Returns:

if inputs are a Numpy array, Pandas DataFrame, or tensor, will return predicitions as either array or tensor

save(name, feats=None, overwrite=False)

Save ensemble and associated objects

Parameters:

• name (str) – base name for saved objects

• feats (Optional[Any]) – optional list of input features

• overwrite (bool) – if existing objects are found, whether to overwrite them

Return type:

None

Examples::

>>> ensemble.save('weights/ensemble')
>>>
>>> ensemble.save('weights/ensemble', ['pt','eta','phi'])

Module contents