nilmtk package

Submodules

nilmtk.building module

class nilmtk.building.Building[source]

Bases: object

Attributes:

elec : MeterGroup

metadata : dict

Metadata just about this building (e.g. geo location etc). See http://nilm-metadata.readthedocs.org/en/latest/dataset_metadata.html#building Has these additional keys: dataset : string
identifier[source]
load(store, key, dataset_name)[source]
save(destination, key)[source]
class nilmtk.building.BuildingID

Bases: tuple

dataset

Alias for field number 1

instance

Alias for field number 0

nilmtk.cross_validation module

nilmtk.exceptions module

File defining custom nilmtk exception classes.

exception nilmtk.exceptions.TooFewSamplesError[source]

Bases: exceptions.Exception

nilmtk.metrics module

Metrics to compare disaggregation performance against ground truth data.

All metrics functions have the same interface. Each function takes predictions and ground_truth parameters. Both of which are nilmtk.MeterGroup objects. Each function returns one of two types: either a pd.Series or a single float. Most functions return a pd.Series where each index element is a meter instance int or a tuple of ints for MeterGroups.

Notation

Below is the notation used to mathematically define each metric.

\(T\) - number of time slices.

\(t\) - a time slice.

\(N\) - number of appliances.

\(n\) - an appliance.

\(y^{(n)}_t\) - ground truth power of appliance \(n\) in time slice \(t\).

\(\hat{y}^{(n)}_t\) - estimated power of appliance \(n\) in time slice \(t\).

\(x^{(n)}_t\) - ground truth state of appliance \(n\) in time slice \(t\).

\(\hat{x}^{(n)}_t\) - estimated state of appliance \(n\) in time slice \(t\).

Functions

nilmtk.metrics.error_in_assigned_energy(predictions, ground_truth)[source]

Compute error in assigned energy.

\[error^{(n)} = \left | \sum_t y^{(n)}_t - \sum_t \hat{y}^{(n)}_t \right |\]
Parameters:

predictions, ground_truth : nilmtk.MeterGroup
Returns:

errors : pd.Series

Each index is an meter instance int (or tuple for MeterGroups). Each value is the absolute error in assigned energy for that appliance, in kWh.
nilmtk.metrics.f1_score(predictions, ground_truth)[source]

Compute F1 scores.

\[F_{score}^{(n)} = \frac {2 * Precision * Recall} {Precision + Recall}\]
Parameters:

predictions, ground_truth : nilmtk.MeterGroup
Returns:

f1_scores : pd.Series

Each index is an meter instance int (or tuple for MeterGroups). Each value is the F1 score for that appliance. If there are multiple chunks then the value is the weighted mean of the F1 score for each chunk.
nilmtk.metrics.fraction_energy_assigned_correctly(predictions, ground_truth)[source]

Compute fraction of energy assigned correctly

\[fraction = \sum_n min \left ( \frac{\sum_n y}{\sum_{n,t} y}, \frac{\sum_n \hat{y}}{\sum_{n,t} \hat{y}} \right )\]

Ignores distinction between different AC types, instead if there are multiple AC types for each meter then we just take the max value across the AC types.

Parameters:

predictions, ground_truth : nilmtk.MeterGroup
Returns:

fraction : float in the range [0,1]

Fraction of Energy Correctly Assigned.
nilmtk.metrics.mean_normalized_error_power(predictions, ground_truth)[source]

Compute mean normalized error in assigned power

\[error^{(n)} = \frac { \sum_t {\left | y_t^{(n)} - \hat{y}_t^{(n)} \right |} } { \sum_t y_t^{(n)} }\]
Parameters:

predictions, ground_truth : nilmtk.MeterGroup
Returns:

mne : pd.Series

Each index is an meter instance int (or tuple for MeterGroups). Each value is the MNE for that appliance.
nilmtk.metrics.rms_error_power(predictions, ground_truth)[source]

Compute RMS error in assigned power

\[error^{(n)} = \sqrt{ \frac{1}{T} \sum_t{ \left ( y_t - \hat{y}_t \right )^2 } }\]
Parameters:

predictions, ground_truth : nilmtk.MeterGroup
Returns:

error : pd.Series

Each index is an meter instance int (or tuple for MeterGroups). Each value is the RMS error in predicted power for that appliance.

nilmtk.plots module

nilmtk.plots.format_axes(ax)[source]
nilmtk.plots.latexify(fig_width=None, fig_height=None, columns=1)[source]

Set up matplotlib’s RC params for LaTeX plotting. Call this before plotting a figure.

Parameters:

fig_width : float, optional, inches

fig_height : float, optional, inches

columns : {1, 2}
nilmtk.plots.plot_series(series, **kwargs)[source]

Plot function for series which is about 5 times faster than pd.Series.plot().

Parameters:

ax : matplotlib Axes, optional

If not provided then will generate our own axes.

fig :

date_format : str, optional, default=’%d/%m/%y %H:%M:%S’

Can also use all **kwargs expected by `ax.plot` :

nilmtk.utils module

nilmtk.utils.container_to_string(container, sep='_')[source]
nilmtk.utils.find_nearest(known_array, test_array)[source]

Find closest value in known_array for each element in test_array.

Parameters:

known_array : numpy array

consisting of scalar values only; shape: (m, 1)

test_array : numpy array

consisting of scalar values only; shape: (n, 1)
Returns:

indices : numpy array; shape: (n, 1)

For each value in test_array finds the index of the closest value in known_array.

residuals : numpy array; shape: (n, 1)

For each value in test_array finds the difference from the closest value in known_array.
nilmtk.utils.flatten_2d_list(list2d)[source]
nilmtk.utils.get_index(data)[source]
Parameters:data : pandas.DataFrame or Series or DatetimeIndex
Returns:index : the index for the DataFrame or Series
nilmtk.utils.index_of_column_name(df, name)[source]
nilmtk.utils.nodes_adjacent_to_root(graph)[source]
nilmtk.utils.simplest_type_for(values)[source]
nilmtk.utils.timedelta64_to_secs(timedelta)[source]

Convert timedelta to seconds.

Parameters:timedelta : np.timedelta64
Returns:float : seconds
nilmtk.utils.tree_root(graph)[source]

Returns the object that is the root of the tree.

Parameters:graph : networkx.Graph

nilmtk.version module

Module contents