Shortcuts

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)[source]

Bases: lumin.nn.ensemble.abs_ensemble.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
Examples::
>>> ensemble = Ensemble()
>>>
>>> ensemble = Ensemble(input_pipe, output_pipe, model_builder)
add_input_pipe(pipe)[source]

Add input pipeline for saving

Parameters

pipe (Pipeline) – pipeline used for preprocessing input data

Return type

None

add_output_pipe(pipe)[source]

Add output pipeline for saving

Parameters

pipe (Pipeline) – pipeline used for preprocessing target data

Return type

None

export2onnx(base_name, bs=1)[source]

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)[source]

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)[source]

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_ouput_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)[source]

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)[source]

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>)[source]

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)[source]

Load an instantiated Ensemble with weights and Model from save.

Arguments;

name: base name for saved objects

Examples::
>>> ensemble.load('weights/ensemble')
Return type

None

static load_trained_model(model_idx, model_builder, name='train_weights/train_')[source]

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

Arguments

model_idx: index of model to load model_builder: ModelBuilder used to build the model name: base name of file from which to load 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)[source]

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

Return type

Union[None, 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)[source]

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

Examples::
>>> ensemble.save('weights/ensemble')
>>>
>>> ensemble.save('weights/ensemble', ['pt','eta','phi'])
Return type

None

Module contents

Read the Docs v: v0.7.1
Versions
latest
stable
v0.7.1
v0.7.0
v0.6.0
v0.5.1
v0.5.0
v0.4.0.1
v0.3.1
Downloads
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.

Docs

Access comprehensive developer and user documentation for LUMIN

View Docs

Tutorials

Get tutorials for beginner and advanced researchers demonstrating many of the features of LUMIN

View Tutorials