Package: arguebuf
Arguebuf PythonArguebuf is a format for serializing argument graphs and specified using Protobuf.
The complete specification and documentation is available at theBuf Schema Registry.
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 likeAIF,SADFace, and a few others.Export of Arguebuf graphs to AIF,NetworkX, andGraphviz.Integration with the popular NLP libraryspaCy.Various helper methods to programmatically manipulate/create argument graphs.More pythonic interfaces than the regular code generated byprotoc.You can easily install the library fromPyPIusing pip. The documentation is hosted onReadTheDocsCommand 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 thecliextras when installing the package.
When usingpip, this can be accomplished withpip install arguebuf[cli]Afterwards, you can execute it by callingarguebuf, for example:arguebuf --helpAlternatively, you can use the Docker image available atghcr.io/recap-utr/arguebuf-python.
To use it, mount a folder to the container and pass the options as the command.docker run --rm -v $(pwd)/data:/data ghcr.io/recap-utr/arguebuf-python:latest --rmIf you use thenixpackage manager, you can run it as follows:nix run github:recap-utr/arguebuf-python -- --helpTheoretical FoundationsAn argument graph is way to representstructuredargumentation.
What sets it apart fromunstructuredargumentation (e.g., in newspaper articles) is that only the essential/argumentative parts of a text art part of this representation.
Theseunitsof 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 throughrelationsbetween these units.
For this purpose, they can be further subdivided intoclaimsandpremises:
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 complexargument graphs.
One of the claims is calledmajor claimand 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 asatom nodeswhile relations between them are represented byscheme 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 theinferencebetween two ADUs.
Based on this, we define an argument graph $G$ as the triple $G = ( V , E , M )$.User GuideWhen importing this library, we recommend using an abbreviation such asag(forargument graph).importarguebufasagIn the following, we will introduce the most important features ofarguebuf.
For more details including examples, check out our API documentation.Importing an Existing GraphWe support multiple established formats to represent argument graphs:AIF,OVA,SADFace,ArgDown,BRAT, andKialo.
Given an input file, the library can automatically determine the correct format and convert it to a representation in thearguebufformat.
One can either pass a string pointing to the file or apathlib.Pathobject.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 aglob patternfor selecting the argument graphs.
This also enables to recursively load all argument graphs from a common parent directory.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 customnlpfunction to these loader methods.
This also makes it really easy to integrate the popularspacylibrarywitharguebufas all texts of atom nodes are automatically converted to a spacyDoc.importspacynlp=spacy.load("en_core_web_lg")graph=ag.load.file("graph.json",nlp=nlp)Programmatically Create a New GraphInstead 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.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=claimgv_graph=ag.dump.graphviz(graph)ag.render.graphviz(gv_graph,"./assets/programmatic.png")With this code, we get the following outputExporting Argument GraphsWe 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# Export to graphviz DOT formatdot=ag.dump.graphviz(graph)# Export an image of this dot source to a fileag.render.graphviz(dot,"./graph.pdf")# Convert to NetworkX graphnx=ag.dump.networkx(graph)# Save the graph as Arguebufag.dump.file(graph,"./graph.json")# Save the graph as AIFag.dump.file(graph,"./graph.json",ag.GraphFormat.AIF)DevelopmentTo pull the testing data, make sure to installDVCand rundvc pullin the root directory of the repository.