Home

Awesome

NILM METADATA

NILM Metadata (where 'NILM' stands for 'non-instrusive load monitoring') is a metadata framework for describing appliances, meters, measurements, buildings and datasets.

Please jump in and add to or modify the schema and documentation!

Documentation

The documentation is available online.

If you're new to NILM Metadata then please read this README and then dive into the tutorial to find out how to see a worked example.

Or, if you are already familiar with NILM Metadata then perhaps you want direct access to the full description of the "Dataset metadata".

There are two sides to NILM Metadata:

1) A schema describing energy datasets

Modelled objects include:

The metadata itself can be either YAML or JSON.

2) Central metadata

Common info about appliances is stored in NILM Metadata. This includes:

The common info about appliances uses a simple but powerful inheritance mechanism to allow appliances to inherit from a other appliances. For example, laptop computer is a specialisation of computer and the two share several properties (e.g. both are in the ICT category). So laptop computer inherits from computer and modifies and adds any properties it needs. In this way, we can embrace the "don't repeat yourself (DRY)" principal by exploiting the relationship between appliances.

Python utilities

NILM Metadata comes with a Python module which collects all ApplianceTypes in central_metadata/appliance_types/*.yaml, performs inheritance and instantiates components and returns a dictionary where each key is an ApplianceType name and each value is an ApplianceType dict. Here's how to use it:

from nilm_metadata import get_appliance_types
appliance_types = get_appliance_types()

NILM Metadata also comes with a convert_yaml_to_hdf5() function which will convert a YAML instance of NILM Metadata to the HDF5 file format.

Research paper describing NILM metadata

The following paper describes NILM metadata in detail:

Bibtex:

@inproceedings{NILM_Metadata,
title = {{Metadata for Energy Disaggregation}},
author = {Kelly, Jack and Knottenbelt, William},
year = {2014},
month = jul,
address = {V{\" a}ster{\aa}s, Sweden},
booktitle = {The 2nd IEEE International Workshop on Consumer Devices and Systems (CDS 2014)},
archivePrefix = {arXiv},
arxivId = {1403.5946},
eprint = {1403.5946},
doi = {10.1109/COMPSACW.2014.97}
}

Please cite this paper if you use NILM metadata in academic research. But please also be aware that the online documentation is more up-to-date than the paper.

JSON Schema has been depreciated

In version 0.1 of the schema, we wrote a very comprehensive (and complex) schema using JSON Schema in order to automate the validation of metadata instances. JSON Schema is a lovely language and can capture everything we need but, because our metadata is quite comprehensive, we found that using JSON Schema was a significant time drain and made it hard to move quickly and add new ideas to the metadata. As such, when we moved from v0.1 to v0.2, the JSON Schema has been dropped. Please use the human-readable documentation instead. If there is a real desire for automated validation then we could resurrect the JSON Schema, but it is a fair amount of work to maintain.

However, there are YAML validators freely available to make sure you are using the correct YAML format. For example: YAMLlint

Installation

If you want to use the Python package in order to concatenate the common appliance metadata then please run:

sudo python setup.py develop

Please do not use python setup.py install until I have updated setup.py to copy the relevant *.yaml files. See issue #6.

Related projects