LUMIN Documentation¶
Lumin Unifies Many Improvements for Networks
lumin.data_processing package¶
Submodules¶
lumin.data_processing.file_proc module¶
-
lumin.data_processing.file_proc.
save_to_grp
(arr, grp, name)[source]¶ Save Numpy array as a dataset in an h5py Group
- Parameters
arr (
ndarray
) – array to be savedgrp (
Group
) – group in which to save arrname (
str
) – name of dataset to create
- Return type
None
-
lumin.data_processing.file_proc.
fold2foldfile
(df, out_file, fold_idx, cont_feats, cat_feats, targ_feats, targ_type, misc_feats=None, wgt_feat=None)[source]¶ Save fold of data into an h5py Group
- Parameters
df (
DataFrame
) – Dataframe from which to save dataout_file (
File
) – h5py file to save data infold_idx (
int
) – ID for the fold; used name h5py group according to ‘fold_{fold_idx}’cont_feats (
List
[str
]) – list of columns in df to save as continuous variablescat_feats (
List
[str
]) – list of columns in df to save as discreet variablestarg_feats (list of) column(s) in df to save as target feature(s) –
targ_type (
Any
) – type of target feature, e.g. int,’float32’misc_feats (optional) – any extra columns to save
wgt_feat (optional) – column to save as data weights
- Return type
None
-
lumin.data_processing.file_proc.
df2foldfile
(df, n_folds, cont_feats, cat_feats, targ_feats, savename, targ_type, strat_key=None, misc_feats=None, wgt_feat=None)[source]¶ Convert dataframe into h5py file by splitting data into sub-folds to be accessed by a
FoldYielder
- Parameters
df (
DataFrame
) – Dataframe from which to save datan_folds (
int
) – number of folds to split df intocont_feats (
List
[str
]) – list of columns in df to save as continuous variablescat_feats (
List
[str
]) – list of columns in df to save as discreet variablestarg_feats (list of) column(s) in df to save as target feature(s) –
savename (
Union
[Path
,str
]) – name of h5py file to create (.h5py extension not required)targ_type (
str
) – type of target feature, e.g. int,’float32’strat_key (optional) – column to use for stratified splitting
misc_feats (optional) – any extra columns to save
wgt_feat (optional) – column to save as data weights
lumin.data_processing.hep_proc module¶
-
lumin.data_processing.hep_proc.
to_cartesian
(df, vec, drop=False)[source]¶ Vectoriesed conversion of 3-momenta to Cartesian coordinates inplace, optionally dropping old pT,eta,phi features
- Parameters
df (
DataFrame
) – DataFrame to altervec (
str
) – column prefix of vector components to alter, e.g. ‘muon’ for columns [‘muon_pt’, ‘muon_phi’, ‘muon_eta’]drop (
bool
) – Whether to remove original columns and just keep the new ones
- Return type
None
-
lumin.data_processing.hep_proc.
to_pt_eta_phi
(df, vec, eta=None, drop=False)[source]¶ Vectoriesed conversion of 3-momenta to pT,eta,phi coordinates inplace, optionally dropping old px,py,pz features
Attention
eta is now deprecieated as it is now infered from df. Will be removed in V0.4
- Parameters
df (
DataFrame
) – DataFrame to altervec (
str
) – column prefix of vector components to alter, e.g. ‘muon’ for columns [‘muon_px’, ‘muon_py’, ‘muon_pz’]eta (
Optional
[bool
]) – depreciated as now infereddrop (
bool
) – Whether to remove original columns and just keep the new ones
- Return type
None
-
lumin.data_processing.hep_proc.
delta_phi
(arr_a, arr_b)[source]¶ Vectorised compututation of modulo 2pi angular seperation of array of angles b from array of angles a, in range [-pi,pi]
- Parameters
arr_a (
Union
[float
,ndarray
]) – reference anglesarr_b (
Union
[float
,ndarray
]) – final angles
- Return type
Union
[float
,ndarray
]- Returns
angular separation as float or np.array
-
lumin.data_processing.hep_proc.
twist
(dphi, deta)[source]¶ Vectorised computation of twist between vectors (https://arxiv.org/abs/1010.3698)
- Parameters
dphi (
Union
[float
,ndarray
]) – delta phi separationsdeta (
Union
[float
,ndarray
]) – delta eta separations
- Return type
Union
[float
,ndarray
]- Returns
angular separation as float or np.array
-
lumin.data_processing.hep_proc.
add_abs_mom
(df, vec, z=True)[source]¶ Vectorised computation 3-momenta magnitude, adding new column in place. Currently only works for Cartesian vectors
- Parameters
df (
DataFrame
) – DataFrame to altervec (
str
) – column prefix of vector components, e.g. ‘muon’ for columns [‘muon_px’, ‘muon_py’, ‘muon_pz’]z (
bool
) – whether to consider the z-component of the momenta
- Return type
None
-
lumin.data_processing.hep_proc.
add_mass
(df, vec)[source]¶ Vectorised computation of mass of 4-vector, adding new column in place.
- Parameters
df (
DataFrame
) – DataFrame to altervec (
str
) – column prefix of vector components, e.g. ‘muon’ for columns [‘muon_px’, ‘muon_py’, ‘muon_pz’]
- Return type
None
-
lumin.data_processing.hep_proc.
add_energy
(df, vec)[source]¶ Vectorised computation of energy of 4-vector, adding new column in place.
- Parameters
df (
DataFrame
) – DataFrame to altervec (
str
) – column prefix of vector components, e.g. ‘muon’ for columns [‘muon_px’, ‘muon_py’, ‘muon_pz’]
- Return type
None
-
lumin.data_processing.hep_proc.
add_mt
(df, vec, mpt_name='mpt')[source]¶ Vectorised computation of transverse mass of 4-vector with respect to missing transverse momenta, adding new column in place. Currently only works for pT, eta, phi vectors
- Parameters
df (
DataFrame
) – DataFrame to altervec (
str
) – column prefix of vector components, e.g. ‘muon’ for columns [‘muon_px’, ‘muon_py’, ‘muon_pz’]mpt_name (
str
) – column prefix of vector of missing transverse momenta components, e.g. ‘mpt’ for columns [‘mpt_pT’, ‘mpt_phi’]
-
lumin.data_processing.hep_proc.
get_vecs
(feats, strict=True)[source]¶ Filter list of features to get list of 3-momenta defined in the list. Works for both pT, eta, phi and Cartesian coordinates. If strict, return only vectors with all coordinates present in feature list.
- Parameters
feats (
List
[str
]) – list of features to filterstrict (
bool
) – whether to require all 3-momenta components to be present in the list
- Return type
Set
[str
]- Returns
set of unique 3-momneta prefixes
-
lumin.data_processing.hep_proc.
fix_event_phi
(df, ref_vec)[source]¶ Rotate event in phi such that ref_vec is at phi == 0. Performed inplace. Currently only works on vectors defined in pT, eta, phi
- Parameters
df (
DataFrame
) – DataFrame to alterref_vec (
str
) – column prefix of vector components to use as reference, e.g. ‘muon’ for columns [‘muon_pT’, ‘muon_eta’, ‘muon_phi’]
- Return type
None
-
lumin.data_processing.hep_proc.
fix_event_z
(df, ref_vec)[source]¶ Flip event in z-axis such that ref_vec is in positive z-direction. Performed inplace. Works for both pT, eta, phi and Cartesian coordinates.
- Parameters
df (
DataFrame
) – DataFrame to alterref_vec (
str
) – column prefix of vector components to use as reference, e.g. ‘muon’ for columns [‘muon_pT’, ‘muon_eta’, ‘muon_phi’]
- Return type
None
-
lumin.data_processing.hep_proc.
fix_event_y
(df, ref_vec_0, ref_vec_1)[source]¶ Flip event in y-axis such that ref_vec_1 has a higher py than ref_vec_0. Performed in place. Works for both pT, eta, phi and Cartesian coordinates.
- Parameters
df (
DataFrame
) – DataFrame to alterref_vec_0 (
str
) – column prefix of vector components to use as reference 0, e.g. ‘muon’ for columns [‘muon_pT’, ‘muon_eta’, ‘muon_phi’]ref_vec_1 (
str
) – column prefix of vector components to use as reference 1, e.g. ‘muon’ for columns [‘muon_pT’, ‘muon_eta’, ‘muon_phi’]
- Return type
None
-
lumin.data_processing.hep_proc.
event_to_cartesian
(df, drop=False, ignore=None)[source]¶ Convert entire event to Cartesian coordinates, except vectors listed in ignore. Optionally, drop old pT,eta,phi features. Perfomed inplace.
- Parameters
df (
DataFrame
) – DataFrame to alterdrop (
bool
) – whether to drop old coordinatesignore (
Optional
[List
[str
]]) – vectors to ignore when converting
- Return type
None
-
lumin.data_processing.hep_proc.
proc_event
(df, fix_phi=False, fix_y=False, fix_z=False, use_cartesian=False, ref_vec_0=None, ref_vec_1=None, keep_feats=None, default_vals=None)[source]¶ Process event: Pass data through inplace various conversions and drop uneeded columns. Data expected to consist of vectors defined in pT, eta, phi.
- Parameters
df (
DataFrame
) – DataFrame to alterfix_phi (
bool
) – whether to rotate events usingfix_event_phi()
fix_y – whether to flip events using
fix_event_y()
fix_z – whether to flip events using
fix_event_z()
use_cartesian – wether to convert vectors to Cartesian coordinates
ref_vec_0 (
Optional
[str
]) – column prefix of vector components to use as reference (0) for :meth:~lumin.data_prcoessing.hep.proc.fix_event_phi`,fix_event_y()
, andfix_event_z()
e.g. ‘muon’ for columns [‘muon_pT’, ‘muon_eta’, ‘muon_phi’]ref_vec_1 (
Optional
[str
]) – column prefix of vector components to use as reference 1 forfix_event_z()
, e.g. ‘muon’ for columns [‘muon_pT’, ‘muon_eta’, ‘muon_phi’]keep_feats (
Optional
[List
[str
]]) – columns to keep which would otherwise be droppeddefault_vals (
Optional
[List
[str
]]) – list of default values which might be used to represent missing vector components. These will be replaced with np.nan.
- Return type
None
-
lumin.data_processing.hep_proc.
calc_pair_mass
(df, masses, feat_map)[source]¶ Vectorised computation of invarient mass of pair of particles with given masses, using 3-momenta. Only works for vectors defined in Cartesian coordinates.
- Parameters
df (
DataFrame
) – DataFrame vector componentsmasses (
Union
[Tuple
[float
,float
],Tuple
[ndarray
,ndarray
]]) – tuple of masses of particles (either constant or different pair of masses per pair of particles)feat_map (
Dict
[str
,str
]) – dictionary mapping of requested momentum components to the features in df
- Return type
ndarray
- Returns
np.array of invarient masses
lumin.data_processing.pre_proc module¶
-
lumin.data_processing.pre_proc.
get_pre_proc_pipes
(norm_in=True, norm_out=False, pca=False, whiten=False, with_mean=True, with_std=True, n_components=None)[source]¶ Configure SKLearn Pipelines for processing inputs and targets with the requested transformations.
- Parameters
norm_in (
bool
) – whether to apply StandardScaler to inputsnorm_out (
bool
) – whether to apply StandardScaler to outputspca (
bool
) – whether to apply PCA to inputs. Perforemed prior to StandardScaler. No dimensionality reduction is applied, purely rotation.whiten (
bool
) – whether PCA should whiten inputs.with_mean (
bool
) – whether StandardScalers should shift means to 0with_std (
bool
) – whether StandardScalers should scale standard deviations to 1n_components (
Optional
[int
]) – if set, causes PCA to reduce the dimensionality of the input data
- Return type
Tuple
[Pipeline
,Pipeline
]- Returns
Pipeline for input data Pipeline for target data
-
lumin.data_processing.pre_proc.
fit_input_pipe
(df, cont_feats, savename=None, input_pipe=None, norm_in=True, pca=False, whiten=False, with_mean=True, with_std=True, n_components=None)[source]¶ Fit input pipeline to continuous features and optionally save.
- Parameters
df (
DataFrame
) – DataFrame with data to fit pipelinecont_feats (
Union
[str
,List
[str
]]) – (list of) column(s) to use as input data for fittingsavename (
Optional
[str
]) – if set will save the fitted Pipeline to with that name as Pickle (.pkl extension added automatically)input_pipe (
Optional
[Pipeline
]) – if set will fit, otherwise will instantiate a new Pipelinenorm_in (
bool
) – whether to apply StandardScaler to inputs. Only used if input_pipe is not set.pca (
bool
) – whether to apply PCA to inputs. Perforemed prior to StandardScaler. No dimensionality reduction is applied, purely rotation. Only used if input_pipe is not set.whiten (
bool
) – whether PCA should whiten inputs. Only used if input_pipe is not set.with_mean (
bool
) – whether StandardScalers should shift means to 0. Only used if input_pipe is not set.with_std (
bool
) – whether StandardScalers should scale standard deviations to 1. Only used if input_pipe is not set.n_components (
Optional
[int
]) – if set, causes PCA to reduce the dimensionality of the input data. Only used if input_pipe is not set.
- Return type
Pipeline
- Returns
Fitted Pipeline
-
lumin.data_processing.pre_proc.
fit_output_pipe
(df, targ_feats, savename=None, output_pipe=None, norm_out=True)[source]¶ Fit output pipeline to target features and optionally save. Have you thought about using a y_range for regression instead?
- Parameters
df (
DataFrame
) – DataFrame with data to fit pipelinetarg_feats (
Union
[str
,List
[str
]]) – (list of) column(s) to use as input data for fittingsavename (
Optional
[str
]) – if set will save the fitted Pipeline to with that name as Pickle (.pkl extension added automatically)output_pipe (
Optional
[Pipeline
]) – if set will fit, otherwise will instantiate a new Pipelinenorm_out (
bool
) – whether to apply StandardScaler to outputs . Only used if output_pipe is not set.
- Return type
Pipeline
- Returns
Fitted Pipeline
-
lumin.data_processing.pre_proc.
proc_cats
(train_df, cat_feats, val_df=None, test_df=None)[source]¶ Process categorical features in train_df to be valued 0->cardinality-1. Applied inplace. Applies same transformation to validation and testing data is passed. Will complain if validation or testing sets contain categories which are not present in the training data.
- Parameters
train_df (
DataFrame
) – DataFrame with the training data, which will also be used to specify all the categories to considercat_feats (
List
[str
]) – list of columns to use as categorical featuresval_df (
Optional
[DataFrame
]) – if set will apply the same category to code mapping to the validation data as was performed on the training datatest_df (
Optional
[DataFrame
]) – if set will apply the same category to code mapping to the testing data as was performed on the training data
- Return type
Tuple
[OrderedDict
,OrderedDict
]- Returns
ordered dictionary mapping categorical features to dictionaries mapping categories to codes ordered dictionary mapping categorical features to their cardinalities
Module contents¶
lumin.evaluation package¶
Submodules¶
lumin.evaluation.ams module¶
-
lumin.evaluation.ams.
calc_ams
(s, b, br=0, unc_b=0)[source]¶ Compute Approximate Median Significance (https://arxiv.org/abs/1007.1727)
- Parameters
s (
float
) – signal weightb (
float
) – background weightbr (
float
) – background offset biasunc_b (
float
) – fractional systemtatic uncertainty on background
- Return type
float
- Returns
Approximate Median Significance if b > 0 else -1
-
lumin.evaluation.ams.
calc_ams_torch
(s, b, br=0, unc_b=0)[source]¶ Compute Approximate Median Significance (https://arxiv.org/abs/1007.1727) using Tensor inputs
- Parameters
s (
Tensor
) – signal weightb (
Tensor
) – background weightbr (
float
) – background offset biasunc_b (
float
) – fractional systemtatic uncertainty on background
- Return type
Tensor
- Returns
Approximate Median Significance if b > 0 else 1e-18 * s
-
lumin.evaluation.ams.
ams_scan_quick
(df, wgt_factor=1, br=0, syst_unc_b=0, pred_name='pred', targ_name='gen_target', wgt_name='gen_weight')[source]¶ Scan accross a range of possible prediction thresholds in order to maximise the Approximate Median Significance (https://arxiv.org/abs/1007.1727). Note that whilst this method is quicker than
ams_scan_slow()
, it sufferes from float precison. Not recommended for final evaluation.- Parameters
df (
DataFrame
) – DataFrame containing prediction datawgt_factor (
float
) – factor to reweight signal and background weightsbr (
float
) – background offset biassyst_unc_b (
float
) – fractional systemtatic uncertainty on backgroundpred_name (
str
) – column to use as predictionstarg_name (
str
) – column to use as truth labels for signal and backgroundwgt_name (
str
) – column to use as weights for signal and background events
- Return type
Tuple
[float
,float
]- Returns
maximum AMS prediction threshold corresponding to maximum AMS
-
lumin.evaluation.ams.
ams_scan_slow
(df, wgt_factor=1, br=0, syst_unc_b=0, use_stat_unc=False, start_cut=0.9, min_events=10, pred_name='pred', targ_name='gen_target', wgt_name='gen_weight', show_prog=True)[source]¶ Scan accross a range of possible prediction thresholds in order to maximise the Approximate Median Significance (https://arxiv.org/abs/1007.1727). Note that whilst this method is slower than
ams_scan_quick()
, it does not suffer as much from float precison. Additionally it allows one to account for statistical uncertainty in AMS calculation.- Parameters
df (
DataFrame
) – DataFrame containing prediction datawgt_factor (
float
) – factor to reweight signal and background weightsbr (
float
) – background offset biassyst_unc_b (
float
) – fractional systemtatic uncertainty on backgrounduse_stat_unc (
bool
) – whether to account for the statistical uncertainty on the backgroundstart_cut (
float
) – minimum prediction to consider; useful for speeding up scanmin_events (
int
) – minimum number of background unscaled events required to pass thresholdpred_name (
str
) – column to use as predictionstarg_name (
str
) – column to use as truth labels for signal and backgroundwgt_name (
str
) – column to use as weights for signal and background eventsshow_prog (
bool
) – whether to display progress and ETA of scan
- Return type
Tuple
[float
,float
]- Returns
maximum AMS prediction threshold corresponding to maximum AMS
Module contents¶
lumin.inference package¶
Submodules¶
lumin.inference.summary_stat module¶
-
lumin.inference.summary_stat.
bin_binary_class_pred
(df, max_unc, consider_samples=None, step_sz=0.001, pred_name='pred', sample_name='gen_sample', compact_samples=False, class_name='gen_target', add_pure_signal_bin=False, max_unc_pure_signal=0.1)[source]¶ Define bin-edges for binning particle process samples as a function of event class prediction (signal | background) such that the statistical uncertainties on per bin yields are below max_unc for each considered sample.
- Parameters
df (
DataFrame
) – DataFrame containing the datamax_unc (
float
) – maximum fractional statisitcal uncertainty to allow when defining binsconsider_samples (
Optional
[List
[str
]]) – if set, only listed samples are considered when defining binsstep_sz (
float
) – resolution of scan along event predictionpred_name (
str
) – column to use as event class predictionsample_name (
str
) – column to use as particle process fo reach eventcompact_samples (
bool
) – if true, will not consider samples when computing bin edges, only the classclass_name (
str
) – name of column to use as class indicatoradd_pure_signal_bin (
bool
) – if true will attempt to add a bin which oonly contains signal (class 1) if the fractional bin-fill uncertainty would be less than max_unc_pure_signalmax_unc_pure_signal (
float
) – maximum fractional statisitcal uncertainty to allow when defining pure-signal bins
- Return type
List
[float
]- Returns
list of bin edges
Module contents¶
lumin.nn package¶
Subpackages¶
lumin.nn.callbacks package¶
Submodules¶
lumin.nn.callbacks.callback module¶
-
class
lumin.nn.callbacks.callback.
Callback
(model=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.abs_callback.AbsCallback
Base callback class from which other callbacks should inherit.
- Parameters
model (
Optional
[AbsModel
]) – model to refer to during trainingplot_settings (
PlotSettings
) – PlotSettings class
-
set_model
(model)[source]¶ Sets the callback’s model in order to allow the callback to access and adjust model parameters
- Parameters
model (
AbsModel
) – model to refer to during training- Return type
None
-
set_plot_settings
(plot_settings)[source]¶ Sets the plot settings for any plots produced by the callback
- Parameters
plot_settings (
PlotSettings
) – PlotSettings class- Return type
None
lumin.nn.callbacks.cyclic_callbacks module¶
-
class
lumin.nn.callbacks.cyclic_callbacks.
AbsCyclicCallback
(interp, param_range, cycle_mult=1, decrease_param=False, scale=1, model=None, nb=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Abstract class for callbacks affecting lr or mom
- Parameters
interp (
str
) – string representation of interpolation function. Either ‘linear’ or ‘cosine’.param_range (
Tuple
[float
,float
]) – minimum and maximum values for parametercycle_mult (
int
) – multiplicative factor for adjusting the cycle length after each cycle. E.g cycle_mult=1 keeps the same cycle length, cycle_mult=2 doubles the cycle length after each cycle.decrease_param (
bool
) – whether to begin by decreasing the parameter, otherwise begin by increasing itscale (
int
) – multiplicative factor for setting the initial number of epochs per cycle. E.g scale=1 means 1 epoch per cycle, scale=5 means 5 epochs per cycle.model (
Optional
[AbsModel
]) – model to refer to during trainingnb (
Optional
[int
]) – number of minibatches (iterations) to expect per epochplot_settings (
PlotSettings
) – PlotSettings class
-
on_batch_begin
(**kargs)[source]¶ Computes the new value for the optimiser parameter and returns it
- Return type
float
- Returns
new value for optimiser parameter
-
on_batch_end
(**kargs)[source]¶ Increments the callback’s progress through the cycle
- Return type
None
-
on_epoch_begin
(**kargs)[source]¶ Ensures the cycle_end flag is false when the epoch starts
- Return type
None
-
class
lumin.nn.callbacks.cyclic_callbacks.
CycleLR
(lr_range, interp='cosine', cycle_mult=1, decrease_param='auto', scale=1, model=None, nb=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.cyclic_callbacks.AbsCyclicCallback
Callback to cycle learning rate during training according to either: cosine interpolation for SGDR https://arxiv.org/abs/1608.03983 or linear interpolation for Smith cycling https://arxiv.org/abs/1506.01186
- Parameters
lr_range (
Tuple
[float
,float
]) – tuple of initial and final LRsinterp (
str
) – ‘cosine’ or ‘linear’ interpolationcycle_mult (
int
) – Multiplicative constant for altering the cycle length after each complete cycledecrease_param (
Union
[str
,bool
]) – whether to increase or decrease the LR (effectively reverses lr_range order), ‘auto’ selects according to interpscale (
int
) – Multiplicative constant for altering the length of a cycle. 1 corresponds to one cycle = one (sub-)epochmodel (
Optional
[AbsModel
]) –Model
to alter, alternatively callset_model()
.nb (
Optional
[int
]) – Number of batches in a (sub-)epochplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Examples::
>>> cosine_lr = CycleLR(lr_range=(0, 2e-3), cycle_mult=2, scale=1, ... interp='cosine', nb=100) >>> >>> cyclical_lr = CycleLR(lr_range=(2e-4, 2e-3), cycle_mult=1, scale=5, interp='linear', nb=100)
-
class
lumin.nn.callbacks.cyclic_callbacks.
CycleMom
(mom_range, interp='cosine', cycle_mult=1, decrease_param='auto', scale=1, model=None, nb=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.cyclic_callbacks.AbsCyclicCallback
Callback to cycle momentum (beta 1) during training according to either: cosine interpolation for SGDR https://arxiv.org/abs/1608.03983 or linear interpolation for Smith cycling https://arxiv.org/abs/1506.01186 By default is set to evolve in opposite direction to learning rate, a la https://arxiv.org/abs/1803.09820
- Parameters
mom_range (
Tuple
[float
,float
]) – tuple of initial and final momentainterp (
str
) – ‘cosine’ or ‘linear’ interpolationcycle_mult (
int
) – Multiplicative constant for altering the cycle length after each complete cycledecrease_param (
Union
[str
,bool
]) – whether to increase or decrease the momentum (effectively reverses mom_range order), ‘auto’ selects according to interpscale (
int
) – Multiplicative constant for altering the length of a cycle. 1 corresponds to one cycle = one (sub-)epochmodel (
Optional
[AbsModel
]) –Model
to alter, alternatively callset_model()
nb (
Optional
[int
]) – Number of batches in a (sub-)epochplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Examples::
>>> cyclical_mom = CycleMom(mom_range=(0.85 0.95), cycle_mult=1, ... scale=5, interp='linear', nb=100)
-
class
lumin.nn.callbacks.cyclic_callbacks.
OneCycle
(lengths, lr_range, mom_range=(0.85, 0.95), interp='cosine', model=None, nb=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.cyclic_callbacks.AbsCyclicCallback
Callback implementing Smith 1-cycle evolution for lr and momentum (beta_1) https://arxiv.org/abs/1803.09820 Default interpolation uses fastai-style cosine function. Automatically triggers early stopping on cycle completion.
- Parameters
lengths (
Tuple
[int
,int
]) – tuple of number of (sub-)epochs in first and second stages of cyclelr_range (
List
[float
]) – tuple of initial and final LRsmom_range (
Tuple
[float
,float
]) – tuple of initial and final momentainterp (
str
) – ‘cosine’ or ‘linear’ interpolationmodel (
Optional
[AbsModel
]) –Model
to alter, alternatively callset_model()
nb (
Optional
[int
]) – Number of batches in a (sub-)epochplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Examples::
>>> onecycle = OneCycle(lengths=(15, 30), lr_range=[1e-4, 1e-2], ... mom_range=(0.85, 0.95), interp='cosine', nb=100)
lumin.nn.callbacks.data_callbacks module¶
-
class
lumin.nn.callbacks.data_callbacks.
BinaryLabelSmooth
(coefs=0, model=None)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Callback for applying label smoothing to binary classes, based on https://arxiv.org/abs/1512.00567 Applies smoothing during both training and inference.
- Parameters
coefs (
Union
[float
,Tuple
[float
,float
]]) – Smoothing coefficients: 0->coef[0] 1->1-coef[1]. if passed float, coef[0]=coef[1]model (
Optional
[AbsModel
]) – not used, only for compatability
- Examples::
>>> lbl_smooth = BinaryLabelSmooth(0.1) >>> >>> lbl_smooth = BinaryLabelSmooth((0.1, 0.02))
-
class
lumin.nn.callbacks.data_callbacks.
SequentialReweight
(reweight_func, scale=0.1, model=None)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Caution
Experiemntal proceedure
During ensemble training, sequentially reweight training data in last validation fold based on prediction performance of last trained model. Reweighting highlights data which are easier or more difficult to predict to the next model being trained.
- Parameters
reweight_func (
Callable
[[Tensor
,Tensor
],Tensor
]) – callable function returning a tensor of same shape as targets, ideally quantifying model-prediction performancescale (
float
) – multiplicative factor for rescaling returned tensor of reweight_funcmodel (
Optional
[AbsModel
]) –Model
to provide predictions, alternatively callset_model()
- Examples::
>>> seq_reweight = SequentialReweight( ... reweight_func=nn.BCELoss(reduction='none'), scale=0.1)
-
on_train_end
(fy, val_id, **kargs)[source]¶ Reweighs the validation fold once training is finished
- Parameters
fy (
FoldYielder
) – FoldYielder providing the training and validation datafold_id – Fold index which was used for validation
- Return type
None
-
class
lumin.nn.callbacks.data_callbacks.
SequentialReweightClasses
(reweight_func, scale=0.1, model=None)[source]¶ Bases:
lumin.nn.callbacks.data_callbacks.SequentialReweight
Caution
Experiemntal proceedure
Version of
SequentialReweight
designed for classification, which renormalises class weights to original weight-sum after reweighting During ensemble training, sequentially reweight training data in last validation fold based on prediction performance of last trained model. Reweighting highlights data which are easier or more difficult to predict to the next model being trained.- Parameters
reweight_func (
Callable
[[Tensor
,Tensor
],Tensor
]) – callable function returning a tensor of same shape as targets, ideally quantifying model-prediction performancescale (
float
) – multiplicative factor for rescaling returned tensor of reweight_funcmodel (
Optional
[AbsModel
]) –Model
to provide predictions, alternatively callset_model()
- Examples::
>>> seq_reweight = SequentialReweight( ... reweight_func=nn.BCELoss(reduction='none'), scale=0.1)
-
class
lumin.nn.callbacks.data_callbacks.
BootstrapResample
(n_folds, bag_each_time=False, reweight=True, model=None)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Callback for bootstrap sampling new training datasets from original training data during (ensemble) training.
- Parameters
n_folds (
int
) – the number of folds present in trainingFoldYielder
bag_each_time (
bool
) – whether to sample a new set for each sub-epoch or to use the same sample each timereweight (
bool
) – whether to reweight the sampleed data to mathch the weight sum (per class) of the original datamodel (
Optional
[AbsModel
]) – not used, only for compatability
- Examples::
>>> bs_resample BootstrapResample(n_folds=len(train_fy))
-
on_epoch_begin
(by, **kargs)[source]¶ Resamples training data for new epoch
- Parameters
by (
BatchYielder
) – BatchYielder providing data for the upcoming epoch- Return type
None
-
class
lumin.nn.callbacks.data_callbacks.
FeatureSubsample
(cont_feats, model=None)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Callback for training a model on a random sub-sample of the range of possible input features. Only sub-samples continuous features. Number of continuous inputs infered from model. Associated
Model
will automatically mask its inputs during inference; simply provide inputs with the same number of columns as trainig data.- Parameters
cont_feats (
List
[str
]) – list of all continuous features in input data. Order must match.model (
Optional
[AbsModel
]) –Model
being trained, alternatively callset_model()
- Examples::
>>> feat_subsample = FeatureSubsample(cont_feats=['pT', 'eta', 'phi'])
-
on_epoch_begin
(by, **kargs)[source]¶ Masks input data to remove non-selected features
- Parameters
by (
BatchYielder
) – BatchYielder providing data for the upcoming epoch- Return type
None
lumin.nn.callbacks.loss_callbacks module¶
-
class
lumin.nn.callbacks.loss_callbacks.
GradClip
(clip, clip_norm=True, model=None)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Callback for clipping gradients by norm or value.
- Parameters
clip (
float
) – value to clip atclip_norm (
bool
) – whether to clip according to norm (torch.nn.utils.clip_grad_norm_) or value (torch.nn.utils.clip_grad_value_)model (
Optional
[AbsModel
]) –Model
with parameters to clip gradients, alternatively callset_model()
- Examples::
>>> grad_clip = GradClip(1e-5)
lumin.nn.callbacks.model_callbacks module¶
-
class
lumin.nn.callbacks.model_callbacks.
SWA
(start_epoch, renewal_period=-1, model=None, val_fold=None, cyclic_callback=None, update_on_cycle_end=None, verbose=False, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.model_callbacks.AbsModelCallback
Callback providing Stochastic Weight Averaging based on (https://arxiv.org/abs/1803.05407) This adapted version allows the tracking of a pair of average models in order to avoid having to hardcode a specific start point for averaging:
Model average x0 will begin to be tracked start_epoch (sub-)epochs/cycles after training begins.
cycle_since_replacement is set to 1
Renewal_period (sub-)epochs/cycles later, a second average x1 will be tracked.
At the next renewal period, the performance of x0 and x1 will be compared on data contained in val_fold.
- If x0 is better than x1:
x1 is replaced by a copy of the current model
cycle_since_replacement is increased by 1
renewal_period is multiplied by cycle_since_replacement
- Else:
x0 is replaced by x1
x1 is replaced by a copy of the current model
cycle_since_replacement is set to 1
renewal_period is set back to its original value
Additonally, will optionally (default True) lock-in to any cyclical callbacks to only update at the end of a cycle.
- Parameters
start_epoch (
int
) – (sub-)epoch/cycle to begin averagingrenewal_period (
int
) – How often to check performance of averages, and renew tracking of least performantmodel (
Optional
[AbsModel
]) –Model
to provide parameters, alternatively callset_model()
val_fold (
Optional
[Dict
[str
,ndarray
]]) – Dictionary containing inputs, targets, and weights (or None) as Numpy arrayscyclic_callback (
Optional
[AbsCyclicCallback
]) – Optional for any cyclical callback which is runningupdate_on_cycle_end (
Optional
[bool
]) – Whether to lock in to the cyclic callback and only update at the end of a cycle. Default yes, if cyclic callback present.verbose (
bool
) – Whether to print out update information for testing and operation confirmationplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Examples::
>>> swa = SWA(start_epoch=5, renewal_period=5)
-
get_loss
()[source]¶ Evaluates SWA model and returns loss
- Return type
float
- Returns
Loss on validation fold for oldest SWA average
-
class
lumin.nn.callbacks.model_callbacks.
AbsModelCallback
(model=None, val_fold=None, cyclic_callback=None, update_on_cycle_end=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Abstract class for callbacks which provide alternative models during training
- Parameters
model (
Optional
[AbsModel
]) –Model
to provide parameters, alternatively callset_model()
val_fold (
Optional
[Dict
[str
,ndarray
]]) – Dictionary containing inputs, targets, and weights (or None) as Numpy arrayscyclic_callback (
Optional
[AbsCyclicCallback
]) – Optional for any cyclical callback which is runningupdate_on_cycle_end (
Optional
[bool
]) – Whether to lock in to the cyclic callback and only update at the end of a cycle. Default yes, if cyclic callback present.plot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
lumin.nn.callbacks.opt_callbacks module¶
-
class
lumin.nn.callbacks.opt_callbacks.
LRFinder
(nb, lr_bounds=[1e-07, 10], model=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Bases:
lumin.nn.callbacks.callback.Callback
Callback class for Smith learning-rate range test (https://arxiv.org/abs/1803.09820)
- Parameters
nb (
int
) – number of batches in a (sub-)epochlr_bounds (
Tuple
[float
,float
]) – tuple of initial and final LRmodel (
Optional
[AbsModel
]) –Model
to alter, alternatively callset_model()
plot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
-
on_batch_end
(loss, **kargs)[source]¶ Records loss and increments LR
- Parameters
loss (
float
) – training loss for most recent batch
Module contents¶
lumin.nn.data package¶
Submodules¶
lumin.nn.data.batch_yielder module¶
-
class
lumin.nn.data.batch_yielder.
BatchYielder
(inputs, targets, bs, objective, weights=None, shuffle=True, use_weights=True, bulk_move=True)[source]¶ Bases:
object
Yields minibatches to model during training. Iteration provides one minibatch as tuple of tensors of inputs, targets, and weights.
- Parameters
inputs (
ndarray
) – input array for (sub-)epochtargets (
ndarray
) – targte array for (sub-)epochbs (
int
) – batchsize, number of data to include per minibatchobjective (
str
) – ‘classification’, ‘multiclass classification’, or ‘regression’. Used for casting target dtype.weights (
Optional
[ndarray
]) – Optional weight array for (sub-)epochshuffle – whether to shuffle the data at the beginning of an iteration
use_weights (
bool
) – if passed weights, whether to actually pass them to the modelbulk_move – whether to move all data to device at once. Default is true (saves time), but if device has low memory you can set to False.
lumin.nn.data.fold_yielder module¶
-
class
lumin.nn.data.fold_yielder.
FoldYielder
(foldfile, cont_feats, cat_feats, ignore_feats=None, input_pipe=None, output_pipe=None)[source]¶ Bases:
object
Interface class for accessing data from foldfiles created by
df2foldfile()
- Parameters
foldfile (
File
) – filename of hdf5 filecont_feats (
List
[str
]) – list of names of continuous features present in input datacat_feats (
List
[str
]) – list of names of categorical features present in input dataignore_feats (
Optional
[List
[str
]]) – optional list of input features which should be ignoredinput_pipe (
Union
[str
,Pipeline
,None
]) – optional Pipeline, or filename for pickled Pipeline, which was used for processing the inputsoutput_pipe (
Union
[str
,Pipeline
,None
]) – optional Pipeline, or filename for pickled Pipeline, which was used for processing the targets
- Examples::
>>> fy = FoldYielder('train.h5', cont_feats=['pT','eta','phi','mass'], ... cat_feats=['channel'], ignore_feats=['phi'], ... input_pipe='input_pipe.pkl')
-
add_ignore
(feats)[source]¶ Add features to ignored features.
- Parameters
feats (
List
[str
]) – list of feature names to ignore- Return type
None
-
add_input_pipe
(input_pipe)[source]¶ Adds an input pipe to the FoldYielder for use when deprocessing data
- Parameters
input_pipe (
Pipeline
) – Pipeline which was used for preprocessing the input data- Return type
None
-
add_input_pipe_from_file
(name)[source]¶ Adds an input pipe from a pkl file to the FoldYielder for use when deprocessing data
- Parameters
name (
str
) – name of pkl file containing Pipeline which was used for preprocessing the input data- Return type
None
-
add_output_pipe
(output_pipe)[source]¶ Adds an output pipe to the FoldYielder for use when deprocessing data
- Parameters
output_pipe (
Pipeline
) – Pipeline which was used for preprocessing the target data- Return type
None
-
add_output_pipe_from_file
(name)[source]¶ Adds an output pipe from a pkl file to the FoldYielder for use when deprocessing data
- Parameters
name (
str
) – name of pkl file containing Pipeline which was used for preprocessing the target data- Return type
None
-
get_column
(column, n_folds=None, fold_idx=None, add_newaxis=False)[source]¶ Load column (h5py group) from foldfile. Used for getting arbitrary data which isn’t automatically grabbed by other methods.
- Parameters
column (
str
) – name of h5py group to getn_folds (
Optional
[int
]) – number of folds to get data from. Default all folds. Not compatable with fold_idxfold_idx (
Optional
[int
]) – Only load group from a single, specified fold. Not compatable with n_foldsadd_newaxis (
bool
) – whether expand shape of returned data if data shape is ()
- Return type
Optional
[ndarray
]- Returns
Numpy array of column data
-
get_data
(n_folds=None, fold_idx=None)[source]¶ Get data for single, specified fold or several of folds. Data consists of dictionary of inputs, targets, and weights. Does not accounts for ignored features. Inputs are passed through np.nan_to_num to deal with nans and infs.
- Parameters
n_folds (
Optional
[int
]) – number of folds to get data from. Default all folds. Not compatable with fold_idxfold_idx (
Optional
[int
]) – Only load group from a single, specified fold. Not compatable with n_folds
- Return type
Dict
[str
,ndarray
]- Returns
tuple of inputs, targets, and weights as Numpy arrays
-
get_df
(pred_name='pred', targ_name='targets', wgt_name='weights', n_folds=None, fold_idx=None, inc_inputs=False, inc_ignore=False, deprocess=False, verbose=True, suppress_warn=False)[source]¶ Get a Pandas DataFrameof the data in the foldfile. Will add columns for inputs (if requested), targets, weights, and predictions (if present)
- Parameters
pred_name (
str
) – name of prediction grouptarg_name (
str
) – name of target groupwgt_name (
str
) – name of weight groupn_folds (
Optional
[int
]) – number of folds to get data from. Default all folds. Not compatable with fold_idxfold_idx (
Optional
[int
]) – Only load group from a single, specified fold. Not compatable with n_foldsinc_inputs (
bool
) – whether to include input datainc_ignore (
bool
) – whether to include ignored featuresdeprocess (
bool
) – whether to deprocess inputs and targets if pipelines have beenverbose (
bool
) – whether to print the number of datapoints loadedsuppress_warn (
bool
) – whether to supress the warning about missing columns
- Return type
DataFrame
- Returns
Pandas DataFrame with requested data
-
get_fold
(idx)[source]¶ Get data for single fold. Data consists of dictionary of inputs, targets, and weights. Accounts for ignored features. Inputs are passed through np.nan_to_num to deal with nans and infs.
- Parameters
idx (
int
) – fold index to load- Return type
Dict
[str
,ndarray
]- Returns
tuple of inputs, targets, and weights as Numpy arrays
-
get_ignore
()[source]¶ Returns list of ignored features
- Return type
List
[str
]- Returns
Features removed from training data
-
save_fold_pred
(pred, fold_idx, pred_name='pred')[source]¶ Save predictions for given fold as a new column in the foldfile
- Parameters
pred (
ndarray
) – array of predictions in the same order as data appears in the filefold_idx (
int
) – index for foldpred_name (
str
) – name of column to save predictions under
- Return type
None
-
class
lumin.nn.data.fold_yielder.
HEPAugFoldYielder
(foldfile, cont_feats, cat_feats, ignore_feats=None, targ_feats=None, rot_mult=2, random_rot=False, reflect_x=False, reflect_y=True, reflect_z=True, train_time_aug=True, test_time_aug=True, input_pipe=None, output_pipe=None)[source]¶ Bases:
lumin.nn.data.fold_yielder.FoldYielder
Specialised version of
FoldYielder
providing HEP specific data augmetation at train and test time.- Parameters
foldfile (
File
) – filename of hdf5 filecont_feats (
List
[str
]) – list of names of continuous features present in input datacat_feats (
List
[str
]) – list of names of categorical features present in input dataignore_feats (
Optional
[List
[str
]]) – optional list of input features which should be ignoredtarg_feats (
Optional
[List
[str
]]) – optional list of target features to also be transformedrot_mult (
int
) – number of rotations of event in phi to make at test-time (currently must be even). Greater than zero will also apply random rotations during train-timerandom_rot (
bool
) – whether test-time rotation angles should be random or in steps of 2pi/rot_multreflect_x (
bool
) – whether to reflect events in x axis at train and test timereflect_y (
bool
) – whether to reflect events in y axis at train and test timereflect_z (
bool
) – whether to reflect events in z axis at train and test timetrain_time_aug (
bool
) – whether to apply augmentations at train timetest_time_aug (
bool
) – whether to apply augmentations at test timeinput_pipe (
Optional
[Pipeline
]) – optional Pipeline, or filename for pickled Pipeline, which was used for processing the inputsoutput_pipe (
Optional
[Pipeline
]) – optional Pipeline, or filename for pickled Pipeline, which was used for processing the targets
- Examples::
>>> fy = HEPAugFoldYielder('train.h5', ... cont_feats=['pT','eta','phi','mass'], ... rot_mult=2, reflect_y=True, reflect_z=True, ... input_pipe='input_pipe.pkl')
-
get_fold
(idx)[source]¶ Get data for single fold applying random train-time data augmentaion. Data consists of dictionary of inputs, targets, and weights. Accounts for ignored features. Inputs are passed through np.nan_to_num to deal with nans and infs.
- Parameters
idx (
int
) – fold index to load- Return type
Dict
[str
,ndarray
]- Returns
tuple of inputs, targets, and weights as Numpy arrays
-
get_test_fold
(idx, aug_idx)[source]¶ Get test data for single fold applying test-time data augmentaion. Data consists of dictionary of inputs, targets, and weights. Accounts for ignored features. Inputs are passed through np.nan_to_num to deal with nans and infs.
- Parameters
idx (
int
) – fold index to loadaug_idx (
int
) – index for the test-time augmentaion (ignored if random test-time augmentation requested)
- Return type
Dict
[str
,ndarray
]- Returns
tuple of inputs, targets, and weights as Numpy arrays
Module contents¶
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.- 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_ouput_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
-
build_ensemble
(results, size, model_builder, metric='loss', weighting='reciprocal', higher_metric_better=False, snapshot_args=None, location=PosixPath('train_weights'), verbose=True)[source]¶ Load up an instantiated
Ensemble
with outputs offold_train_ensemble()
- 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
location (
Path
) – Path to save location passed tofold_train_ensemble()
verbose (
bool
) – whether to print out information of models loaded
- Examples::
>>> ensemble.build_ensemble(results, 10, model_builder, ... location=Path('train_weights')) >>> >>> ensemble.build_ensemble( ... 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})
- 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_results
(results, size, model_builder, metric='loss', weighting='reciprocal', higher_metric_better=False, snapshot_args=None, location=PosixPath('train_weights'), 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
location (
Path
) – Path to save location passed tofold_train_ensemble()
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, eval_metric=None)[source]¶ Call
get_ensemble_feat_importance()
, passing thisEnsemble
and provided arguments- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to data on which to evaluate importanceeval_metric (
Optional
[EvalMetric
]) – OptionalEvalMetric
to use for quantifying performance
- 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')[source]¶ Compatability method for predicting data contained in either a Numpy array or a
FoldYielder
Will either pass inputs tolumin.nn.ensemble.ensemble.Ensemble.predict_array()
orlumin.nn.ensemble.ensemble.Ensemble.predict_folds()
.- Parameters
inputs (
Union
[ndarray
,FoldYielder
,List
[ndarray
]]) – either aFoldYielder
interfacing with the input data, or the input data as an arrayn_models (
Optional
[int
]) – number of models to use in predictions as ranked by the metric which was used when constructing theEnsemble
. By default, entire ensemble is used.pred_name (
str
) – name for new group of predictions if passed aFoldYielder
- Return type
Union
[None
,ndarray
]- Returns
If passed a Numpy array will return predictions.
- Examples::
>>> preds = ensemble.predict(input_array) >>> >>> ensemble.predict(test_fy)
-
predict_array
(arr, n_models=None, parent_bar=None, display=True)[source]¶ Apply ensemble to Numpy array and get predictions. If an output pipe has been added to the ensemble, then the predictions will be deprocessed. Inputs are expected to be preprocessed; i.e. any input pipe added to the ensemble is not used.
- Parameters
arr (
ndarray
) – input datan_models (
Optional
[int
]) – number of models to use in predictions as ranked by the metric which was used when constructing theEnsemble
. By default, entire ensemble is used.parent_bar (
Optional
[ConsoleMasterBar
]) – not used when calling the method directlydisplay (
bool
) – whether to display a progress bar for model evaluations
- Return type
ndarray
- Returns
Numpy array of predictions
- Examples::
>>> preds = ensemble.predict_array(inputs)
-
predict_folds
(fy, n_models=None, pred_name='pred')[source]¶ Apply ensemble to data accessed by a
FoldYielder
and save predictions as a new group per fold in the foldfile. If an output pipe has been added to the ensemble, then the predictions will be deprocessed. Inputs are expected to be preprocessed; i.e. any input pipe added to the ensemble is not used. If foldyielder has test-time augmentation, then predictions will be averaged over all augmentated forms of the data.- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing with the input datan_models (
Optional
[int
]) – number of models to use in predictions as ranked by the metric which was used when constructing theEnsemble
. By default, entire ensemble is used.pred_name (
str
) – name for new group of predictions
- Examples::
>>> ensemble.predict_array(test_fy, pred_name='pred_tta')
- Return type
None
-
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
Module contents¶
lumin.nn.interpretation package¶
Submodules¶
lumin.nn.interpretation.features module¶
-
lumin.nn.interpretation.features.
get_nn_feat_importance
(model, fy, eval_metric=None, pb_parent=None, plot=True, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Compute permutation importance of features used by a
Model
on provided data using either loss or anEvalMetric
to quantify performance. Returns bootstrapped mean importance from sample constructed by computing importance for each fold in fy.- Parameters
model (
AbsModel
) –Model
to use to evaluate feature importancefy (
FoldYielder
) –FoldYielder
interfacing to data used to train modeleval_metric (
Optional
[EvalMetric
]) – OptionalEvalMetric
to use to quantify performance in place of losspb_parent (
Optional
[ConsoleMasterBar
]) – Not used if calling method directlyplot (
bool
) – whetehr to plot resulting feature importancessavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
DataFrame
- Returns
Pandas DataFrame containing mean importance and associated uncertainty for each feature
- Examples::
>>> fi = get_nn_feat_importance(model, train_fy) >>> >>> fi = get_nn_feat_importance(model, train_fy, savename='feat_import') >>> >>> fi = get_nn_feat_importance(model, train_fy, ... eval_metric=AMS(n_total=100000))
-
lumin.nn.interpretation.features.
get_ensemble_feat_importance
(ensemble, fy, eval_metric=None, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Compute permutation importance of features used by an
Ensemble
on provided data using either loss or anEvalMetric
to quantify performance. Returns bootstrapped mean importance from sample constructed by computing importance for eachModel
in ensemble.- Parameters
ensemble (
AbsEnsemble
) –Ensemble
to use to evaluate feature importancefy (
FoldYielder
) –FoldYielder
interfacing to data used to train models in ensembleeval_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 importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
DataFrame
- Returns
Pandas DataFrame containing mean importance and associated uncertainty for each feature
- Examples::
>>> fi = get_ensemble_feat_importance(ensemble, train_fy) >>> >>> fi = get_ensemble_feat_importance(ensemble, train_fy ... savename='feat_import') >>> >>> fi = get_ensemble_feat_importance(ensemble, train_fy, ... eval_metric=AMS(n_total=100000))
Module contents¶
lumin.nn.losses package¶
Submodules¶
lumin.nn.losses.basic_weighted module¶
-
class
lumin.nn.losses.basic_weighted.
WeightedMSE
(weight=None)[source]¶ Bases:
torch.nn.modules.loss.MSELoss
Class for computing Mean Squared-Error loss with optional weights per prediction. For compatability with using basic PyTorch losses, weights are passed during initialisation rather than when computing the loss.
- Parameters
weight (
Optional
[Tensor
]) – sample weights as PyTorch Tensor, to be used with data to be passed when computing the loss
- Examples::
>>> loss = WeightedMSE() >>> >>> loss = WeightedMSE(weights)
-
class
lumin.nn.losses.basic_weighted.
WeightedMAE
(weight=None)[source]¶ Bases:
torch.nn.modules.loss.L1Loss
Class for computing Mean Absolute-Error loss with optional weights per prediction. For compatability with using basic PyTorch losses, weights are passed during initialisation rather than when computing the loss.
- Parameters
weight (
Optional
[Tensor
]) – sample weights as PyTorch Tensor, to be used with data to be passed when computing the loss
- Examples::
>>> loss = WeightedMAE() >>> >>> loss = WeightedMAE(weights)
-
class
lumin.nn.losses.basic_weighted.
WeightedCCE
(weight=None)[source]¶ Bases:
torch.nn.modules.loss.NLLLoss
Class for computing Categorical Cross-Entropy loss with optional weights per prediction. For compatability with using basic PyTorch losses, weights are passed during initialisation rather than when computing the loss.
- Parameters
weight (
Optional
[Tensor
]) – sample weights as PyTorch Tensor, to be used with data to be passed when computing the loss
- Examples::
>>> loss = WeightedCCE() >>> >>> loss = WeightedCCE(weights)
lumin.nn.losses.hep_losses module¶
-
class
lumin.nn.losses.hep_losses.
SignificanceLoss
(weight, sig_wgt=<class 'float'>, bkg_wgt=<class 'float'>, func=typing.Callable[[torch.Tensor, torch.Tensor], torch.Tensor])[source]¶ Bases:
torch.nn.modules.module.Module
General class for implementing significance-based loss functions, e.g. Asimov Loss (https://arxiv.org/abs/1806.00322). For compatability with using basic PyTorch losses, event weights are passed during initialisation rather than when computing the loss.
- Parameters
weight (
Tensor
) – sample weights as PyTorch Tensor, to be used with data to be passed when computing the losssig_wgt – total weight of signal events
bkg_wgt – total weight of background events
func – callable which returns a float based on signal and background weights
- Examples::
>>> loss = SignificanceLoss(weight, sig_weight=sig_weight, ... bkg_weight=bkg_weight, func=calc_ams_torch) >>> >>> loss = SignificanceLoss(weight, sig_weight=sig_weight, ... bkg_weight=bkg_weight, ... func=partial(calc_ams_torch, br=10))
Module contents¶
lumin.nn.metrics package¶
Submodules¶
lumin.nn.metrics.class_eval module¶
-
class
lumin.nn.metrics.class_eval.
AMS
(n_total, wgt_name, targ_name='targets', br=0, syst_unc_b=0, use_quick_scan=True)[source]¶ Bases:
lumin.nn.metrics.eval_metric.EvalMetric
Class to compute maximum Approximate Median Significance (https://arxiv.org/abs/1007.1727) using classifier which directly predicts the class of data in a binary classifiaction problem. AMS is computed on a single fold of data provided by a
FoldYielder
and automatically reweights data by event multiplicity to account missing weights.- Parameters
n_total (
int
) – total number of events in entire data setwgt_name (
str
) – name of weight group in fold file to use. N.B. if you have reweighted to balance classes, be sure to use the un-reweighted weights.targ_name (
str
) – name of target group in fold filebr (
float
) – constant bias offset for background yieldsyst_unc_b (
float
) – fractional systematic uncertainty on background yielduse_quick_scan (
bool
) – whether to optimise AMS by theams_scan_quick()
method (fast but suffers floating point precision) if False useams_scan_slow()
(slower but more accurate)
- Examples::
>>> ams_metric = AMS(n_total=250000, br=10, wgt_name='gen_orig_weight') >>> >>> ams_metric = AMS(n_total=250000, syst_unc_b=0.1, ... wgt_name='gen_orig_weight', use_quick_scan=False)
-
evaluate
(fy, idx, y_pred)[source]¶ Compute maximum AMS on fold using provided predictions.
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to dataidx (
int
) – fold index corresponding to fold for which y_pred was computedy_pred (
ndarray
) – predictions for fold
- Return type
float
- Returns
Maximum AMS computed on reweighted data from fold
- Examples::
>>> ams = ams_metric.evaluate(train_fy, val_id, val_preds)
-
class
lumin.nn.metrics.class_eval.
MultiAMS
(n_total, wgt_name, targ_name, zero_preds, one_preds, br=0, syst_unc_b=0, use_quick_scan=True)[source]¶ Bases:
lumin.nn.metrics.class_eval.AMS
Class to compute maximum Approximate Median Significance (https://arxiv.org/abs/1007.1727) using classifier which predicts the class of data in a multiclass classifiaction problem which can be reduced to a binary classification problem AMS is computed on a single fold of data provided by a
FoldYielder
and automatically reweights data by event multiplicity to account missing weights.- Parameters
n_total (
int
) – total number of events in entire data setwgt_name (
str
) – name of weight group in fold file to use. N.B. if you have reweighted to balance classes, be sure to use the un-reweighted weights.targ_name (
str
) – name of target group in fold file which indicates whether the event is signal or backgroundzero_preds (
List
[str
]) – list of predicted classes which correspond to class 0 in the form pred_[i], where i is a NN output indexone_preds (
List
[str
]) – list of predicted classes which correspond to class 1 in the form pred_[i], where i is a NN output indexbr (
float
) – constant bias offset for background yieldsyst_unc_b (
float
) – fractional systematic uncertainty on background yielduse_quick_scan (
bool
) – whether to optimise AMS by theams_scan_quick()
method (fast but suffers floating point precision) if False useams_scan_slow()
(slower but more accurate)
- Examples::
>>> ams_metric = MultiAMS(n_total=250000, br=10, targ_name='gen_target', ... wgt_name='gen_orig_weight', ... zero_preds=['pred_0', 'pred_1', 'pred_2'], ... one_preds=['pred_3']) >>> >>> ams_metric = MultiAMS(n_total=250000, syst_unc_b=0.1, ... targ_name='gen_target', ... wgt_name='gen_orig_weight', ... use_quick_scan=False, ... zero_preds=['pred_0', 'pred_1', 'pred_2'], ... one_preds=['pred_3'])
-
evaluate
(fy, idx, y_pred)[source]¶ Compute maximum AMS on fold using provided predictions.
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to dataidx (
int
) – fold index corresponding to fold for which y_pred was computedy_pred (
ndarray
) – predictions for fold
- Return type
float
- Returns
Maximum AMS computed on reweighted data from fold
- Examples::
>>> ams = ams_metric.evaluate(train_fy, val_id, val_preds)
lumin.nn.metrics.eval_metric module¶
-
class
lumin.nn.metrics.eval_metric.
EvalMetric
(targ_name, wgt_name=None)[source]¶ Bases:
abc.ABC
Abstract class for evaluating performance of a model using some metric
- Parameters
targ_name (
str
) – name of group in fold file containing regression targetswgt_name (
Optional
[str
]) – name of group in fold file containing datapoint weights
-
abstract
evaluate
(fy, idx, y_pred)[source]¶ Evaluate the required metric for a given fold and set of predictions
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to dataidx (
int
) – fold index corresponding to fold for which y_pred was computedy_pred (
ndarray
) – predictions for fold
- Return type
float
- Returns
metric value
-
get_df
(fy, idx, y_pred)[source]¶ Returns a DataFrame for the given fold containing targets, weights, and predictions
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to dataidx (
int
) – fold index corresponding to fold for which y_pred was computedy_pred (
ndarray
) – predictions for fold
- Return type
DataFrame
- Returns
DataFrame for the given fold containing targets, weights, and predictions
lumin.nn.metrics.reg_eval module¶
-
class
lumin.nn.metrics.reg_eval.
RegPull
(return_mean, use_bootstrap=False, use_weights=True, use_pull=True, targ_name='targets', wgt_name=None)[source]¶ Bases:
lumin.nn.metrics.eval_metric.EvalMetric
Compute mean or standard deviation of delta or pull of some feature which is being directly regressed to. Optionally, use bootstrap resampling on validation data.
- Parameters
return_mean (
bool
) – whether to return the mean or the standard deviationuse_bootstrap (
bool
) – whether to bootstrap resamples validation fold when computing statisiticuse_weights (
bool
) – whether to actually use weights if wgt_name is setuse_pull (
bool
) – whether to return the pull (differences / targets) or delta (differences)targ_name (
str
) – name of group in fold file containing regression targetswgt_name (
Optional
[str
]) – name of group in fold file containing datapoint weights
- Examples::
>>> mean_pull = RegPull(return_mean=True, use_bootstrap=True, ... use_pull=True) >>> >>> std_delta = RegPull(return_mean=False, use_bootstrap=True, ... use_pull=False) >>> >>> mean_pull = RegPull(return_mean=True, use_bootstrap=False, ... use_pull=True, wgt_name='weights')
-
evaluate
(fy, idx, y_pred)[source]¶ Compute statisitic on fold using provided predictions.
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to dataidx (
int
) – fold index corresponding to fold for which y_pred was computedy_pred (
ndarray
) – predictions for fold
- Return type
float
- Returns
Statistic set in initialisation computed on the chsoen fold
- Examples::
>>> mean = mean_pull.evaluate(train_fy, val_id, val_preds)
-
class
lumin.nn.metrics.reg_eval.
RegAsProxyPull
(proxy_func, return_mean, use_bootstrap=False, use_weights=True, use_pull=True, targ_name='targets', wgt_name=None)[source]¶ Bases:
lumin.nn.metrics.reg_eval.RegPull
Compute mean or standard deviation of delta or pull of some feature which is being indirectly regressed to via a proxy function. Optionally, use bootstrap resampling on validation data.
- Parameters
proxy_func (
Callable
[[DataFrame
],None
]) – function which acts on regression predictions and adds pred and gen_target columns to the Pandas DataFrame it is passed which contains prediction columns pred_{i}return_mean (
bool
) – whether to return the mean or the standard deviationuse_bootstrap (
bool
) – whether to bootstrap resamples validation fold when computing statisiticuse_weights (
bool
) – whether to actually use weights if wgt_name is setuse_pull (
bool
) – whether to return the pull (differences / targets) or delta (differences)targ_name (
str
) – name of group in fold file containing regression targetswgt_name (
Optional
[str
]) – name of group in fold file containing datapoint weights
- Examples::
>>> def reg_proxy_func(df): >>> df['pred'] = calc_pair_mass(df, (1.77682, 1.77682), ... {targ[targ.find('_t')+3:]: ... f'pred_{i}' for i, targ ... in enumerate(targ_feats)}) >>> df['gen_target'] = 125 >>> >>> std_delta = RegAsProxyPull(proxy_func=reg_proxy_func, ... return_mean=False, use_pull=False)
-
evaluate
(fy, idx, y_pred)[source]¶ Compute statisitic on fold using provided predictions.
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to dataidx (
int
) – fold index corresponding to fold for which y_pred was computedy_pred (
ndarray
) – predictions for fold
- Return type
float
- Returns
Statistic set in initialisation computed on the chsoen fold
- Examples::
>>> mean = mean_pull.evaluate(train_fy, val_id, val_preds)
Module contents¶
lumin.nn.models package¶
Subpackages¶
lumin.nn.models.blocks package¶
-
class
lumin.nn.models.blocks.body.
FullyConnected
(n_in, feat_map, depth, width, do=0, bn=False, act='relu', res=False, dense=False, growth_rate=0, lookup_init=<function lookup_normal_init>, lookup_act=<function lookup_act>, freeze=False)[source]¶ Bases:
lumin.nn.models.blocks.body.AbsBody
Fully connected set of hidden layers. Designed to be passed as a ‘body’ to
ModelBuilder
. Supports batch normalisation and dropout. Order is dense->activation->BN->DO, except when res is true in which case the BN is applied after the addition. Can optionaly have skip connections between each layer (res=true). Alternatively can concatinate layers (dense=true) growth_rate parameter can be used to adjust the width of layers according to width+(width*(depth-1)*growth_rate)- Parameters
n_in (
int
) – number of inputs to the blockfeat_map (
Dict
[str
,List
[int
]]) – dictionary mapping input features to the model to outputs of head blockdepth (
int
) – number of hidden layers. If res==True and depth is even, depth will be increased by one.width (
int
) – base width of each hidden layerdo (
float
) – if not None will add dropout layers with dropout rates dobn (
bool
) – whether to use batch normalisationact (
str
) – string representation of argument to pass to lookup_actres (
bool
) – whether to add an additative skip connection every two dense layers. Mutually exclusive with dense.dense (
bool
) – whether to perform layer-wise concatinations after every layer. Mutually exclusion with res.growth_rate (
int
) – rate at which width of dense layers should increase with depth beyond the initial layer. Ignored if res=True. Can be negative.lookup_init (
Callable
[[str
,Optional
[int
],Optional
[int
]],Callable
[[Tensor
],None
]]) – function taking choice of activation function, number of inputs, and number of outputs an returning a function to initialise layer weights.lookup_act (
Callable
[[str
],Any
]) – function taking choice of activation function and returning an activation function layerfreeze (
bool
) – whether to start with module parameters set to untrainable
- Examples::
>>> body = FullyConnected(n_in=32, feat_map=head.feat_map, depth=4, ... width=100, act='relu') >>> >>> body = FullyConnected(n_in=32, feat_map=head.feat_map, depth=4, ... width=200, act='relu', growth_rate=-0.3) >>> >>> body = FullyConnected(n_in=32, feat_map=head.feat_map, depth=4, ... width=100, act='swish', do=0.1, res=True) >>> >>> body = FullyConnected(n_in=32, feat_map=head.feat_map, depth=6, ... width=32, act='selu', dense=True, ... growth_rate=0.5) >>> >>> body = FullyConnected(n_in=32, feat_map=head.feat_map, depth=6, ... width=50, act='prelu', bn=True, ... lookup_init=lookup_uniform_init)
-
class
lumin.nn.models.blocks.body.
MultiBlock
(n_in, feat_map, blocks, feats_per_block, bottleneck_sz=0, bottleneck_act=None, lookup_init=<function lookup_normal_init>, lookup_act=<function lookup_act>, freeze=False)[source]¶ Bases:
lumin.nn.models.blocks.body.AbsBody
Body block allowing outputs of head block to be split amongst a series of body blocks. Output is the concatination of all sub-body blocks. Optionally, single-neuron ‘bottleneck’ layers can be used to pass an input to each sub-block based on a learned function of the input features that block would otherwise not receive, i.e. a highly compressed representation of the rest of teh feature space.
- Parameters
n_in (
int
) – number of inputs to the blockfeat_map (
Dict
[str
,List
[int
]]) – dictionary mapping input features to the model to outputs of head blockblocks (
List
[partial
]) – list of uninstantciatedAbsBody
blocks to which to pass a subsection of the total inputs. Note that partials should be used to set any relevant parameters at initialisation timefeats_per_block (
List
[List
[str
]]) – list of lists of names of features to pass to eachAbsBody
, not that the feat_map provided byAbsHead
will map features to their relavant head outputsbottleneck – if true, each block will receive the output of a single neuron which takes as input all the features which each given block does not directly take as inputs
bottleneck_act (
Optional
[str
]) – if set to a string representation of an activation function, the output of each bottleneck neuron will be passed throguh the defined activation function before being passed to their associated blockslookup_init (
Callable
[[str
,Optional
[int
],Optional
[int
]],Callable
[[Tensor
],None
]]) – function taking choice of activation function, number of inputs, and number of outputs an returning a function to initialise layer weights.lookup_act (
Callable
[[str
],Any
]) – function taking choice of activation function and returning an activation function layerfreeze (
bool
) – whether to start with module parameters set to untrainable
- Examples::
>>> body = MultiBlock( ... blocks=[partial(FullyConnected, depth=1, width=50, act='swish'), ... partial(FullyConnected, depth=6, width=55, act='swish', ... dense=True, growth_rate=-0.1)], ... feats_per_block=[[f for f in train_feats if 'DER_' in f], ... [f for f in train_feats if 'PRI_' in f]]) >>> >>> body = MultiBlock( ... blocks=[partial(FullyConnected, depth=1, width=50, act='swish'), ... partial(FullyConnected, depth=6, width=55, act='swish', ... dense=True, growth_rate=-0.1)], ... feats_per_block=[[f for f in train_feats if 'DER_' in f], ... [f for f in train_feats if 'PRI_' in f]], ... bottleneck=True) >>> >>> body = MultiBlock( ... blocks=[partial(FullyConnected, depth=1, width=50, act='swish'), ... partial(FullyConnected, depth=6, width=55, act='swish', ... dense=True, growth_rate=-0.1)], ... feats_per_block=[[f for f in train_feats if 'DER_' in f], ... [f for f in train_feats if 'PRI_' in f]], ... bottleneck=True, bottleneck_act='swish')
-
class
lumin.nn.models.blocks.endcap.
AbsEndcap
(model)[source]¶ Bases:
torch.nn.modules.module.Module
Abstract class for constructing post training layer which performs further calculation on NN outputs. Used when NN was trained to some proxy objective
- Parameters
model (
Module
) – trainedModel
to wrap
-
forward
(x)[source]¶ Pass tensor through endcap and compute function
- Parameters
x (
Tensor
) – model output tensor
- Returns
Resulting tensor
- Return type
Tensor
-
abstract
func
(x)[source]¶ Transformation functio to apply to model outputs
- Arguements:
x: model output tensor
- Return type
Tensor
- Returns
Resulting tensor
-
predict
(inputs, as_np=True)[source]¶ Evaluate model on input tensor, and comput function of model outputs
- Parameters
inputs (
Union
[ndarray
,DataFrame
,Tensor
]) – input data as Numpy array, Pandas DataFrame, or tensor on deviceas_np (
bool
) – whether to return predictions as Numpy array (otherwise tensor)
- Return type
Union
[ndarray
,Tensor
]- Returns
model predictions pass through endcap function
-
class
lumin.nn.models.blocks.head.
CatEmbHead
(cont_feats, do_cont=0, do_cat=0, cat_embedder=None, lookup_init=<function lookup_normal_init>, freeze=False)[source]¶ Bases:
lumin.nn.models.blocks.head.AbsHead
Standard model head for columnar data. Provides inputs for continuous features and embedding matrices for categorical inputs, and uses a dense layer to upscale to width of network body. Designed to be passed as a ‘head’ to
ModelBuilder
. Supports batch normalisation and dropout (at separate rates for continuous features and categorical embeddings). Continuous features are expected to be the first len(cont_feats) columns of input tensors and categorical features the remaining columns. Embedding arguments for categorical features are set using aCatEmbedder
.- Parameters
cont_feats (
List
[str
]) – list of names of continuous input featuresdo_cont (
float
) – if not None will add a dropout layer with dropout rate do acting on the continuous inputs prior to concatination wih the categorical embeddingsdo_cat (
float
) – if not None will add a dropout layer with dropout rate do acting on the categorical embeddings prior to concatination wih the continuous inputscat_embedder (
Optional
[CatEmbedder
]) –CatEmbedder
providing details of how to embed categorical inputslookup_init (
Callable
[[str
,Optional
[int
],Optional
[int
]],Callable
[[Tensor
],None
]]) – function taking choice of activation function, number of inputs, and number of outputs an returning a function to initialise layer weights.freeze (
bool
) – whether to start with module parameters set to untrainable
- Examples::
>>> head = CatEmbHead(cont_feats=cont_feats) >>> >>> head = CatEmbHead(cont_feats=cont_feats, ... cat_embedder=CatEmbedder.from_fy(train_fy)) >>> >>> head = CatEmbHead(cont_feats=cont_feats, ... cat_embedder=CatEmbedder.from_fy(train_fy), ... do_cont=0.1, do_cat=0.05) >>> >>> head = CatEmbHead(cont_feats=cont_feats, ... cat_embedder=CatEmbedder.from_fy(train_fy), ... lookup_init=lookup_uniform_init)
-
forward
(x_in)[source]¶ Pass tensor through head
- Parameters
x – input tensor
- Returns
Resulting tensor
- Return type
Tensor
-
get_embeds
()[source]¶ Get state_dict for every embedding matrix.
- Return type
Dict
[str
,OrderedDict
]- Returns
Dictionary mapping categorical features to learned embedding matrix
-
get_out_size
()[source]¶ Get size width of output layer
- Return type
int
- Returns
Width of output layer
-
plot_embeds
(savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot representations of embedding matrices for each categorical feature.
- Parameters
savename (
Optional
[str
]) – if not None, will save copy of plot to give pathsettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
class
lumin.nn.models.blocks.tail.
ClassRegMulti
(n_in, n_out, objective, y_range=None, bias_init=None, lookup_init=<function lookup_normal_init>, freeze=False)[source]¶ Bases:
lumin.nn.models.blocks.tail.AbsTail
Output block for (multi(class/label)) classification or regression tasks. Designed to be passed as a ‘tail’ to
ModelBuilder
. Takes output size of network body and scales it to required number of outputs. For regression tasks, y_range can be set with per-output minima and maxima. The outputs are then adjusted according to ((y_max-y_min)*x)+self.y_min, where x is the output of the network passed through a sigmoid function. Effectively allowing regression to be performed without normalising and standardising the target values. Note it is safest to allow some leaway in setting the min and max, e.g. max = 1.2*max, min = 0.8*min Output activation function is automatically set according to objective and y_range.- Parameters
n_in (
int
) – number of inputs to expectn_out (
int
) – number of outputs requiredobjective (
str
) – string representation of network objective, i.e. ‘classification’, ‘regression’, ‘multiclass’y_range (
Union
[Tuple
,ndarray
,None
]) – if not None, will apply rescaling to network outputs.lookup_init (
Callable
[[str
,Optional
[int
],Optional
[int
]],Callable
[[Tensor
],None
]]) – function taking string representation of activation function, number of inputs, and number of outputs an returning a function to initialise layer weights.
- Examples::
>>> tail = ClassRegMulti(n_in=100, n_out=1, objective='classification') >>> >>> tail = ClassRegMulti(n_in=100, n_out=5, objective='multiclass') >>> >>> y_range = (0.8*targets.min(), 1.2*targets.max()) >>> tail = ClassRegMulti(n_in=100, n_out=1, objective='regression', ... y_range=y_range) >>> >>> min_targs = np.min(targets, axis=0).reshape(targets.shape[1],1) >>> max_targs = np.max(targets, axis=0).reshape(targets.shape[1],1) >>> min_targs[min_targs > 0] *=0.8 >>> min_targs[min_targs < 0] *=1.2 >>> max_targs[max_targs > 0] *=1.2 >>> max_targs[max_targs < 0] *=0.8 >>> y_range = np.hstack((min_targs, max_targs)) >>> tail = ClassRegMulti(n_in=100, n_out=6, objective='regression', ... y_range=y_range, ... lookup_init=lookup_uniform_init)
lumin.nn.models.layers package¶
-
lumin.nn.models.layers.activations.
lookup_act
(act)[source]¶ Map activation name to class
- Parameters
act (
str
) – string representation of activation function- Return type
Any
- Returns
Class implementing requested activation function
-
class
lumin.nn.models.layers.activations.
Swish
(inplace=False)[source]¶ Bases:
torch.nn.modules.module.Module
Non-trainable Swish activation function https://arxiv.org/abs/1710.05941
- Parameters
inplace – whether to apply activation inplace
- Examples::
>>> swish = Swish()
Submodules¶
lumin.nn.models.helpers module¶
-
class
lumin.nn.models.helpers.
CatEmbedder
(cat_names, cat_szs, emb_szs=None, max_emb_sz=50, emb_load_path=None)[source]¶ Bases:
object
Helper class for embedding categorical features. Designed to be passed to
ModelBuilder
. Note that the classmethodfrom_fy()
may be used to instantiate anCatEmbedder
from aFoldYielder
.- Parameters
cat_names (
List
[str
]) – list of names of catgorical features in order in which they will be passed as inputs columnscat_szs (
List
[int
]) – list of cardinalities (number of unique elements) for each featureemb_szs (
Optional
[List
[int
]]) – Optional list of embedding sizes for each feature. If None, will use min(max_emb_sz, (1+sz)//2)max_emb_sz (
int
) – Maximum size of embedding if emb_szs is Noneemb_load_path (
Union
[Path
,str
,None
]) – if not None, will causeModelBuilder
to attempt to load pretrained embeddings from path
- Examples::
>>> cat_embedder = CatEmbedder(cat_names=['n_jets', 'channel'], cat_szs=[5, 3]) >>> >>> cat_embedder = CatEmbedder(cat_names=['n_jets', 'channel'], cat_szs=[5, 3], emb_szs=[2, 2]) >>> >>> cat_embedder = CatEmbedder(cat_names=['n_jets', 'channel'], cat_szs=[5, 3], emb_szs=[2, 2], emb_load_path=Path('weights'))
-
calc_emb_szs
()[source]¶ Method used to set sizes of embeddings for each categorical feature when no embedding sizes are explicitly passed Uses rule of thumb of min(50, (1+cardinality)/2)
- Return type
None
-
classmethod
from_fy
(fy, emb_szs=None, max_emb_sz=50, emb_load_path=None)[source]¶ Instantiate an
CatEmbedder
from aFoldYielder
, i.e. avoid having to pass cat_names and cat_szs.- Parameters
fy (
FoldYielder
) –FoldYielder
with training dataemb_szs (
Optional
[List
[int
]]) – Optional list of embedding sizes for each feature. If None, will use min(max_emb_sz, (1+sz)//2)max_emb_sz (
int
) – Maximum size of embedding if emb_szs is Noneemb_load_path (
Union
[Path
,str
,None
]) – if not None, will causeModelBuilder
to attempt to load pretrained embeddings from path
- Returns
- Examples::
>>> cat_embedder = CatEmbedder.from_fy(train_fy) >>> >>> cat_embedder = CatEmbedder.from_fy(train_fy, emb_szs=[2, 2]) >>> >>> cat_embedder = CatEmbedder.from_fy( train_fy, emb_szs=[2, 2], emb_load_path=Path('weights'))
-
lumin.nn.models.helpers.
Embedder
(cat_names, cat_szs, emb_szs=None, max_emb_sz=50, emb_load_path=None)[source]¶ Attention
Depreciated in favour of
CatEmbedder
and will be removed in v0.4.
lumin.nn.models.initialisations module¶
-
lumin.nn.models.initialisations.
lookup_normal_init
(act, fan_in=None, fan_out=None)[source]¶ Lookup for weight initialisation using Normal distributions
- Parameters
act (
str
) – string representation of activation functionfan_in (
Optional
[int
]) – number of inputs to neuronfan_out (
Optional
[int
]) – number of outputs from neuron
- Return type
Callable
[[Tensor
],None
]- Returns
Callable to initialise weight tensor
-
lumin.nn.models.initialisations.
lookup_uniform_init
(act, fan_in=None, fan_out=None)[source]¶ Lookup weight initialisation using Uniform distributions
- Parameters
act (
str
) – string representation of activation functionfan_in (
Optional
[int
]) – number of inputs to neuronfan_out (
Optional
[int
]) – number of outputs from neuron
- Return type
Callable
[[Tensor
],None
]- Returns
Callable to initialise weight tensor
lumin.nn.models.model module¶
-
class
lumin.nn.models.model.
Model
(model_builder=None)[source]¶ Bases:
lumin.nn.models.abs_model.AbsModel
Wrapper class to handle training and inference of NNs created via a
ModelBuilder
. Note that saved models can be instantiated direcly viafrom_save()
classmethod.- Parameters
model_builder (
Optional
[ModelBuilder
]) –ModelBuilder
which will construct the network, loss, and optimiser
- Examples::
>>> model = Model(model_builder)
-
evaluate
(inputs, targets, weights=None, callbacks=None, mask_inputs=True)[source]¶ Compute loss on provided data.
- Parameters
inputs (
Tensor
) – input data as tensor on devicetargets (
Tensor
) – targets as tensor on deviceweights (
Optional
[Tensor
]) – Optional weights as tensor on devicecallbacks (
Optional
[List
[AbsCallback
]]) – list of any callbacks to use during evaluationmask_inputs (
bool
) – whether to apply input mask if one has been set
- Return type
float
- Returns
(weighted) loss of model predictions on provided data
-
export2onnx
(name, bs=1)[source]¶ Export network 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
name (
str
) – filename for exported filebs (
int
) – batch size for exported models
- Return type
None
-
export2tfpb
(name, bs=1)[source]¶ Export network 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
name (
str
) – filename for exported filebs (
int
) – batch size for exported models
- Return type
None
-
fit
(batch_yielder, callbacks=None)[source]¶ Fit network for one complete iteration of a
BatchYielder
, i.e. one (sub-)epoch- Parameters
batch_yielder (
BatchYielder
) –BatchYielder
providing training data in form of tuple of inputs, targtes, and weights as tensors on devicecallbacks (
Optional
[List
[AbsCallback
]]) – list ofAbsCallback
to be used during training
- Return type
float
- Returns
Loss on training data averaged across all minibatches
-
classmethod
from_save
(name, model_builder)[source]¶ Instantiated a
Model
and load saved state from file.- Parameters
name (
str
) – name of file containing saved statemodel_builder (
ModelBuilder
) –ModelBuilder
which was used to construct the network
- Return type
AbsModel
- Returns
Instantiated
Model
with network weights, optimiser state, and input mask loaded from saved state
- Examples::
>>> model = Model.from_save('weights/model.h5', model_builder)
-
get_feat_importance
(fy, eval_metric=None)[source]¶ Call
get_nn_feat_importance()
passing thisModel
and provided arguments- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to data on which to evaluate importanceeval_metric (
Optional
[EvalMetric
]) – OptionalEvalMetric
to use for quantifying performance
- Return type
DataFrame
-
get_lr
()[source]¶ Get learning rate of optimiser
- Return type
float
- Returns
learning rate of optimiser
-
get_mom
()[source]¶ Get momentum/beta_1 of optimiser
- Return type
float
- Returns
momentum/beta_1 of optimiser
-
get_out_size
()[source]¶ Get number of outputs of model
- Return type
int
- Returns
Number of outputs of model
-
get_param_count
(trainable=True)[source]¶ Return number of parameters in model.
- Parameters
trainable (
bool
) – if true (default) only count trainable parameters- Return type
int
- Returns
NUmber of (trainable) parameters in model
-
get_weights
()[source]¶ Get state_dict of weights for network
- Return type
OrderedDict
- Returns
state_dict of weights for network
-
load
(name, model_builder=None)[source]¶ Load model, optimiser, and input mask states from file
- Parameters
name (
str
) – name of save filemodel_builder (
Optional
[ModelBuilder
]) – ifModel
was not initialised with aModelBuilder
, you will need to pass one here
- Return type
None
-
predict
(inputs, as_np=True, pred_name='pred')[source]¶ Apply model to inputed data and compute predictions. A compatability method to call
predict_array()
or meth:~lumin.nn.models.model.Model.predict_folds, depending on input type.- Parameters
inputs (
Union
[ndarray
,DataFrame
,Tensor
,FoldYielder
]) – input data as Numpy array, Pandas DataFrame, or tensor on device, orFoldYielder
interfacing to dataas_np (
bool
) – whether to return predictions as Numpy array (otherwise tensor) if inputs are a Numpy array, Pandas DataFrame, or tensorpred_name (
str
) – name of group to which to save predictions if inputs are aFoldYielder
- Return type
Union
[ndarray
,Tensor
,None
]- Returns
if inputs are a Numpy array, Pandas DataFrame, or tensor, will return predicitions as either array or tensor
-
predict_array
(inputs, as_np=True, mask_inputs=True)[source]¶ Pass inputs through network and obtain predictions.
- Parameters
inputs (
Union
[ndarray
,DataFrame
,Tensor
]) – input data as Numpy array, Pandas DataFrame, or tensor on deviceas_np (
bool
) – whether to return predictions as Numpy array (otherwise tensor)mask_inputs (
bool
) – whether to apply input mask if one has been set
- Return type
Union
[ndarray
,Tensor
]- Returns
Model prediction(s) per datapoint
-
predict_folds
(fy, pred_name='pred')[source]¶ Apply model to all dataaccessed by a
FoldYielder
and save predictions as new group in fold file- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing to datapred_name (
str
) – name of group to which to save predictions
- Return type
None
-
save
(name)[source]¶ Save model, optimiser, and input mask states to file
- Parameters
name (
str
) – name of save file- Return type
None
-
set_input_mask
(mask)[source]¶ Mask input columns by only using input columns whose indeces are listed in mask
- Parameters
mask (
ndarray
) – array of column indeces to use from all input columns- Return type
None
-
set_lr
(lr)[source]¶ set learning rate of optimiser
- Parameters
lr (
float
) – learning rate of optimiser- Return type
None
lumin.nn.models.model_builder module¶
-
class
lumin.nn.models.model_builder.
ModelBuilder
(objective, n_out, cont_feats=None, model_args=None, opt_args=None, cat_embedder=None, loss='auto', head=<class 'lumin.nn.models.blocks.head.CatEmbHead'>, body=<class 'lumin.nn.models.blocks.body.FullyConnected'>, tail=<class 'lumin.nn.models.blocks.tail.ClassRegMulti'>, lookup_init=<function lookup_normal_init>, lookup_act=<function lookup_act>, pretrain_file=None, freeze_head=False, freeze_body=False, freeze_tail=False, cat_args=None, n_cont_in=None)[source]¶ Bases:
object
Class to build models to specified architecture on demand along with an optimiser.
Attention
cat_args is now depreciated in favour of cat_embedder and will be removed in v0.4
Attention
n_cont_in is now depreciated in favour of cont_feats and will be removed in v0.4
- Parameters
objective (
str
) – string representation of network objective, i.e. ‘classification’, ‘regression’, ‘multiclass’n_out (
int
) – number of outputs requiredcont_feats (
Optional
[List
[str
]]) – list of names of continuous input featuresmodel_args (
Optional
[Dict
[str
,Dict
[str
,Any
]]]) – dictionary of dictionaries of keyword arguments to pass to head, body, and tail to control architrctureopt_args (
Optional
[Dict
[str
,Any
]]) – dictionary of arguments to pass to optimiser. Missing kargs will be filled with default values. Currently, only ADAM (default), RAdam, Ranger, and SGD are available.cat_embedder (
Optional
[CatEmbedder
]) –CatEmbedder
for embedding categorical inputsloss (
Any
) – either and uninstantiated loss class, or leave as ‘auto’ to select loss according to objectivehead (
AbsHead
) – uninstantiated class which can receive input data and upscale it to model widthbody (
AbsBody
) – uninstantiated class which implements the main bulk of the model’s hidden layerstail (
AbsTail
) – uninstantiated class which scales the body to the required number of outputs and implements any final activation function and output scalinglookup_init (
Callable
[[str
,Optional
[int
],Optional
[int
]],Callable
[[Tensor
],None
]]) – function taking choice of activation function, number of inputs, and number of outputs an returning a function to initialise layer weights.lookup_act (
Callable
[[str
],Module
]) – function taking choice of activation function and returning an activation function layerpretrain_file (
Optional
[str
]) – if set, will load saved parameters for entire network from saved modelfreeze_head (
bool
) – whether to start with the head parameters set to untrainablefreeze_body (
bool
) – whether to start with the body parameters set to untrainablecat_args (
Optional
[Dict
[str
,Any
]]) – depreciated in place of cat_embeddern_cont_in (
Optional
[int
]) – depreciated in favour of cont_feats
- Examples::
>>> model_builder = ModelBuilder(objective='classifier', >>> cont_feats=cont_feats, n_out=1, >>> model_args={'body':{'depth':4, >>> 'width':100}}) >>> >>> min_targs = np.min(targets, axis=0).reshape(targets.shape[1],1) >>> max_targs = np.max(targets, axis=0).reshape(targets.shape[1],1) >>> min_targs[min_targs > 0] *=0.8 >>> min_targs[min_targs < 0] *=1.2 >>> max_targs[max_targs > 0] *=1.2 >>> max_targs[max_targs < 0] *=0.8 >>> y_range = np.hstack((min_targs, max_targs)) >>> model_builder = ModelBuilder( >>> objective='regression', cont_feats=cont_feats, n_out=6, >>> cat_embedder=CatEmbedder.from_fy(train_fy), >>> model_args={'body':{'depth':4, 'width':100}, >>> 'tail':{y_range=y_range}) >>> >>> model_builder = ModelBuilder(objective='multiclassifier', >>> cont_feats=cont_feats, n_out=5, >>> model_args={'body':{'width':100, >>> 'depth':6, >>> 'do':0.1, >>> 'res':True}}) >>> >>> model_builder = ModelBuilder(objective='classifier', >>> cont_feats=cont_feats, n_out=1, >>> model_args={'body':{'depth':4, >>> 'width':100}}, >>> opt_args={'opt':'sgd', >>> 'momentum':0.8, >>> 'weight_decay':1e-5}, >>> loss=partial(SignificanceLoss, >>> sig_weight=sig_weight, >>> bkg_weight=bkg_weight, >>> func=calc_ams_torch))
-
build_model
()[source]¶ Construct entire network module
- Return type
Module
- Returns
Instantiated nn.Module
-
classmethod
from_model_builder
(model_builder, pretrain_file=None, freeze_head=False, freeze_body=False, freeze_tail=False, loss=None, opt_args=None)[source]¶ Instantiate a
ModelBuilder
from an exisitngModelBuilder
, but with options to adjust loss, optimiser, pretraining, and module freezing- Parameters
model_builder – existing
ModelBuilder
or filename for a pickledModelBuilder
pretrain_file (
Optional
[str
]) – if set, will load saved parameters for entire network from saved modelfreeze_head (
bool
) – whether to start with the head parameters set to untrainablefreeze_body (
bool
) – whether to start with the body parameters set to untrainablefreeze_tail (
bool
) – whether to start with the tail parameters set to untrainableloss (
Optional
[Any
]) – either and uninstantiated loss class, or leave as ‘auto’ to select loss according to objectiveopt_args (
Optional
[Dict
[str
,Any
]]) – dictionary of arguments to pass to optimiser. Missing kargs will be filled with default values. Choice of optimiser (‘opt’) keyword can either be set by passing the string name (e.g. ‘adam’ ), but only ADAM and SGD are available this way, or by passing an uninstantiated optimiser (e.g. torch.optim.Adam). If no optimser is set, then it defaults to ADAM. Additional keyword arguments can be set, and these will be passed tot he optimiser during instantiation
- Returns
Instantiated
ModelBuilder
- Examples::
>>> new_model_builder = ModelBuilder.from_model_builder( >>> ModelBuidler) >>> >>> new_model_builder = ModelBuilder.from_model_builder( >>> ModelBuidler, loss=partial( >>> SignificanceLoss, sig_weight=sig_weight, >>> bkg_weight=bkg_weight, func=calc_ams_torch)) >>> >>> new_model_builder = ModelBuilder.from_model_builder( >>> 'weights/model_builder.pkl', >>> opt_args={'opt':'sgd', 'momentum':0.8, 'weight_decay':1e-5}) >>> >>> new_model_builder = ModelBuilder.from_model_builder( >>> 'weights/model_builder.pkl', >>> opt_args={'opt':torch.optim.Adam, ... 'momentum':0.8, ... 'weight_decay':1e-5})
-
get_body
(n_in, feat_map)[source]¶ Construct body module
- Return type
AbsBody
- Returns
Instantiated body nn.Module
-
get_model
()[source]¶ Construct model, loss, and optimiser, optionally loading pretrained weights
- Return type
Tuple
[Module
,Optimizer
,Any
]- Returns
Instantiated network, optimiser linked to model parameters, and uninstantiated loss
-
get_out_size
()[source]¶ Get number of outputs of model
- Return type
int
- Returns
number of outputs of network
-
get_tail
(n_in)[source]¶ Construct tail module
- Return type
Module
- Returns
Instantiated tail nn.Module
-
load_pretrained
(model)[source]¶ Load model weights from pretrained file
- Parameters
model (
Module
) – instantiated model, i.e. return ofbuild_model()
- Returns
model with weights loaded
Module contents¶
lumin.nn.training package¶
Submodules¶
lumin.nn.training.fold_train module¶
-
lumin.nn.training.fold_train.
fold_train_ensemble
(fy, n_models, bs, model_builder, callback_partials=None, eval_metrics=None, train_on_weights=True, eval_on_weights=True, patience=10, max_epochs=200, plots=['history', 'realtime'], shuffle_fold=True, shuffle_folds=True, bulk_move=True, savepath=PosixPath('train_weights'), verbose=False, log_output=False, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>, callback_args=None)[source]¶ Main training method for
Model
. Trains a specified numer of models created by aModelBuilder
on data provided by aFoldYielder
, and save them to savepath. Note, this does not return trained models, instead they are saved and must be loaded later. Instead this method returns results of model training. EachModel
is trained on N-1 folds, for aFoldYielder
with N folds, and the remaining fold is used as validation data. Training folds are loaded iteratively, and model evaluation takes place after each fold use (a sub-epoch), rather than after ever use of all folds (epoch). Training continues until:All of the training folds are used max_epoch number of times;
Or validation loss does not decrease for patience number of training folds; (or cycles, if using an
AbsCyclicCallback
);Or a callback triggers trainign to stop, e.g.
OneCycle
Once training is finished, the state with the lowest validation loss is loaded, evaluated, and saved.
Attention
callback_args is now depreciated in favour of callback_partials and will be removed in v0.4
- Parameters
fy (
FoldYielder
) –FoldYielder
interfacing ot training datan_models (
int
) – number of models to trainbs (
int
) – batch size. Number of data points per iterationmodel_builder (
ModelBuilder
) –ModelBuilder
creating the networks to traincallback_partials (
Optional
[List
[partial
]]) – optional list of functools.partial, each of which will a instantiateCallback
when calledeval_metrics (
Optional
[Dict
[str
,EvalMetric
]]) – list of instantiatedEvalMetric
. At the end of training, validation data and model predictions will be passed to each, and the results printed and savedtrain_on_weights (
bool
) – If weights are present in training data, whether to pass them to the loss function during trainingeval_on_weights (
bool
) – If weights are present in validation data, whether to pass them to the loss function during validationpatience (
int
) – number of folds (sub-epochs) or cycles to train without decrease in validation loss before ending training (early stopping)max_epochs (
int
) – maximum number of epochs for which to trainplots (
List
[str
]) – list of string representation of plots to produce. currently: ‘history’: loss history of all models after all training has finished ‘realtime’: live loss evolution during training ‘cycle”: call the plot method of the last (if any)AbsCyclicCallback
listed in callback_partials after every complete model training.shuffle_fold (
bool
) – whether to tellBatchYielder
to shuffle datashuffle_folds (
bool
) – whether to shuffle the order of the trainign foldsbulk_move (
bool
) – whether to pass all training data to device at once, or by minibatch. Bulk moving will be quicker, but may not fit in memory.savepath (
Path
) – path to to which to save model weights and resultsverbose (
bool
) – whether to print out extra information during traininglog_output (
bool
) – whether to save printed results to a log file rather than printing themplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearancecallback_args (
Optional
[List
[Dict
[str
,Any
]]]) – depreciated in favour of callback_partials
- Return type
Tuple
[List
[Dict
[str
,float
]],List
[Dict
[str
,List
[float
]]],List
[Dict
[str
,float
]]]- Returns
results list of validation losses and other eval_metrics results, ordered by model training. Can be used to create an
Ensemble
.histories list of loss histories, ordered by model training
cycle_losses if an
AbsCyclicCallback
was passed, list of validation losses at the end of each cycle, ordered by model training. Can be passed toEnsemble
.
Module contents¶
Module contents¶
lumin.optimisation package¶
Submodules¶
lumin.optimisation.features module¶
-
lumin.optimisation.features.
get_rf_feat_importance
(rf, inputs, targets, weights=None)[source]¶ Compute feature importance for a Random Forest model using rfpimp.
- Parameters
rf (
ForestRegressor
) – trained Random Forest modelinputs (
DataFrame
) – input data as Pandas DataFrametargets (
ndarray
) – target data as Numpy arrayweights (
Optional
[ndarray
]) – Optional data weights as Numpy array
- Return type
DataFrame
-
lumin.optimisation.features.
rf_rank_features
(train_df, val_df, objective, train_feats, targ_name='gen_target', wgt_name=None, importance_cut=0.0, n_estimators=40, n_rfs=1, savename=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Compute relative permutation importance of input features via using Random Forests. A reduced set of ‘important features’ is obtained by cutting on relative importance and a new model is trained and evaluated on this reduced set. RFs will have their hyper-parameters roughly optimised, both when training on all features and once when training on important features. Relative importances may be computed multiple times (via n_rfs) and averaged. In which case the standard error is also computed.
- Parameters
train_df (
DataFrame
) – training data as Pandas DataFrameval_df (
DataFrame
) – validation data as Pandas DataFrameobjective (
str
) – string representation of objective: either ‘classification’ or ‘regression’train_feats (
List
[str
]) – complete list of training featurestarg_name (
str
) – name of column containing target datawgt_name (
Optional
[str
]) – name of column containing weight data. If set, will use weights for training and evaluation, otherwise will notimportance_cut (
float
) – minimum importance required to be considered an ‘important feature’n_estimators (
int
) – number of trees to use in each forestn_rfs (
int
) – number of trainings to perform on all training features in order to compute importancessavename (
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
List
[str
]- Returns
List of features passing importance_cut, ordered by importance
lumin.optimisation.hyper_param module¶
-
lumin.optimisation.hyper_param.
get_opt_rf_params
(x_trn, y_trn, x_val, y_val, objective, w_trn=None, w_val=None, params={'max_features': [0.3, 0.5, 0.7, 0.9], 'min_samples_leaf': [1, 3, 5, 10, 25, 50, 100]}, n_estimators=40, verbose=True)[source]¶ Use an ordered parameter-scan to roughly optimise Random Forest hyper-parameters.
- Parameters
x_trn (
ndarray
) – training input datay_trn (
ndarray
) – training target datax_val (
ndarray
) – validation input datay_val (
ndarray
) – validation target dataobjective (
str
) – string representation of objective: either ‘classification’ or ‘regression’w_trn (
Optional
[ndarray
]) – training weightsw_val (
Optional
[ndarray
]) – validation weightsparams (
OrderedDict
) – ordered dictionary mapping parameters to optimise to list of values to cosnidern_estimators (
int
) – number of trees to use in each forestverbose – Print extra information and show a live plot of model performance
- Returns
dictionary mapping parameters to their optimised values rf: best performing Random Forest
- Return type
params
-
lumin.optimisation.hyper_param.
fold_lr_find
(fy, model_builder, bs, train_on_weights=True, shuffle_fold=True, n_folds=-1, lr_bounds=[1e-05, 10], callback_partials=None, plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Wrapper function for training using
LRFinder
which runs a Smith LR range test (https://arxiv.org/abs/1803.09820) using folds inFoldYielder
. Trains models for 1 fold, interpolating LR between set bounds. This repeats for each fold inFoldYielder
, and loss evolution is averaged.- Parameters
fy (
FoldYielder
) –FoldYielder
providing training datamodel_builder (
ModelBuilder
) –ModelBuilder
providing networks and optimisersbs (
int
) – batch sizetrain_on_weights (
bool
) – If weights are present, whether to use them for trainingshuffle_fold (
bool
) – whether to shuffle data in foldsn_folds (
int
) – if >= 1, will only train n_folds number of models, otherwise will train one model per foldlr_bounds (
Tuple
[float
,float
]) – starting and ending LR valuescallback_partials (
Optional
[List
[partial
]]) – optional list of functools.partial, each of which will a instantiateCallback
when calledplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
List
[LRFinder
]- Returns
List of
LRFinder
which were used for each model trained
lumin.optimisation.threshold module¶
-
lumin.optimisation.threshold.
binary_class_cut
(df, top_perc=5.0, min_pred=0.9, wgt_factor=1.0, br=0.0, syst_unc_b=0.0, pred_name='pred', targ_name='gen_target', wgt_name='gen_weight', plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Attention
Depreciated as renamed to
binary_class_cut_by_ams()
. Will be removed in v0.4.- Return type
Tuple
[float
,float
,float
]
-
lumin.optimisation.threshold.
binary_class_cut_by_ams
(df, top_perc=5.0, min_pred=0.9, wgt_factor=1.0, br=0.0, syst_unc_b=0.0, pred_name='pred', targ_name='gen_target', wgt_name='gen_weight', plot_settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Optimise a cut on a signal-background classifier prediction by the Approximate Median Significance Cut which should generalise better by taking the mean class prediction of the top top_perc percentage of points as ranked by AMS
- Parameters
df (
DataFrame
) – Pandas DataFrame containing datatop_perc (
float
) – top percentage of events to consider as ranked by AMSmin_pred (
float
) – minimum prediction to considerwgt_factor (
float
) – single multiplicative coeficient for rescaling signal and background weights before computing AMSbr (
float
) – background offset biassyst_unc_b (
float
) – fractional systemtatic uncertainty on backgroundpred_name (
str
) – column to use as predictionstarg_name (
str
) – column to use as truth labels for signal and backgroundwgt_name (
str
) – column to use as weights for signal and background eventsplot_settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
Tuple
[float
,float
,float
]- Returns
Optimised cut AMS at cut Maximum AMS
Module contents¶
lumin.plotting package¶
Submodules¶
lumin.plotting.data_viewing module¶
-
lumin.plotting.data_viewing.
plot_feat
(df, feat, wgt_name=None, cuts=None, labels='', plot_bulk=True, n_samples=100000, plot_params=None, size='mid', show_moments=True, ax_labels={'x': None, 'y': 'Density'}, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ A flexible function to provide indicative information about the 1D distribution of a feature. By default it will produce a weighted KDE+histogram for the [1,99] percentile of the data, as well as compute the mean and standard deviation of the data in this region. Distributions are weighted by sampling with replacement the data with probabilities propotional to the sample weights. By passing a list of cuts and labels, it will plot multiple distributions of the same feature for different cuts. Since it is designed to provide quick, indicative information, more specific functions (such as plot_kdes_from_bs) should be used to provide final results.
- Parameters
df (
DataFrame
) – Pandas DataFrame containing datafeat (
str
) – column name to plotwgt_name (
Optional
[str
]) – if set, will use column to weight datacuts (
Optional
[List
[Series
]]) – optional list of cuts to apply to feature. Will add one KDE+hist for each cut listed on the same plotlabels (
Optional
[List
[str
]]) – optional list of labels for each KDE+histplot_bulk (
bool
) – whether to plot the [1,99] percentile of the data, or all of itn_samples (
int
) – if plotting weighted distributions, how many samples to useplot_params (
Union
[Dict
[str
,Any
],List
[Dict
[str
,Any
]],None
]) – optional list of of arguments to pass to Seaborn Distplot for each KDE+histsize (
str
) – string to pass tostr2sz()
to determin size of plotshow_moments (
bool
) – whether to compute and display the mean and standard deviationax_labels (
Dict
[str
,Any
]) – dictionary of x and y axes labelssavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.data_viewing.
compare_events
(events)[source]¶ Plot at least two events side by side in their transverse and longitudinal projections
- Parameters
events (
list
) – list of DataFrames containing vector coordinates for 3 momenta- Return type
None
-
lumin.plotting.data_viewing.
plot_rank_order_dendrogram
(df, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot dendrogram of features in df clustered via Spearman’s rank correlation coefficient
- Parameters
df (
DataFrame
) – Pandas DataFrame containing datasavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.data_viewing.
plot_kdes_from_bs
(x, bs_stats, name2args, feat, units=None, moments=True, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot KDEs computed via
bootstrap_stats()
- Parameters
bs_stats (
Dict
[str
,Any
]) – (filtered) dictionary retruned bybootstrap_stats()
name2args (
Dict
[str
,Dict
[str
,Any
]]) – Dictionary mapping names of different distributions to arguments to pass to seaborn tsplotfeat (
str
) – Name of feature being plotted (for axis lablels)units (
Optional
[str
]) – Optional units to show on axesmoments – whether to display mean and standard deviation of each distribution
savename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
lumin.plotting.interpretation module¶
-
lumin.plotting.interpretation.
plot_importance
(df, feat_name='Feature', imp_name='Importance', unc_name='Uncertainty', savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot feature importances as computted via get_nn_feat_importance, get_ensemble_feat_importance, or rf_rank_features
- Parameters
df (
DataFrame
) – DataFrame containing columns of features, importances and, optionally, uncertaintiesfeat_name (
str
) – column name for featuresimp_name (
str
) – column name for importancesunc_name (
str
) – column name for uncertainties (if present)savename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.interpretation.
plot_embedding
(embed, feat, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Visualise weights in provided categorical entity-embedding matrix
- Parameters
embed (
OrderedDict
) – state_dict of trained nn.Embeddingfeat (
str
) – name of feature embeddedsavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.interpretation.
plot_1d_partial_dependence
(model, df, feat, train_feats, ignore_feats=None, input_pipe=None, sample_sz=None, wgt_name=None, n_clusters=10, n_points=20, pdp_isolate_kargs=None, pdp_plot_kargs=None, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Wrapper for PDPbox to plot 1D dependence of specified feature using provided NN or RF. If features have been preprocessed using an SK-Learn Pipeline, then that can be passed in order to rescale the x-axis back to its original values.
- Parameters
model (
Any
) – any trained model with a .predict methoddf (
DataFrame
) – DataFrame containing training datafeat (
str
) – feature for which to evaluate the partial dependence of the modeltrain_feats (
List
[str
]) – list of all training features including ones which were later ignored, i.e. input features considered when input_pipe was fittedignore_feats (
Optional
[List
[str
]]) – features present in training data which were not used to train the model (necessary to correctly deprocess feature using input_pipe)input_pipe (
Optional
[Pipeline
]) – SK-Learn Pipeline which was used to process the training datasample_sz (
Optional
[int
]) – if set, will only compute partial dependence on a random sample with replacement of the training data, sampled according to weights (if set). Speeds up computation and allows weighted partial dependencies to computed.wgt_name (
Optional
[str
]) – Optional column name to use as sampling weightsn_points (
int
) – number of points at which to evaluate the model output, passed to pdp_isolate as num_grid_pointsn_clusters (
Optional
[int
]) – number of clusters in which to group dependency lines. Set to None to show all linespdp_isolate_kargs (
Optional
[Dict
[str
,Any
]]) – optional dictionary of keyword arguments to pass to pdp_isolatepdp_plot_kargs (
Optional
[Dict
[str
,Any
]]) – optional dictionary of keyword arguments to pass to pdp_plotsavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.interpretation.
plot_2d_partial_dependence
(model, df, feats, train_feats, ignore_feats=None, input_pipe=None, sample_sz=None, wgt_name=None, n_points=[20, 20], pdp_interact_kargs=None, pdp_interact_plot_kargs=None, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Wrapper for PDPbox to plot 2D dependence of specified pair of features using provided NN or RF. If features have been preprocessed using an SK-Learn Pipeline, then that can be passed in order to rescale them back to their original values.
- Parameters
model (
Any
) – any trained model with a .predict methoddf (
DataFrame
) – DataFrame containing training datafeats (
Tuple
[str
,str
]) – pair of features for which to evaluate the partial dependence of the modeltrain_feats (
List
[str
]) – list of all training features including ones which were later ignored, i.e. input features considered when input_pipe was fittedignore_feats (
Optional
[List
[str
]]) – features present in training data which were not used to train the model (necessary to correctly deprocess feature using input_pipe)input_pipe (
Optional
[Pipeline
]) – SK-Learn Pipeline which was used to process the training datasample_sz (
Optional
[int
]) – if set, will only compute partial dependence on a random sample with replacement of the training data, sampled according to weights (if set). Speeds up computation and allows weighted partial dependencies to computed.wgt_name (
Optional
[str
]) – Optional column name to use as sampling weightsn_points (
Tuple
[int
,int
]) – pair of numbers of points at which to evaluate the model output, passed to pdp_interact as num_grid_pointsn_clusters – number of clusters in which to group dependency lines. Set to None to show all lines
pdp_isolate_kargs – optional dictionary of keyword arguments to pass to pdp_isolate
pdp_plot_kargs – optional dictionary of keyword arguments to pass to pdp_plot
savename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.interpretation.
plot_multibody_weighted_outputs
(model, inputs, block_names=None, use_mean=False, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Interpret how a model relies on the outputs of each block in a :class:MultiBlock by plotting the outputs of each block as weighted by the tail block. This function currently only supports models whose tail block contains a single neuron in the first dense layer. Input data is passed through the model and the absolute sums of the weighted block outputs are computed per datum, and optionally averaged over the number of block outputs.
- Parameters
model (
AbsModel
) – model to interpretinputs (
Union
[ndarray
,Tensor
]) – input data to use for interpretationblock_names (
Optional
[List
[str
]]) – names for each block to use when plottinguse_mean (
bool
) – if True, will average the weighted outputs over the number of output neurons in each blocksavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.interpretation.
plot_bottleneck_weighted_inputs
(model, bottleneck_idx, inputs, log_y=True, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Interpret how a single-neuron bottleneck in a :class:MultiBlock relies on input features by plotting the absolute values of the features times their associated weight for a given set of input data.
- Parameters
model (
AbsModel
) – model to interpretbottleneck_idx (
int
) – index of the bottleneck to interpret, i.e. model.body.bottleneck_blocks[bottleneck_idx]inputs (
Union
[ndarray
,Tensor
]) – input data to use for interpretationlog_y (
bool
) – whether to plot a log scale for the y-axissavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
lumin.plotting.plot_settings module¶
-
class
lumin.plotting.plot_settings.
PlotSettings
(**kargs)[source]¶ Bases:
object
Class to provide control over plot appearances. Default parameters are set automatically, and can be adjusted by passing values as keyword arguments during initialisation (or changed after instantiation)
- Parameters
arguments (keyword) – used to set relevant plotting parameters
lumin.plotting.results module¶
-
lumin.plotting.results.
plot_roc
(data, pred_name='pred', targ_name='gen_target', wgt_name=None, labels=None, plot_params=None, n_bootstrap=0, log_x=False, plot_baseline=True, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot receiver operating characteristic curve(s), optionally using booststrap resampling
- Parameters
data (
Union
[DataFrame
,List
[DataFrame
]]) – (list of) DataFrame(s) from which to draw predictions and targetspred_name (
str
) – name of column to use as predictionstarg_name (
str
) – name of column to use as targetswgt_name (
Optional
[str
]) – optional name of column to use as sample weightslabels (
Union
[str
,List
[str
],None
]) – (list of) label(s) for plot legendplot_params (
Union
[Dict
[str
,Any
],List
[Dict
[str
,Any
]],None
]) – (list of) dictionar[y/ies] of argument(s) to pass to line plotn_bootstrap (
int
) – if greater than 0, will bootstrap resample the data that many times when computing the ROC AUC. Currently, this does not affect the shape of the lines, which are based on computing the ROC for the entire dataset as is.log_x (
bool
) – whether to use a log scale for plotting the x-axis, useful for high AUC lineplot_baseline (
bool
) – whether to plot a dotted line for AUC=0.5. Currently incompatable with log_x=Truesavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
Dict
[str
,Union
[float
,Tuple
[float
,float
]]]- Returns
Dictionary mapping data labels to aucs (and uncertainties if n_bootstrap > 0)
-
lumin.plotting.results.
plot_binary_class_pred
(df, pred_name='pred', targ_name='gen_target', wgt_name=None, wgt_scale=1, log_y=False, lim_x=(0, 1), density=True, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Basic plotter for prediction distribution in a binary classification problem. Note that labels are set using the settings.targ2class dictionary, which by default is {0: ‘Background’, 1: ‘Signal’}.
- Parameters
df (
DataFrame
) – DataFrame with targets and predictionspred_name (
str
) – name of column to use as predictionstarg_name (
str
) – name of column to use as targetswgt_name (
Optional
[str
]) – optional name of column to use as sample weightswgt_scale (
float
) – applies a global multiplicative rescaling to sample weights. Default 1 = no rescalinglog_y (
bool
) – whether to use a log scale for the y-axislim_x (
Tuple
[float
,float
]) – limit for plotting on the x-axisdensity – whether to normalise each distribution to one, or keep set to sum of weights / datapoints
savename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.results.
plot_sample_pred
(df, pred_name='pred', targ_name='gen_target', wgt_name='gen_weight', sample_name='gen_sample', wgt_scale=1, bins=35, log_y=True, lim_x=(0, 1), density=False, zoom_args=None, savename=None, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ More advanceed plotter for prediction distirbution in a binary class problem with stacked distributions for backgrounds and user-defined binning Can also zoom in to specified parts of plot Note that plotting colours can be controled by seeting the settings.sample2col dictionary
- Parameters
df (
DataFrame
) – DataFrame with targets and predictionspred_name (
str
) – name of column to use as predictionstarg_name (
str
) – name of column to use as targetswgt_name (
str
) – name of column to use as sample weightssample_name (
str
) – name of column to use as process nameswgt_scale (
float
) – applies a global multiplicative rescaling to sample weights. Default 1 = no rescalingbins (
Union
[int
,List
[int
]]) – either the number of bins to use for a uniform binning, or a list of bin edges for a variable-width binninglog_y (
bool
) – whether to use a log scale for the y-axislim_x (
Tuple
[float
,float
]) – limit for plotting on the x-axisdensity – whether to normalise each distribution to one, or keep set to sum of weights / datapoints
zoom_args (
Optional
[Dict
[str
,Any
]]) – arguments to control the optional zoomed in section, e.g. {‘x’:(0.4,0.45), ‘y’:(0.2, 1500), ‘anchor’:(0,0.25,0.95,1), ‘width_scale’:1, ‘width_zoom’:4, ‘height_zoom’:3}savename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancessettings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
lumin.plotting.training module¶
-
lumin.plotting.training.
plot_train_history
(histories, savename=None, ignore_trn=True, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot histories object returned by
fold_train_ensemble()
showing the loss evolution over time per model trained.- Parameters
histories (
List
[Dict
[str
,List
[float
]]]) – list of dictionaries mapping loss type to values at each (sub)-epochsavename (
Optional
[str
]) – Optional name of file to which to save the plot of feature importancesignore_trn – whether to ignore training loss
settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
-
lumin.plotting.training.
plot_lr_finders
(lr_finders, loss='loss', cut=-10, settings=<lumin.plotting.plot_settings.PlotSettings object>)[source]¶ Plot mean loss evolution against learning rate for several
fold_lr_find
.- Parameters
lr_finders (
List
[LRFinder
]) – list offold_lr_find
)loss – string representation of loss to plot
cut – number of final iterations to cut
settings (
PlotSettings
) –PlotSettings
class to control figure appearance
- Return type
None
Module contents¶
lumin.utils package¶
Submodules¶
lumin.utils.data module¶
-
lumin.utils.data.
check_val_set
(train, val, test=None, n_folds=None)[source]¶ Method to check validation set suitability by seeing whether Random Forests can predict whether events belong to one dataset or another. If a
FoldYielder
is passed, then trainings are run once per fold and averaged. Will compute the ROC AUC for set discrimination (should be close to 0.5) and compute the feature importances to aid removal of discriminating features.- Parameters
train (
Union
[DataFrame
,ndarray
,FoldYielder
]) – training dataval (
Union
[DataFrame
,ndarray
,FoldYielder
]) – validation datatest (
Union
[DataFrame
,ndarray
,FoldYielder
,None
]) – optional testing datan_folds (
Optional
[int
]) – if set and if passed aFoldYielder
, will only use the first n_folds folds
- Return type
None
lumin.utils.misc module¶
-
lumin.utils.misc.
to_np
(x)[source]¶ Convert Tensor x to a Numpy array
- Parameters
x (
Tensor
) – Tensor to convert- Return type
ndarray
- Returns
x as a Numpy array
-
lumin.utils.misc.
to_device
(x, device=device(type='cpu'))[source]¶ Recursively place Tensor(s) onto device
- Parameters
x (
Union
[Tensor
,List
[Tensor
]]) – Tensor(s) to place on device- Return type
Union
[Tensor
,List
[Tensor
]]- Returns
Tensor(s) on device
-
lumin.utils.misc.
to_tensor
(x)[source]¶ Convert Numpy array to Tensor with possibility of a None being passed
- Parameters
x (
Optional
[ndarray
]) – Numpy array or None- Return type
Optional
[Tensor
]- Returns
x as Tensor or None
-
lumin.utils.misc.
str2bool
(string)[source]¶ Convert string representation of Boolean to bool
- Parameters
string (
Union
[str
,bool
]) – string representation of Boolean (or a Boolean)- Return type
bool
- Returns
bool if bool was passed else, True if lowercase string matches is in (“yes”, “true”, “t”, “1”)
-
lumin.utils.misc.
to_binary_class
(df, zero_preds, one_preds)[source]¶ Map class precitions back to a binary prediction. The maximum prediction for features listed in zero_preds is treated as the prediction for class 0, vice versa for one_preds. The binary prediction is added to df in place as column ‘pred’
- Parameters
df (
DataFrame
) – DataFrame containing prediction featureszero_preds (
List
[str
]) – list of column names for predictions associated with class 0one_preds (
List
[str
]) – list of column names for predictions associated with class 0
- Return type
None
-
lumin.utils.misc.
ids2unique
(ids)[source]¶ Map a permutaion of integers to a unique number, or a 2D array of integers to unique numbers by row. Returned numbers are unique for a given permutation of integers. This is achieved by computing the product of primes raised to powers equal to the integers. Beacause of this, it can be easy to produce numbers which are too large to be stored if many (large) integers are passed.
- Parameters
ids (
Union
[List
[int
],ndarray
]) – (array of) permutation(s) of integers to map- Return type
ndarray
- Returns
(Array of) unique id(s) for given permutation(s)
-
class
lumin.utils.misc.
FowardHook
(module, hook_fn=None)[source]¶ Bases:
object
Create a hook for performing an action based on the forward pass thorugh a nn.Module
- Parameters
module – nn.Module to hook
hook_fn – Optional function to perform. Default is to record input and output of module
- Examples::
>>> hook = ForwardHook(model.tail.dense) >>> model.predict(inputs) >>> print(hook.inputs)
lumin.utils.multiprocessing module¶
-
lumin.utils.multiprocessing.
mp_run
(args, func)[source]¶ Run multiple instances of function simultaneously by using a list of argument dictionaries Runs given function once per entry in args list.
Important
Function should put a dictionary of results into the mp.Queue and each result key should be unique otherwise they will overwrite one another.
- Parameters
args (
List
[Dict
[Any
,Any
]]) – list of dictionaries of argumentsfunc (
Callable
[[Any
],Any
]) – function to which to pass dictionary arguments
- Return type
Dict
[Any
,Any
]- Returns
DIctionary of results
lumin.utils.statistics module¶
-
lumin.utils.statistics.
bootstrap_stats
(args, out_q=None)[source]¶ Computes statistics and KDEs of data via sampling with replacement
- Parameters
args (
Dict
[str
,Any
]) – dictionary of arguments. Possible keys are: name - name prepended to returned keys in result dict weights - array of weights matching length of data to use for weighted resampling n - number of times to resample data x - points at which to compute the kde values of resample data kde - whether to compute the kde values at x-points for resampled data mean - whether to compute the means of the resampled data std - whether to compute standard deviation of resampled data c68 - whether to compute the width of the absolute central 68.2 percentile of the resampled dataout_q (
Optional
[<bound method BaseContext.Queue of <multiprocessing.context.DefaultContext object at 0x7fb48dc0a668>>]) – if using multiporcessing can place result dictionary in provided queue
- Return type
Union
[None
,Dict
[str
,Any
]]- Returns
Result dictionary if out_q is None else None.
-
lumin.utils.statistics.
get_moments
(arr)[source]¶ Computes mean and std of data, and their associated uncertainties
- Parameters
arr (
ndarray
) – univariate data- Return type
Tuple
[float
,float
,float
,float
]- Returns
mean
statistical uncertainty of mean
standard deviation
statistical uncertainty of standard deviation
-
lumin.utils.statistics.
uncert_round
(value, uncert)[source]¶ Round value according to given uncertainty using one significant figure of the uncertainty
- Parameters
value (
float
) – value to rounduncert (
float
) – uncertainty of value
- Return type
Tuple
[float
,float
]- Returns
rounded value
rounded uncertainty