{"id":23438505,"url":"https://github.com/lszeremeta/knows","last_synced_at":"2026-01-05T08:10:17.404Z","repository":{"id":219645599,"uuid":"749542720","full_name":"lszeremeta/knows","owner":"lszeremeta","description":"Property graph benchmark with node and edges generation, multiple output formats, and visualization","archived":false,"fork":false,"pushed_at":"2024-10-29T15:37:34.000Z","size":91,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T13:17:07.898Z","etag":null,"topics":["benchmark","generator","graphml","graphml-generator","graphs","property-graphs","yars-pg"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lszeremeta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-28T21:40:06.000Z","updated_at":"2024-10-29T15:37:37.000Z","dependencies_parsed_at":"2024-06-20T06:27:55.037Z","dependency_job_id":null,"html_url":"https://github.com/lszeremeta/knows","commit_stats":null,"previous_names":["lszeremeta/knows"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lszeremeta%2Fknows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lszeremeta%2Fknows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lszeremeta%2Fknows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lszeremeta%2Fknows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lszeremeta","download_url":"https://codeload.github.com/lszeremeta/knows/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248672218,"owners_count":21143242,"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":["benchmark","generator","graphml","graphml-generator","graphs","property-graphs","yars-pg"],"created_at":"2024-12-23T14:49:49.612Z","updated_at":"2026-01-03T00:20:10.162Z","avatar_url":"https://github.com/lszeremeta.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://raw.githubusercontent.com/lszeremeta/knows/main/logo/knows-logo.png\" alt=\"Knows logo\" width=\"300\"\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/knows)](https://pypi.org/project/knows/) [![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/lszeremeta/knows?label=Docker%20image%20size)](https://hub.docker.com/r/lszeremeta/knows)\n\nKnows is a powerful and user-friendly tool for generating property graphs. These graphs are crucial in many fields.\nKnows supports\nmultiple output formats and basic visualization capabilities, making it a go-to tool for researchers, educators and data\nenthusiasts.\n\n## Key Features 🚀\n\n- **Customizable Graph Generation**: Tailor your graphs by specifying the number of nodes and edges.\n- **Diverse Output Formats**: Export graphs in formats like\n  GraphML, [YARS-PG 5.0](https://github.com/lszeremeta/yarspg), CSV, Cypher, GEXF, GML, JSON, and others.\n- **Flexible Output Options**: Display results in the console, redirect them, or save them directly to a file.\n- **Integrated Graph Visualization**: Conveniently visualize your graphs in SVG, PNG, JPG, or PDF format.\n- **Intuitive Command-Line Interface (CLI)**: A user-friendly CLI for streamlined graph generation and visualization.\n- **Docker Compatibility**: Deploy Knows in Docker containers for a consistent and isolated runtime environment.\n- **Selectable Properties**: Choose which node and edge properties should be generated.\n- **Custom Schema Support**: Define custom node/edge types and properties using GQL-inspired (ISO/IEC 39075) JSON schema\n  files. Includes [JSON Schema](https://github.com/lszeremeta/knows/knows/schema.json) for validation. Schemas support many data types (String, Int, Float, Date,\n  enums, and more), symmetric edge properties (for mutual relationships), computed node properties (like degree), and\n  type constraints. See [SCHEMA.md](https://github.com/lszeremeta/knows/SCHEMA.md) for full documentation.\n- **Reproducible graphs**: Ensure deterministic outputs by setting the `-s`/`--seed` option regardless of the selected\n  output format.\n\n\u003e **Note on reproducibility:** The `-s`/`--seed` option makes the random aspects of graph generation deterministic\n\u003e within the same software environment. Results may still differ across versions of Python or dependencies.\n\n## Graph Structure\n\n- Generates graphs with specified or random nodes and edges.\n- Creates directed graphs.\n- Nodes are labeled `Person` with unique IDs (`N1, N2, N3, ..., Nn`).\n- Nodes feature `firstName` and `lastName` properties by default.\n- Edges are labeled `knows` and include `strength` [1..100] and `lastMeetingDate` [1955-01-01..2025-06-28] properties by\n  default.\n- Additional node properties:\n    - `favoriteColor`\n    - `company`\n    - `job`\n    - `phoneNumber`\n    - `postalAddress`\n    - `friendCount` (actual node degree - number of unique connections)\n    - `preferredContactMethod` [`inPerson`, `email`, `postalMail`, `phone`, `textMessage`, `videoCall`, `noPreference`]\n- Additional edge properties:\n    - `lastMeetingCity`\n    - `meetingCount` [1..10000]\n- Edges have random nodes, avoiding cycles.\n- If edges connect the same nodes in both directions, the paired edges share `lastMeetingCity`, `lastMeetingDate`, and\n  `meetingCount` values.\n\n## Installation 🛠️\n\nYou can install knows via PyPI, Docker or run it from the source code.\n\n### Install via PyPI\n\n1. **Installation**:\n   ```shell\n   pip install knows[draw]\n   ```\n   The `draw` installs a `matplotlib` and `scipy` libraries for graph visualization. You can omit the `[draw]` if you\n   don't need visualization and `svg` output generation.\n\n2. **Running Knows**:\n   ```shell\n   knows [options]\n   ```\n\n### Docker Deployment 🐳\n\n#### From Docker Hub\n\n1. **Pull Image**:\n   ```shell\n   docker pull lszeremeta/knows\n   ```\n\n2. **Run Container**:\n   ```shell\n   docker run --rm lszeremeta/knows [options]\n   ```\n\n#### Building from Source\n\n1. **Build Image**:\n   ```shell\n   docker build -t knows .\n   ```\n\n2. **Run Container**:\n   ```shell\n   docker run --rm knows [options]\n   ```\n\n### Python from Source\n\n1. **Clone Repository**:\n   ```shell\n   git clone git@github.com:lszeremeta/knows.git\n   cd knows\n   ```\n\n2. **Install Requirements**:\n   ```shell\n   pip install .[draw]\n   ```\n\n3. **Execute Knows**:\n   ```shell\n   python -m knows [options]\n   ```\n\n### Install Tkinter for Graph Visualization\n\nThe `-d`/`--draw` option requires Tkinter.\n\n- **Ubuntu**:\n  ```shell\n  sudo apt update\n  sudo apt install python3-tk\n  ```\n  See [Installing Tkinter on Ubuntu](https://www.pythonguis.com/installation/install-tkinter-linux/) for details.\n\n- **macOS (Homebrew)**:\n  ```shell\n  brew install python3\n  brew install python-tk\n  ```\n  See [Installing Tkinter on macOS](https://www.pythonguis.com/installation/install-tkinter-mac/) for details.\n\n- **Windows**:\n  On Windows, Tkinter should be installed by default with Python. No additional steps required.\n\n## Usage 💡\n\n### Basic Usage\n\n```shell\nknows [-h] [-n NODES] [-e EDGES] [-s SEED] [-v]\n             [-f {yarspg,graphml,csv,cypher,gexf,gml,svg,png,jpg,pdf,adjacency_list,multiline_adjacency_list,edge_list,json}]\n             [-np [{firstName,lastName,company,job,phoneNumber,favoriteColor,postalAddress,preferredContactMethod,friendCount} ...]]\n             [-ep [{strength,lastMeetingCity,lastMeetingDate,meetingCount} ...]] [-ap] [--schema FILE] [-d]\n             [output]\n```\n\n\u003e Available options may vary depending on the version. To display all available options with their descriptions use\n`knows -h`.\n\n### Positional arguments\n\n- `output`: Optional path to save the graph. For CSV format two files will be created: `*_nodes.csv` and `*_edges.csv`.\n\n### Options\n\n- `-h`, `--help`: Show help message and exit.\n- `-n NODES`, `--nodes NODES`: Number of nodes in the graph. Selected randomly if not specified.\n- `-e EDGES`, `--edges EDGES`: Number of edges in the graph. Selected randomly if not specified.\n- `-s SEED`, `--seed SEED`: Seed for random number generation to ensure reproducible results (also between various\n  output formats).\n- `-v`, `--version`: Show program version and exit.\n- `-f {yarspg,graphml,csv,cypher,gexf,gml,svg,png,jpg,pdf,adjacency_list,multiline_adjacency_list,edge_list,json}, --format {yarspg,graphml,csv,cypher,gexf,gml,svg,png,jpg,pdf,adjacency_list,multiline_adjacency_list,edge_list,json}`:\nFormat to output the graph. Default: `yarspg`. The `svg`, `png`, `jpg` and `pdf` formats are for simple graph\nvisualization.\n- `-np [{firstName,lastName,company,job,phoneNumber,favoriteColor,postalAddress,friendCount,preferredContactMethod} ...], --node-props [{firstName,lastName,company,job,phoneNumber,favoriteColor,postalAddress,friendCount,preferredContactMethod} ...]`:  \nSpace-separated node properties. Available: `firstName`, `lastName`, `company`, `job`, `phoneNumber`, `favoriteColor`,\n`postalAddress`, `preferredContactMethod` `friendCount`. Ignored when `--schema` is used.\n- `-ep [{strength,lastMeetingCity,lastMeetingDate,meetingCount} ...]`,  \n  `--edge-props [{strength,lastMeetingCity,lastMeetingDate,meetingCount} ...]`:  \n  Space-separated edge properties. Available: `strength`, `lastMeetingCity`, `lastMeetingDate`, `meetingCount`. Ignored when `--schema` is used.\n- `-ap`, `--all-props`: Use all available node and edge properties. Ignored when `--schema` is used.\n- `--schema FILE`: Path to JSON schema file defining custom node/edge types and properties. When specified,\n  overrides `-np`, `-ep`, and `-ap` options. GQL-inspired schema format ([ISO/IEC 39075](https://www.iso.org/standard/76120.html)).\n  See [SCHEMA.md](https://github.com/lszeremeta/knows/SCHEMA.md) for details.\n- `-d`, `--draw`: Show simple image of the graph. Requires Tkinter. This option\n  may not work in Docker. If you want to generate an image of the graph, use the `svg`, `png`, `jpg`, or `pdf` output\n  format and save it to a file.\n\n### Practical Examples 🌟\n\n1. Create a random graph in [YARS-PG 5.0 format](https://github.com/lszeremeta/yarspg) and show it:\n   ```shell\n   knows\n   # or\n   docker run --rm lszeremeta/knows\n   ```\n2. Create a 100-node, 70-edge graph in GraphML format:\n   ```shell\n   knows -n 100 -e 70 -f graphml \u003e graph.graphml\n   # or\n   knows -n 100 -e 70 -f graphml graph.graphml\n   # or\n   docker run --rm lszeremeta/knows -n 100 -e 70 -f graphml \u003e graph.graphml\n   # or\n   docker run --rm -v \"$(pwd)\":/data lszeremeta/knows -n 100 -e 70 -f graphml /data/graph.graphml\n   ```\n3. Create a random graph in CSV format and save to files (nodes are written to standard output, edges to standard\n   error):\n   ```shell\n   knows -f csv \u003e nodes.csv 2\u003e edges.csv\n   # or\n   knows -f csv graph.csv\n   # or\n   docker run --rm lszeremeta/knows -f csv \u003e nodes.csv 2\u003e edges.csv\n   # or\n   docker run --rm -v \"$(pwd)\":/data lszeremeta/knows -f csv /data/graph.csv\n   ```\n   The latter command creates `graph_nodes.csv` and `graph_edges.csv`.\n4. Create a 50-node, 20-edge graph in Cypher format:\n   ```shell\n   knows -n 50 -e 20 -f cypher \u003e graph.cypher\n   # or\n   knows -n 50 -e 20 -f cypher graph.cypher\n   ```\n5. Create a 100-node, 50-edge graph in YARS-PG format:\n   ```shell\n   knows -n 100 -e 50 \u003e graph.yarspg\n   # or\n   knows -n 100 -e 50 graph.yarspg\n   ```\n6. Create, save, and visualize a 100-node, 50-edge graph in SVG:\n   ```shell\n   knows -n 100 -e 50 -f svg -d \u003e graph.svg\n   # or\n   knows -n 100 -e 50 -f svg -d graph.svg\n   ```\n7. Create, save a 70-node, 50-edge graph in SVG:\n   ```shell\n   knows -n 70 -e 50 -f svg \u003e graph.svg\n   # or\n   knows -n 70 -e 50 -f svg graph.svg\n   ```\n8. Create, save a 10-node, 5-edge graph in PNG:\n   ```shell\n   knows -n 10 -e 5 -f png \u003e graph.png\n   # or\n   knows -n 10 -e 5 -f png graph.png\n   ```\n9. Create a graph in JSON format:\n   ```shell\n   knows -f json \u003e graph.json\n   # or\n   knows -f json graph.json\n   ```\n10. Create a graph with custom properties (20 nodes, 10 edges) and show it:\n   ```shell\n   knows -n 20 -e 10 -np firstName favoriteColor job -ep lastMeetingCity\n   ```\n11. Create a graph with all possible properties in YARS-PG format and save it to file:\n   ```shell\n   knows -ap \u003e graph.yarspg\n   # or\n   knows -ap graph.yarspg\n   ```\n12. Generate a reproducible graph in CSV by setting a seed:\n   ```shell\n   knows -n 3 -e 2 -s 43 -f csv\n   ```\n\nRunning the command again with the same seed will produce the identical graph, provided the environment and dependencies\nremain unchanged.\n\n13. Generate the same graph as above but in YARS-PG format:\n\n   ```shell\n   knows -n 3 -e 2 -s 43\n   ```\n\n14. Generate a graph using a custom schema file:\n   ```shell\n   knows -n 10 -e 15 -S schema-examples/employee_schema.json\n   # or\n   knows -n 10 -e 15 -S schema-examples/employee_schema.json -f cypher \u003e employees.cypher\n   ```\n\nSee [SCHEMA.md](https://github.com/lszeremeta/knows/SCHEMA.md) for full schema documentation and more examples.\n\n## Contribute to Knows 👥\n\nYour ideas and contributions can make Knows even better! If you're new to open source,\nread [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)\nand [CONTRIBUTING.md](https://github.com/lszeremeta/knows/blob/main/CONTRIBUTING.md).\n\n## License 📜\n\nKnows is licensed under the [MIT License](https://github.com/lszeremeta/knows/blob/main/LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flszeremeta%2Fknows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flszeremeta%2Fknows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flszeremeta%2Fknows/lists"}