wdn-knowledge-graph 1.1.5

A package for creating knowledge graphs from water distribution network data.

wdn-knowledge-graph

wdn-knowledge-graph is a Python package designed to convert water distribution network (WDN) data from .inp files ( the standard format for the EPANET tool) into RDF knowledge graphs in the .ttl format using a WDN ontology we created.

The WDN ontology in wdn_ontology.ttl captures the physical components of a WDN, inspired from the EPANET tool.

This package also provides the possibility of converting the final knowledge graph to the popular NetworkX format for further processing, making it easier to analyze and manipulate the water distribution network data.

---

Table of Contents

• Introduction
• Installation
• Usage
  • Command-Line Interface (CLI)
  • Using in a Python Program
• About
  • EPANET
  • TTL Files
  • INP Files
  • Ontology and Knowledge Graph
• Functions
  • create_knowledge_graph_from_inp
  • networkx
• Citation
• Contact
• Contributing

---

Introduction

wdn-knowledge-graph is a tool for creating RDF-based knowledge graphs from water distribution network (WDN) data. It reads an .inp file (the standard format for EPANET) and an ontology .ttl file, then generates a knowledge graph representing the water network. The package also provides a method to convert the generated RDF graph into a NetworkX graph for further analysis, leveraging the power of the NetworkX Python package.

You can use this package to model and analyze water distribution networks with ease and flexibility.

Please remember to cite our paper if you use this package in your work:

Installation

You can install wdn-knowledge-graph via pip:

pip install wdn-knowledge-graph

Usage

Command-Line Interface (CLI)

Once the package is installed, you can use it directly from the command line to construct a knowledge graph from a water distribution network .inp file. The construction of the knowledge graph uses our Water Distribution Network ontology (wdn_ontology.ttl).

create-knowledge-graph -i path_to_input_file.inp -d knowledge_graph.ttl

-i : Path to the .inp file containing water network data.

-d : Path to the output .ttl file to save the generated knowledge graph.

Using in a Python Program

Alternatively, you can use the package directly within a Python program by importing its functions. This allows for more flexibility in how you integrate it into your project.

Example:

from rdflib import Graph
from wdn_knowledge_graph.knowledge_graph import create_knowledge_graph_from_inp, networkx

# Define file paths
inp_file = 'EPANET input file.inp'
output_file = 'knowledge_graph.ttl'
ontology_file = 'wdn_ontology.ttl'

# Create the knowledge graph
knowledge_graph = create_knowledge_graph_from_inp(inp_file, destination=output_file)

# Convert the RDF knowledge graph to a NetworkX graph for further processing
ontology = Graph().parse(ontology_file, format='ttl')
networkx_graph = networkx(knowledge_graph, ontology)

print(networkx_graph)

In this example:

• create_knowledge_graph_from_inp() is used to generate the RDF knowledge graph from the .inp file and ontology.
• networkx() is then used to convert the RDF graph into a NetworkX graph, which can be analyzed or manipulated further.

About

This section explains some of the fundamental concepts behind the .inp file, .ttl (Turtle) files, EPANET, ontologies, and knowledge graphs that are used in this package.

• EPANET is a software application used to simulate water distribution systems. It models the hydraulic and water quality behavior of water distribution networks. EPANET uses the .inp file format to store input data describing the network, including pipes, junctions, tanks, reservoirs, and pumps.

• Turtle (TTL) is a human-readable serialization format for RDF (Resource Description Framework) data. RDF is a standard model for data interchange on the web. In the context of this package, TTL files are used to store knowledge graphs, which represent relationships between different entities (e.g., junctions, pipes, tanks).

• The .inp file format is a text-based format used by EPANET to define the components of a water distribution system, including junctions, pipes, pumps, valves, tanks, and reservoirs. These files contain data such as pipe lengths, junction demands, tank levels, etc., that describe how the water distribution system operates. Ontology and Knowledge Graph

• An ontology is a formal representation of knowledge within a particular domain. It defines the concepts, entities, and relationships that exist within that domain.

• A knowledge graph is a graph-based representation of information where nodes represent entities, and edges represent the relationships between these entities. It is often used to represent complex data, and in this case, the package creates a knowledge graph of a water distribution network.

Additionally, we provide a water distribution network ontology in the wdn_ontology.ttl file in the main folder. This ontology defines the relevant classes, properties, and relationships specific to water distribution networks.

Key Python Packages Used

This package makes use of several popular Python libraries for ease of use and performance:

• WNTR: A Python package for modeling and analyzing water distribution networks.
• RDFLib: A Python library for working with RDF data, parsing and serializing RDF files, and querying them using SPARQL.
• NetworkX: A Python package for the creation, manipulation, and study of the structure, dynamics, and functions of complex networks.

Sample Data

The sample data folder includes knowledge graphs created for the L-Town and LeakDB (Scenario 1) datasets.

• Knowledge graph constructed from the L-Town dataset
• Knowledge graph constructed from the LeakDB dataset

Functions

create_knowledge_graph_from_inp(inp_file, ontology_file, destination="output.ttl")

This function generates a knowledge graph in Turtle format (.ttl) from a water network .inp file and an ontology .ttl file. It creates an RDF graph representing the various entities in the water distribution system (e.g., junctions, pipes, tanks, etc.).

Parameters:

• inp_file: The path to the .inp file containing water network data.
• ontology_file: The path to the ontology .ttl file.
• destination: The file path to save the generated RDF graph (default is output.ttl).

Returns:

• An RDF Graph object representing the knowledge graph.

networkx(rdf_graph)

This function converts a Turtle file (knowledge graph) to a NetworkX graph for easier analysis and manipulation. It accepts either in RDFlib graph format or a string path to where the .ttl file is located. It processes both object properties and data properties from the ontology to create the appropriate nodes and edges in the NetworkX graph.

Parameters:

• rdf_graph: An RDFlib Graph object or a .ttl file with the knowledge graph to be converted.

Returns:

• A NetworkX directed graph (DiGraph).

Citation

If you use this package in your research or work, please cite the following paper:

@article{karabulut2024learning,
  title={Learning Semantic Association Rules from Internet of Things Data},
  author={Karabulut, Erkan and Groth, Paul and Degeler, Victoria},
  journal={arXiv preprint arXiv:2412.03417},
  year={2024}
}

Contact

If you have any questions or improvement ideas, feel free to contact Erkan Karabulut at:

Email: [e-mail]

Contributing

You can contribute to the project in any way you see fit! Whether it’s updating our WDN ontology, reporting bugs, suggesting new features, or submitting code, your input is welcome.

To contribute, please visit the project’s GitHub repository and start a discussion:

GitHub: wdn-knowledge-graph