# Abstract 🕸️
Abstract is a Python library designed for creating and visualizing graphs, enabling users to leverage various graph properties effectively.
## Installation
To install the library, simply run:
```bash
pip install abstract
```
## Graph
### Introduction
In computer science, a graph is an abstract data type that implements the concepts of undirected and directed graphs from mathematics, specifically within the field of graph theory. [[1]](https://en.wikipedia.org/wiki/Graph_(abstract_data_type))
A graph data structure consists of a finite (and potentially mutable) set of vertices (or nodes) and a set of unordered pairs of these vertices for undirected graphs, or ordered pairs for directed graphs. These pairs are referred to as edges, arcs, or lines in undirected graphs, and as arrows, directed edges, directed arcs, or directed lines in directed graphs. The vertices may be part of the graph structure or may be represented externally by integer indices or references. [[1]](https://en.wikipedia.org/wiki/Graph_(abstract_data_type))
### Usage
The `Graph` class allows you to create nodes and edges, as well as visualize the resulting graph. Edges can have direction, indicating parent-child relationships.
To create a new graph, use the `Graph()` constructor:
```python
from abstract import Graph
graph = Graph(direction='LR')
# The default direction is 'LR'; other options include 'TB', 'BT', and 'RL'.
```
### `add_node(...)`
The `add_node` method creates a node in the graph and returns a `Node` object.
It accepts the following arguments:
* `name`: The name of the new node (should be unique); snake_case is recommended.
* `label` (optional): Any string; if omitted, the name will be displayed.
* `value` (optional): Can be any object.
* `style` (optional): Should be a `NodeStyle` object, used only for rendering.
* `if_node_exists` (optional): Specifies the action if a node with this name already exists; options are 'warn', 'error', or 'ignore'; the default is 'warn'.
To illustrate how the `Graph` class works, let's use the [Rock, Paper, Scissors, Lizard, Spock](https://bigbangtheory.fandom.com/wiki/Rock,_Paper,_Scissors,_Lizard,_Spock) game. The following list shows the order in which an object in the game defeats the object to its right and is defeated by the object to its left. Note that there are only five objects, which are repeated to demonstrate all possible pairs.
```python
node_list = [
'scissors', 'paper', 'rock', 'lizard', 'Spock', 'scissors',
'lizard', 'paper', 'Spock', 'rock', 'scissors'
]
```
Now, let's create nodes with the same names:
```python
# Create a set to avoid duplicates
for node in set(node_list):
graph.add_node(name=node)
graph.display(direction='TB') # The left-right direction is too tall.
```
**Note**: By default, the Graph uses the colour theme from the [colouration](http://pypi.org/project/colouration) library for root nodes and determines the colour of other nodes based on the directionality of edges. In the above example, without any edges, all nodes are considered roots.
### `connect(...)` (Add an Edge)
The `connect` method creates an edge from a `start` node to an `end` node. The `start` and `end` arguments can be either the names of nodes or the `Node` objects themselves.
```python
for i in range(len(node_list) - 1):
graph.connect(start=node_list[i], end=node_list[i + 1])
graph.display(direction='LR') # The top-bottom direction is too tall.
```
**Note**: Nodes that form a loop are coloured differently (red circles with yellow interiors).
### *get_node*
To retrieve a node from the graph, use the `get_node` method, which returns a `Node` object.
```python
rock = graph.get_node('rock')
```
### `display(...)`
The `display` method visualizes the graph. If a `path` is provided, it saves the visualization to an image file, which can be in either *pdf* or *png* format. You can also specify the resolution using the `dpi` argument. The file format is inferred from the `path` argument.
```python
# Save as a PNG file and view the file
graph.draw(path='my_graph.png', view=True)
```
### `Graph(obj=...)`
You can create a graph from any object that has a `__graph__()` method. Examples of such objects include:
* `Graph` class from this library
* `Pensieve` class from the [pensieve](https://pypi.org/project/pensieve/) library
* `Page` class from the [internet.wikipedia](https://pypi.org/project/internet/) submodule
```python
from pensieve import Pensieve
from abstract import Graph
pensieve = Pensieve()
pensieve['two'] = 2
pensieve['three'] = 3
pensieve['four'] = lambda two: two * two
pensieve['five'] = 5
pensieve['six'] = lambda two, three: two * three
pensieve['seven'] = 7
pensieve['eight'] = lambda two, four: two * four
pensieve['nine'] = lambda three: three * three
pensieve['ten'] = lambda two, five: two * five
graph = Graph(obj=pensieve, direction='TB') # or Graph(pensieve)
graph.display()
```
### `random(...)`
The `random` method creates a random graph.
```python
g1 = Graph.random(num_nodes=8, connection_probability=0.4, seed=6)
g1
```
### Adding Two Graphs: `+`
You can easily add two graphs using the `+` operator. The result will contain the union of nodes and edges from both graphs.
```python
g2 = Graph.random(num_nodes=7, start_index=3, connection_probability=0.4, seed=41)
g2
```
```python
g3 = g1 + g2
g3
```
### Finding Loops
The `is_in_loop` method of a node helps identify nodes that form a loop; that is, nodes that have at least one descendant that is also an ancestor.
```python
graph_with_loop = Graph()
for letter in 'abcdef':
graph_with_loop.add_node(letter)
for start, end in [
('a', 'b'), ('b', 'c'), ('c', 'a'), ('c', 'd'), ('d', 'e'), ('e', 'f'), ('f', 'e')
]:
graph_with_loop.connect(start, end)
graph_with_loop
```
```python
for node in graph_with_loop.nodes:
if node.is_in_loop_with(other='a') and node.name != 'a':
print(node.name, 'is in the same loop as a')
elif node.is_in_loop():
print(node.name, 'is in a loop')
else:
print(node.name, 'is not in a loop')
```
Output:
```text
a is in a loop
b is in the same loop as a
c is in the same loop as a
d is not in a loop
e is in a loop
f is in a loop
```
## Future Features
* Create a graph from:
* List of dictionaries
* DataFrame
* Create a new graph by filtering an existing graph
Raw data
{
"_id": null,
"home_page": "https://github.com/idin/abstract",
"name": "abstract",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.6",
"maintainer_email": null,
"keywords": "graph",
"author": "Idin",
"author_email": "py@idin.ca",
"download_url": "https://files.pythonhosted.org/packages/61/29/41cb61cbb14c4bc1944e1370effc2b133a79e3104c38f808722f7d3d0a38/abstract-2025.2.17.0.tar.gz",
"platform": null,
"description": "# Abstract \ud83d\udd78\ufe0f\r\nAbstract is a Python library designed for creating and visualizing graphs, enabling users to leverage various graph properties effectively.\r\n\r\n## Installation\r\n\r\nTo install the library, simply run:\r\n\r\n```bash\r\npip install abstract\r\n```\r\n\r\n## Graph\r\n\r\n### Introduction\r\nIn computer science, a graph is an abstract data type that implements the concepts of undirected and directed graphs from mathematics, specifically within the field of graph theory. [[1]](https://en.wikipedia.org/wiki/Graph_(abstract_data_type))\r\n\r\nA graph data structure consists of a finite (and potentially mutable) set of vertices (or nodes) and a set of unordered pairs of these vertices for undirected graphs, or ordered pairs for directed graphs. These pairs are referred to as edges, arcs, or lines in undirected graphs, and as arrows, directed edges, directed arcs, or directed lines in directed graphs. The vertices may be part of the graph structure or may be represented externally by integer indices or references. [[1]](https://en.wikipedia.org/wiki/Graph_(abstract_data_type))\r\n\r\n### Usage\r\nThe `Graph` class allows you to create nodes and edges, as well as visualize the resulting graph. Edges can have direction, indicating parent-child relationships.\r\n\r\nTo create a new graph, use the `Graph()` constructor:\r\n\r\n```python\r\nfrom abstract import Graph\r\n\r\ngraph = Graph(direction='LR') \r\n# The default direction is 'LR'; other options include 'TB', 'BT', and 'RL'.\r\n```\r\n\r\n### `add_node(...)`\r\nThe `add_node` method creates a node in the graph and returns a `Node` object. \r\n\r\nIt accepts the following arguments:\r\n* `name`: The name of the new node (should be unique); snake_case is recommended.\r\n* `label` (optional): Any string; if omitted, the name will be displayed.\r\n* `value` (optional): Can be any object.\r\n* `style` (optional): Should be a `NodeStyle` object, used only for rendering.\r\n* `if_node_exists` (optional): Specifies the action if a node with this name already exists; options are 'warn', 'error', or 'ignore'; the default is 'warn'.\r\n\r\nTo illustrate how the `Graph` class works, let's use the [Rock, Paper, Scissors, Lizard, Spock](https://bigbangtheory.fandom.com/wiki/Rock,_Paper,_Scissors,_Lizard,_Spock) game. The following list shows the order in which an object in the game defeats the object to its right and is defeated by the object to its left. Note that there are only five objects, which are repeated to demonstrate all possible pairs.\r\n\r\n```python\r\nnode_list = [\r\n 'scissors', 'paper', 'rock', 'lizard', 'Spock', 'scissors',\r\n 'lizard', 'paper', 'Spock', 'rock', 'scissors'\r\n]\r\n```\r\n\r\nNow, let's create nodes with the same names:\r\n\r\n```python\r\n# Create a set to avoid duplicates\r\nfor node in set(node_list):\r\n graph.add_node(name=node)\r\n \r\ngraph.display(direction='TB') # The left-right direction is too tall.\r\n```\r\n\r\n\r\n**Note**: By default, the Graph uses the colour theme from the [colouration](http://pypi.org/project/colouration) library for root nodes and determines the colour of other nodes based on the directionality of edges. In the above example, without any edges, all nodes are considered roots.\r\n\r\n### `connect(...)` (Add an Edge)\r\nThe `connect` method creates an edge from a `start` node to an `end` node. The `start` and `end` arguments can be either the names of nodes or the `Node` objects themselves.\r\n\r\n```python\r\nfor i in range(len(node_list) - 1):\r\n graph.connect(start=node_list[i], end=node_list[i + 1])\r\ngraph.display(direction='LR') # The top-bottom direction is too tall.\r\n```\r\n\r\n\r\n**Note**: Nodes that form a loop are coloured differently (red circles with yellow interiors).\r\n\r\n### *get_node*\r\nTo retrieve a node from the graph, use the `get_node` method, which returns a `Node` object.\r\n\r\n```python\r\nrock = graph.get_node('rock')\r\n```\r\n\r\n### `display(...)`\r\nThe `display` method visualizes the graph. If a `path` is provided, it saves the visualization to an image file, which can be in either *pdf* or *png* format. You can also specify the resolution using the `dpi` argument. The file format is inferred from the `path` argument.\r\n\r\n```python\r\n# Save as a PNG file and view the file\r\ngraph.draw(path='my_graph.png', view=True)\r\n```\r\n\r\n### `Graph(obj=...)`\r\nYou can create a graph from any object that has a `__graph__()` method. Examples of such objects include: \r\n* `Graph` class from this library\r\n* `Pensieve` class from the [pensieve](https://pypi.org/project/pensieve/) library\r\n* `Page` class from the [internet.wikipedia](https://pypi.org/project/internet/) submodule\r\n\r\n```python\r\nfrom pensieve import Pensieve\r\nfrom abstract import Graph\r\n\r\npensieve = Pensieve()\r\npensieve['two'] = 2\r\npensieve['three'] = 3\r\npensieve['four'] = lambda two: two * two\r\npensieve['five'] = 5\r\npensieve['six'] = lambda two, three: two * three\r\npensieve['seven'] = 7\r\npensieve['eight'] = lambda two, four: two * four\r\npensieve['nine'] = lambda three: three * three\r\npensieve['ten'] = lambda two, five: two * five\r\ngraph = Graph(obj=pensieve, direction='TB') # or Graph(pensieve)\r\ngraph.display()\r\n```\r\n\r\n\r\n### `random(...)`\r\nThe `random` method creates a random graph.\r\n\r\n```python\r\ng1 = Graph.random(num_nodes=8, connection_probability=0.4, seed=6)\r\ng1\r\n```\r\n\r\n\r\n### Adding Two Graphs: `+`\r\nYou can easily add two graphs using the `+` operator. The result will contain the union of nodes and edges from both graphs.\r\n\r\n```python\r\ng2 = Graph.random(num_nodes=7, start_index=3, connection_probability=0.4, seed=41)\r\ng2\r\n```\r\n\r\n\r\n```python\r\ng3 = g1 + g2\r\ng3\r\n```\r\n\r\n\r\n### Finding Loops\r\nThe `is_in_loop` method of a node helps identify nodes that form a loop; that is, nodes that have at least one descendant that is also an ancestor.\r\n\r\n```python\r\ngraph_with_loop = Graph()\r\nfor letter in 'abcdef':\r\n graph_with_loop.add_node(letter)\r\nfor start, end in [\r\n ('a', 'b'), ('b', 'c'), ('c', 'a'), ('c', 'd'), ('d', 'e'), ('e', 'f'), ('f', 'e')\r\n]:\r\n graph_with_loop.connect(start, end)\r\ngraph_with_loop\r\n```\r\n\r\n\r\n```python\r\nfor node in graph_with_loop.nodes:\r\n if node.is_in_loop_with(other='a') and node.name != 'a':\r\n print(node.name, 'is in the same loop as a')\r\n elif node.is_in_loop():\r\n print(node.name, 'is in a loop')\r\n else:\r\n print(node.name, 'is not in a loop')\r\n```\r\nOutput:\r\n```text\r\na is in a loop\r\nb is in the same loop as a\r\nc is in the same loop as a\r\nd is not in a loop\r\ne is in a loop\r\nf is in a loop\r\n```\r\n\r\n## Future Features\r\n\r\n* Create a graph from:\r\n * List of dictionaries\r\n * DataFrame\r\n* Create a new graph by filtering an existing graph\r\n",
"bugtrack_url": null,
"license": "Conditional Freedom License (CFL-1.0)",
"summary": "Python library for creating and drawing graphs and taking advantage of graph properties",
"version": "2025.2.17.0",
"project_urls": {
"Homepage": "https://github.com/idin/abstract"
},
"split_keywords": [
"graph"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3496d309a1e6b993f17fa1b7639dabd0eb43b347610e3704eb4a4bc33bd43e24",
"md5": "a6b3e088ddea13245f7fb7f17c1d6dce",
"sha256": "dc0ba9510e90c59b8a8c23c34fe07990ee256171667b5b703d3dc3073b5e6483"
},
"downloads": -1,
"filename": "abstract-2025.2.17.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6b3e088ddea13245f7fb7f17c1d6dce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.6",
"size": 31812,
"upload_time": "2025-02-17T22:37:23",
"upload_time_iso_8601": "2025-02-17T22:37:23.170648Z",
"url": "https://files.pythonhosted.org/packages/34/96/d309a1e6b993f17fa1b7639dabd0eb43b347610e3704eb4a4bc33bd43e24/abstract-2025.2.17.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "612941cb61cbb14c4bc1944e1370effc2b133a79e3104c38f808722f7d3d0a38",
"md5": "12e1a8b9bf31093dfae2d95ea9effea5",
"sha256": "2e7a789595120aefce951a357fc622899599b7b4cb71500abde92f25f10847cd"
},
"downloads": -1,
"filename": "abstract-2025.2.17.0.tar.gz",
"has_sig": false,
"md5_digest": "12e1a8b9bf31093dfae2d95ea9effea5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.6",
"size": 27374,
"upload_time": "2025-02-17T22:37:25",
"upload_time_iso_8601": "2025-02-17T22:37:25.439660Z",
"url": "https://files.pythonhosted.org/packages/61/29/41cb61cbb14c4bc1944e1370effc2b133a79e3104c38f808722f7d3d0a38/abstract-2025.2.17.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-17 22:37:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "idin",
"github_project": "abstract",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "abstract"
}
JSON
