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_methodslumin.nn.ensemble.ensemble.Ensemble.from_save()
orlumin.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 calllumin.nn.ensemble.ensemble.Ensemble.add_input_pipe()
output_pipe (
Optional
[Pipeline
]) – Optional output pipeline, alternatively calllumin.nn.ensemble.ensemble.Ensemble.add_output_pipe()
model_builder (
Optional
[ModelBuilder
]) – OptionalModelBuilder
for constructing models from saved weights.
- 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 inEnsemble
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}.onnxbs (
int
) – batch size for exported models
- Return type
None
-
export2tfpb
(base_name, bs=1)[source]¶ Export all
Model
contained inEnsemble
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}.pbbs (
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 ofModel
, and the associatedModelBuilder
.- Parameters
models (
List
[AbsModel
]) – list ofModel
weights (
Union
[ndarray
,List
[float
],None
]) – Optional list of weights, otherwise models will be weighted uniformlyresults (
Optional
[List
[Dict
[str
,float
]]]) – Optional results saved/returned byfold_train_ensemble()
input_pipe (
Optional
[Pipeline
]) – Optional input pipeline, alternatively calllumin.nn.ensemble.ensemble.Ensemble.add_input_pipe()
output_pipe (
Optional
[Pipeline
]) – Optional output pipeline, alternatively calllumin.nn.ensemble.ensemble.Ensemble.add_output_pipe()
model_builder (
Optional
[ModelBuilder
]) – OptionalModelBuilder
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 offold_train_ensemble()
. If cycle models are loaded, then only uniform weighting between models is supported.- Parameters
results (
List
[Dict
[str
,float
]]) – results saved/returned byfold_train_ensemble()
size (
int
) – number of models to load as ranked by metricmodel_builder (
ModelBuilder
) –ModelBuilder
used for buildingModel
from saved modelsmetric (
str
) – metric name listed in results to use for ranking and weighting trained modelsweighting (
str
) – ‘reciprocal’ or ‘uniform’ how to weight model predictions during predicition. ‘reciprocal’ = models weighted by 1/metric ‘uniform’ = models treated with equal weightinghigher_metric_better (
bool
) – whether metric should be maximised or minimisedsnapshot_args (
Optional
[Dict
[str
,Any
]]) –Dictionary potentially containing: ‘cycle_losses’: returned/save by
fold_train_ensemble()
when using anAbsCyclicCallback
‘patience’: patience value that was passed tofold_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 savedEnsemble
- 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 thisEnsemble
and provided arguments- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to data on which to evaluate importancebs (
Optional
[int
]) – If set, will evaluate model in batches of data, rather than all at onceeval_metric (
Optional
[EvalMetric
]) – OptionalEvalMetric
to use to quantify performance in place of losssavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancesplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
DataFrame
-
load
(name)[source]¶ Load an instantiated
Ensemble
with weights andModel
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
- 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)[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, orFoldYielder
interfacing to dataas_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 aFoldYielder
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 classifiercbs (
Optional
[List
[AbsCallback
]]) – list of any instantiated callbacks to use during predictionbs (
Optional
[int
]) – if not None, will run prediction in batches of specified size to save of memoryauto_deprocess (
bool
) – if true and ensemble has an output_pipe, will inverse-transform predictions
- 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 objectsfeats (
Optional
[Any
]) – optional list of input featuresoverwrite (
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