{"id":18829916,"url":"https://github.com/nilmtk/nilm_metadata","last_synced_at":"2025-04-14T03:41:04.985Z","repository":{"id":14533217,"uuid":"17247889","full_name":"nilmtk/nilm_metadata","owner":"nilmtk","description":"A schema for modelling meters, measurements, appliances, buildings etc","archived":false,"fork":false,"pushed_at":"2019-08-20T00:54:03.000Z","size":2215,"stargazers_count":51,"open_issues_count":20,"forks_count":50,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-12T19:51:35.701Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://nilm-metadata.readthedocs.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nilmtk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-27T12:22:42.000Z","updated_at":"2025-03-31T13:07:59.000Z","dependencies_parsed_at":"2022-09-26T20:10:24.730Z","dependency_job_id":null,"html_url":"https://github.com/nilmtk/nilm_metadata","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilmtk%2Fnilm_metadata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilmtk%2Fnilm_metadata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilmtk%2Fnilm_metadata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilmtk%2Fnilm_metadata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nilmtk","download_url":"https://codeload.github.com/nilmtk/nilm_metadata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248818525,"owners_count":21166438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T01:47:01.566Z","updated_at":"2025-04-14T03:41:04.972Z","avatar_url":"https://github.com/nilmtk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"NILM METADATA\n=============\n\nNILM Metadata (where 'NILM' stands for 'non-instrusive load\nmonitoring') is a metadata framework for describing appliances, meters,\nmeasurements, buildings and datasets.\n\nPlease jump in and add to or modify the schema and documentation!\n\n### Documentation\n\nThe\n[documentation is available online](http://nilm-metadata.readthedocs.org).\n\nIf you're new to NILM Metadata then please read this README and then\ndive into the [tutorial](http://nilm-metadata.readthedocs.org/en/latest/tutorial.html)\nto find out how \nto see a worked example.\n\nOr, if you are already familiar with NILM Metadata then perhaps you\nwant direct access to the full description of the\n\"[Dataset metadata](http://nilm-metadata.readthedocs.org/en/latest/dataset_metadata.html)\".\n\n## There are two sides to NILM Metadata:\n\n### 1) A schema describing energy datasets\n\nModelled objects include:\n\n* electricity meters (whole-home and individual appliance meters)\n  * wiring hierarchy of meters\n  * a controlled vocabulary for measurement names\n  * description of pre-processing applied\n  * storage of pre-processed statistics\n* domestic appliances\n  * a controlled vocabulary for appliance names\n  * each appliance can contain any number of components (e.g. a\n    light fitting can contain multiple lamps and a dimmer)\n  * a list of time periods when each appliance was active\n  * manufacturer, model, nominal power consumption etc.\n* a mapping of which appliances are connected to which meters\n* buildings\n* datasets \n\nThe metadata itself can be either\n[YAML](http://en.wikipedia.org/wiki/YAML) or JSON.\n\n### 2) Central metadata\n\nCommon info about appliances is stored in NILM Metadata.  This includes:\n\n* Categories for each appliance type\n* prior knowledge about the distribution of variables such as:\n  * on power\n  * on duration\n  * usage in terms of hour per day\n  * appliance correlations (e.g. that the TV is usually on if the\n    games console is on)\n* valid additional properties for each appliance\n* mapping from country codes to nominal mains voltage ranges\n\nThe common info about appliances uses a simple but powerful\ninheritance mechanism to allow appliances to inherit from a other\nappliances.  For example, `laptop computer` is a specialisation of\n`computer` and the two share several properties (e.g. both are in the\n`ICT` category).  So `laptop computer` inherits from `computer` and\nmodifies and adds any properties it needs.  In this way, we can\nembrace the\n[\"don't repeat yourself (DRY)\"](http://en.wikipedia.org/wiki/Don%27t_repeat_yourself)\nprincipal by exploiting the relationship between appliances.\n\n### Python utilities\n\nNILM Metadata comes with a Python module which collects all \nApplianceTypes in `central_metadata/appliance_types/*.yaml`,\nperforms inheritance and instantiates components and\nreturns a dictionary where each key is an ApplianceType name and each\nvalue is an ApplianceType dict.  Here's how to use it:\n\n```python\nfrom nilm_metadata import get_appliance_types\nappliance_types = get_appliance_types()\n```\n\nNILM Metadata also comes with a `convert_yaml_to_hdf5()` function\nwhich will convert a YAML instance of NILM Metadata to the HDF5 file\nformat.\n\n## Research paper describing NILM metadata\n\nThe following paper describes NILM metadata in detail:\n\n* Jack Kelly and William Knottenbelt (2014). **Metadata for Energy\n  Disaggregation**. In The 2nd IEEE International Workshop on Consumer\n  Devices and Systems (CDS 2014) in Västerås, Sweden.\n  arXiv:[1403.5946](http://arxiv.org/abs/1403.5946)\n  DOI:[10.1109/COMPSACW.2014.97](http://dx.doi.org/10.1109/COMPSACW.2014.97)\n\nBibtex:\n\n```\n@inproceedings{NILM_Metadata,\ntitle = {{Metadata for Energy Disaggregation}},\nauthor = {Kelly, Jack and Knottenbelt, William},\nyear = {2014},\nmonth = jul,\naddress = {V{\\\" a}ster{\\aa}s, Sweden},\nbooktitle = {The 2nd IEEE International Workshop on Consumer Devices and Systems (CDS 2014)},\narchivePrefix = {arXiv},\narxivId = {1403.5946},\neprint = {1403.5946},\ndoi = {10.1109/COMPSACW.2014.97}\n}\n```\n\nPlease cite this paper if you use NILM metadata in academic research.\nBut please also be aware that the online documentation is more\nup-to-date than the paper.\n\n\n## JSON Schema has been depreciated\n\nIn\n[version 0.1 of the schema](https://github.com/nilmtk/nilm_metadata/tree/v0.1.0),\nwe wrote a very comprehensive (and complex) schema using\n[JSON Schema](http://json-schema.org/) in order to automate the\nvalidation of metadata instances.  JSON Schema is a lovely language\nand can capture everything we need but, because our metadata is quite\ncomprehensive, we found that using JSON Schema was a significant time\ndrain and made it hard to move quickly and add new ideas to the\nmetadata.  As such, when we moved from v0.1 to v0.2, the JSON Schema\nhas been dropped.  Please use the\n[human-readable documentation](http://nilm-metadata.readthedocs.org)\ninstead.  If there is a real desire for automated validation then we\ncould resurrect the JSON Schema, but it is a fair amount of work to\nmaintain.\n\nHowever, there are YAML validators freely available to make sure you are \nusing the correct YAML format.  For example: [YAMLlint](http://www.yamllint.com)\n\n\nInstallation\n============\n\nIf you want to use the Python package in order to concatenate the\ncommon appliance metadata then please run:\n\n```\npython -m pip install -e .[dev]\n```\n\nTo exceute tests please run from the project root directory:\n\n```\npytest\n```\n\nTo generate documentation please run from the project root directory:\n\n```\nmake -C docs singlehtml\n```\n\nRelated projects\n================\n\n* [Project Haystack](http://project-haystack.org/), to quote their\n  website, \"*is an open source initiative to develop tagging\n  conventions and taxonomies for building equipment and operational\n  data. We define standardized data models for sites, equipment, and\n  points related to energy, HVAC, lighting, and other environmental\n  systems.*\"  Haystack is an awesome project but it does not specify a\n  controlled vocabulary for appliances, which is the meat of the\n  `nilm_metadata` project.  Where appropriate, `nilm_metadata` does\n  use similar properties to Haystack (e.g. the \"site_meter\" property\n  is borrowed directly from Haystack).\n* [WikiEnergy](http://wiki-energy.org/) \"*A Universe of Energy Data,\n  Available Around the World*\".\n* [sMAP metadata tags](http://www.eecs.berkeley.edu/~stevedh/smap2/tags.html)\n  - sMAP is Berkley's \"Simple Measurement and Actuation Profile\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnilmtk%2Fnilm_metadata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnilmtk%2Fnilm_metadata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnilmtk%2Fnilm_metadata/lists"}