# Arguebuf Python
Arguebuf is a format for serializing argument graphs and specified using Protobuf.
The complete specification and documentation is available at the [Buf Schema Registry](https://buf.build/recap/arg-services/docs/main:arg_services.graph.v1).
While Protobuf automatically generates native code for all major programming languages (including Python), we created a custom implementation that provides some additional benefits, including:
- The ability to import existing formats like [AIF](http://www.argumentinterchange.org), [SADFace](https://github.com/Open-Argumentation/SADFace), and a few others.
- Export of Arguebuf graphs to AIF, [NetworkX](https://networkx.org), and [Graphviz](https://graphviz.org).
- Integration with the popular NLP library [spaCy](http://spacy.io).
- Various helper methods to programmatically manipulate/create argument graphs.
- More pythonic interfaces than the regular code generated by `protoc`.
You can easily install the library from [PyPI](https://pypi.org/project/arguebuf/) using pip. The documentation is hosted on [ReadTheDocs](https://arguebuf.readthedocs.io/en/latest/)
## Command Line Interface (CLI)
We also offer some tools to simplify dealing with structured argument graphs.
Among others, it is possible to convert graphs between different formats, translate them, and render images using graphviz.
To use it, install the `cli` extras when installing the package.
When using `pip`, this can be accomplished with
`pip install arguebuf[cli]`
Afterwards, you can execute it by calling `arguebuf`, for example:
`arguebuf --help`
Alternatively, you can use the Docker image available at `ghcr.io/recap-utr/arguebuf-python`.
To use it, mount a folder to the container and pass the options as the command.
`docker run --rm -it -v $(pwd)/data:/data ghcr.io/recap-utr/arguebuf-python:latest --help`
If you use the `nix` package manager, you can run it as follows:
`nix run github:recap-utr/arguebuf-python -- --help`
## Theoretical Foundations
An argument graph is way to represent _structured_ argumentation.
What sets it apart from _unstructured_ argumentation (e.g., in newspaper articles) is that only the essential/argumentative parts of a text art part of this representation.
These _units_ of argumentation are also called ADUs (argumentative discourse units).
The length of ADUs can differ dramatically (depending on various factors like the context), meaning they might contain only a few words, a sentence, or even a whole paragraph.
The structure of an argument is then represented through _relations_ between these units.
For this purpose, they can be further subdivided into _claims_ and _premises_:
A claim is a statement that is supported or attacked by one or multiple premises.
At the same time, a claim may also function as a premise for another claim, making it possible to construct even complex _argument graphs_.
One of the claims is called _major claim_ and represents the overall claim of the whole argument.
In many cases (but not all), this major claim is located right at the top of the graph
Here is a rather simple example.
Claims, premises and the major claim are represented as _atom nodes_ while relations between them are represented by _scheme nodes_.
The set of nodes $V = A \cup S$ is composed of the set of atom nodes $A$ and the set of scheme nodes $S$.
The supporting or attacking relations are encoded in a set of edges $E \subseteq V \times V \setminus A \times A$.
Edges can be drawn between any type of nodes except for two atom nodes.
For instance, it is possible to connect two scheme nodes to support or attack the _inference_ between two ADUs.
Based on this, we define an argument graph $G$ as the triple $G = ( V , E , M )$.
## User Guide
When importing this library, we recommend using an abbreviation such as `ag` (for _argument graph_).
```python
import arguebuf as ag
```
In the following, we will introduce the most important features of `arguebuf`.
For more details including examples, check out our API documentation.
### Importing an Existing Graph
We support multiple established formats to represent argument graphs: `AIF`, `OVA`, `SADFace`, `ArgDown`, `BRAT`, and `Kialo`.
Given an input file, the library can automatically determine the correct format and convert it to a representation in the `arguebuf` format.
One can either pass a string pointing to the file or a `pathlib.Path` object.
```python
graph = ag.load.file("graph.json")
```
It is also possible to load multiple graphs within a folder.
Here, you need to pass the folder along with a [glob pattern](https://docs.python.org/3/library/fnmatch.html#module-fnmatch) for selecting the argument graphs.
This also enables to recursively load all argument graphs from a common parent directory.
```python
graphs = ag.load.folder("./data", "**/*.json")
```
Since atom nodes contain textual information that may need to be analyzed using NLP techniques, we support passing a custom `nlp` function to these loader methods.
This also makes it really easy to integrate the popular [`spacy` library](http://spacy.io) with `arguebuf` as all texts of atom nodes are automatically converted to a spacy `Doc`.
```python
import spacy
nlp = spacy.load("en_core_web_lg")
graph = ag.load.file("graph.json", nlp=nlp)
```
### Programmatically Create a New Graph
Instead of importing an existing graph, you can also create a new one using an object-oriented API using our library.
To illustrate this, we generate a graph with two premises that are connected to a major claim.
**Please note:** In case edges with nodes not yet contained in the graph are added, the respective nodes are added automatically.
```python
graph = ag.Graph()
premise1 = ag.AtomNode("Text of premise 1")
premise2 = ag.AtomNode("Text of premise 2")
claim = ag.AtomNode("Text of claim")
scheme1 = ag.SchemeNode(ag.Support.DEFAULT)
scheme2 = ag.SchemeNode(ag.Attack.DEFAULT)
graph.add_edge(ag.Edge(premise1, scheme1))
graph.add_edge(ag.Edge(scheme1, claim))
graph.add_edge(ag.Edge(premise2, scheme2))
graph.add_edge(ag.Edge(scheme2, claim))
graph.major_claim = claim
gv_graph = ag.dump.graphviz(graph)
ag.render.graphviz(gv_graph, "./assets/programmatic.png")
```
With this code, we get the following output
### Exporting Argument Graphs
We support different output formats and integration with other libraries to ease the use of argument graphs.
Have a look at the following code snippet to get an overview of the possibilities
```python
# Export to graphviz DOT format
dot = ag.dump.graphviz(graph)
# Export an image of this dot source to a file
ag.render.graphviz(dot, "./graph.pdf")
# Convert to NetworkX graph
nx = ag.dump.networkx(graph)
# Save the graph as Arguebuf
ag.dump.file(graph, "./graph.json")
# Save the graph as AIF
ag.dump.file(graph, "./graph.json", ag.GraphFormat.AIF)
```
## Development
To pull the testing data, make sure to install [DVC](https://dvc.org/doc/install) and run `dvc pull` in the root directory of the repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/recap-utr/arguebuf-python",
"name": "arguebuf",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Mirko Lenz",
"author_email": "info@mirko-lenz.de",
"download_url": "https://files.pythonhosted.org/packages/9f/b3/9a086ef201d3bbf6a266aeada21193756cb43573dd09ea67c7619611a01a/arguebuf-2.6.3.tar.gz",
"platform": null,
"description": "# Arguebuf Python\n\nArguebuf is a format for serializing argument graphs and specified using Protobuf.\nThe complete specification and documentation is available at the [Buf Schema Registry](https://buf.build/recap/arg-services/docs/main:arg_services.graph.v1).\nWhile Protobuf automatically generates native code for all major programming languages (including Python), we created a custom implementation that provides some additional benefits, including:\n\n- The ability to import existing formats like [AIF](http://www.argumentinterchange.org), [SADFace](https://github.com/Open-Argumentation/SADFace), and a few others.\n- Export of Arguebuf graphs to AIF, [NetworkX](https://networkx.org), and [Graphviz](https://graphviz.org).\n- Integration with the popular NLP library [spaCy](http://spacy.io).\n- Various helper methods to programmatically manipulate/create argument graphs.\n- More pythonic interfaces than the regular code generated by `protoc`.\n\nYou can easily install the library from [PyPI](https://pypi.org/project/arguebuf/) using pip. The documentation is hosted on [ReadTheDocs](https://arguebuf.readthedocs.io/en/latest/)\n\n## Command Line Interface (CLI)\n\nWe also offer some tools to simplify dealing with structured argument graphs.\nAmong others, it is possible to convert graphs between different formats, translate them, and render images using graphviz.\nTo use it, install the `cli` extras when installing the package.\nWhen using `pip`, this can be accomplished with\n\n`pip install arguebuf[cli]`\n\nAfterwards, you can execute it by calling `arguebuf`, for example:\n\n`arguebuf --help`\n\nAlternatively, you can use the Docker image available at `ghcr.io/recap-utr/arguebuf-python`.\nTo use it, mount a folder to the container and pass the options as the command.\n\n`docker run --rm -it -v $(pwd)/data:/data ghcr.io/recap-utr/arguebuf-python:latest --help`\n\nIf you use the `nix` package manager, you can run it as follows:\n\n`nix run github:recap-utr/arguebuf-python -- --help`\n\n## Theoretical Foundations\n\nAn argument graph is way to represent _structured_ argumentation.\nWhat sets it apart from _unstructured_ argumentation (e.g., in newspaper articles) is that only the essential/argumentative parts of a text art part of this representation.\nThese _units_ of argumentation are also called ADUs (argumentative discourse units).\nThe length of ADUs can differ dramatically (depending on various factors like the context), meaning they might contain only a few words, a sentence, or even a whole paragraph.\nThe structure of an argument is then represented through _relations_ between these units.\nFor this purpose, they can be further subdivided into _claims_ and _premises_:\nA claim is a statement that is supported or attacked by one or multiple premises.\nAt the same time, a claim may also function as a premise for another claim, making it possible to construct even complex _argument graphs_.\nOne of the claims is called _major claim_ and represents the overall claim of the whole argument.\nIn many cases (but not all), this major claim is located right at the top of the graph\nHere is a rather simple example.\n\n\n\nClaims, premises and the major claim are represented as _atom nodes_ while relations between them are represented by _scheme nodes_.\nThe set of nodes $V = A \\cup S$ is composed of the set of atom nodes $A$ and the set of scheme nodes $S$.\nThe supporting or attacking relations are encoded in a set of edges $E \\subseteq V \\times V \\setminus A \\times A$.\nEdges can be drawn between any type of nodes except for two atom nodes.\nFor instance, it is possible to connect two scheme nodes to support or attack the _inference_ between two ADUs.\nBased on this, we define an argument graph $G$ as the triple $G = ( V , E , M )$.\n\n## User Guide\n\nWhen importing this library, we recommend using an abbreviation such as `ag` (for _argument graph_).\n\n```python\nimport arguebuf as ag\n```\n\nIn the following, we will introduce the most important features of `arguebuf`.\nFor more details including examples, check out our API documentation.\n\n### Importing an Existing Graph\n\nWe support multiple established formats to represent argument graphs: `AIF`, `OVA`, `SADFace`, `ArgDown`, `BRAT`, and `Kialo`.\nGiven an input file, the library can automatically determine the correct format and convert it to a representation in the `arguebuf` format.\nOne can either pass a string pointing to the file or a `pathlib.Path` object.\n\n```python\ngraph = ag.load.file(\"graph.json\")\n```\n\nIt is also possible to load multiple graphs within a folder.\nHere, you need to pass the folder along with a [glob pattern](https://docs.python.org/3/library/fnmatch.html#module-fnmatch) for selecting the argument graphs.\nThis also enables to recursively load all argument graphs from a common parent directory.\n\n```python\ngraphs = ag.load.folder(\"./data\", \"**/*.json\")\n```\n\nSince atom nodes contain textual information that may need to be analyzed using NLP techniques, we support passing a custom `nlp` function to these loader methods.\nThis also makes it really easy to integrate the popular [`spacy` library](http://spacy.io) with `arguebuf` as all texts of atom nodes are automatically converted to a spacy `Doc`.\n\n```python\nimport spacy\nnlp = spacy.load(\"en_core_web_lg\")\ngraph = ag.load.file(\"graph.json\", nlp=nlp)\n```\n\n### Programmatically Create a New Graph\n\nInstead of importing an existing graph, you can also create a new one using an object-oriented API using our library.\nTo illustrate this, we generate a graph with two premises that are connected to a major claim.\n**Please note:** In case edges with nodes not yet contained in the graph are added, the respective nodes are added automatically.\n\n```python\ngraph = ag.Graph()\n\npremise1 = ag.AtomNode(\"Text of premise 1\")\npremise2 = ag.AtomNode(\"Text of premise 2\")\nclaim = ag.AtomNode(\"Text of claim\")\n\nscheme1 = ag.SchemeNode(ag.Support.DEFAULT)\nscheme2 = ag.SchemeNode(ag.Attack.DEFAULT)\n\ngraph.add_edge(ag.Edge(premise1, scheme1))\ngraph.add_edge(ag.Edge(scheme1, claim))\ngraph.add_edge(ag.Edge(premise2, scheme2))\ngraph.add_edge(ag.Edge(scheme2, claim))\n\ngraph.major_claim = claim\ngv_graph = ag.dump.graphviz(graph)\nag.render.graphviz(gv_graph, \"./assets/programmatic.png\")\n```\n\nWith this code, we get the following output\n\n\n\n### Exporting Argument Graphs\n\nWe support different output formats and integration with other libraries to ease the use of argument graphs.\nHave a look at the following code snippet to get an overview of the possibilities\n\n```python\n# Export to graphviz DOT format\ndot = ag.dump.graphviz(graph)\n\n# Export an image of this dot source to a file\nag.render.graphviz(dot, \"./graph.pdf\")\n\n# Convert to NetworkX graph\nnx = ag.dump.networkx(graph)\n\n# Save the graph as Arguebuf\nag.dump.file(graph, \"./graph.json\")\n\n# Save the graph as AIF\nag.dump.file(graph, \"./graph.json\", ag.GraphFormat.AIF)\n```\n\n## Development\n\nTo pull the testing data, make sure to install [DVC](https://dvc.org/doc/install) and run `dvc pull` in the root directory of the repository.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create and analyze argument graphs and serialize them via Protobuf",
"version": "2.6.3",
"project_urls": {
"Documentation": "https://arguebuf.readthedocs.io/en/latest",
"Homepage": "https://github.com/recap-utr/arguebuf-python",
"Repository": "https://github.com/recap-utr/arguebuf-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe5c44180103abfa67cc25ea3338e387987d9ae13d79889086e4d27b187f121a",
"md5": "914d9a517ff83beede3f4a84e6930565",
"sha256": "ca2d35b15f85adb3ab22122df7fdd94a4d68f57156c46be3702a5bf8a90e4dee"
},
"downloads": -1,
"filename": "arguebuf-2.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "914d9a517ff83beede3f4a84e6930565",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 65484,
"upload_time": "2024-11-17T12:33:52",
"upload_time_iso_8601": "2024-11-17T12:33:52.955689Z",
"url": "https://files.pythonhosted.org/packages/fe/5c/44180103abfa67cc25ea3338e387987d9ae13d79889086e4d27b187f121a/arguebuf-2.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9fb39a086ef201d3bbf6a266aeada21193756cb43573dd09ea67c7619611a01a",
"md5": "027fe8ab1988fbe78b4793082ef355a6",
"sha256": "956add261a61015020a6e9fc17544d8b863ecb6bd146ab319b55b0c8149ab926"
},
"downloads": -1,
"filename": "arguebuf-2.6.3.tar.gz",
"has_sig": false,
"md5_digest": "027fe8ab1988fbe78b4793082ef355a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 46603,
"upload_time": "2024-11-17T12:33:55",
"upload_time_iso_8601": "2024-11-17T12:33:55.132482Z",
"url": "https://files.pythonhosted.org/packages/9f/b3/9a086ef201d3bbf6a266aeada21193756cb43573dd09ea67c7619611a01a/arguebuf-2.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-17 12:33:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "recap-utr",
"github_project": "arguebuf-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "arguebuf"
}
JSON
