# Creating statement and argument nodes

This section describes how the Argdown parser decides which statements and arguments are represented as nodes in the generated argument map and how you can change this behaviour.

In general, all arguments with at least one relation are added as nodes to the argument map. But you can also be more selective. For example, you might want to create a map with arguments from a certain section or with a certain tag.

The default rules that decide which statements will get their own node are more complicated. The Argdown parser tries to keep the number of statement nodes as low as possible to support visualizing complex debates with many arguments in comparartively compact maps. For example, this allows you to "hide" unimportant premises in your arguments and only introduce the premises you really care about as nodes in your map.

Choose your own style

In this respect Argdown distinguishes itself from many argument mapping tools that represent arguments only as "inference nodes" that link different premises together. Such tools force you to represent every statement and inferential step as a node in your map. This becomes quickly overwhelming and unmanagable in complex debates (at least if you reconstruct every argument's premise-conclusion-structure in detail).

In contrast, Argdown lets you choose what you want to emphasize in your map. You can even choose to only add the central thesis of the debate to your map and otherwise only visualize arguments (that may contain many inferential steps). This is a good choice for complex debates.

On the other hand, for small debates or single arguments, you might prefer the "oldschool" style of argument mapping that represents each statement and inferential step as its own node in the map. In that case just follow these step and you are good to go.

The selection process is divided up into two phases:

Preselection round: In the preselection round, statements and arguments are excluded based on selected sections, tags, titles or flags.

Selection round: In the selection round, it is checked in which relations these preselected elements stand to other preselected elements. This is the round in which the excludeDisconnected setting and the statementSelectionMode are applied. It is also the round in which you can choose to include "extra" statements from the preselection with the includeStatements setting or the isInMap:true flag.

Let us start with the latter, as this is the round that is excluding arguments and statements by default, even if you do not change any settings.

In contrast, the preselection round will only exclude statements or arguments, if you explicitely tell it to do so by using the selection settings or the isInMap data flag.

# The excludeDisconnected selection setting

By default only statements and arguments are represented by nodes in the argument map that are considered to be connected to another node in the map. A statement counts as connected, if its equivalence class is.

Connected elements

An equivalence class is considered to be connected if at least one of the following conditions applies:

  • It is used in a preselected argument's premise-conclusion-structure as premise or conclusion.
  • It has at least one relation to a preselected element.

An argument is considered to be connected if at least one of the following conditions applies:

  • The argument itself is directly related to another preselected element.
  • A premise is supported/attacked by another preselected element.
  • The main conclusion is supporting/attacking another preselected element.
  • An inference is undercut by a preselected element.
  • Support by equivalence: a premise is equivalent with a main conclusion or the main conclusion is equivalent with a premise of another preselected argument.

The exclusion of disconnected statements from the map allows you to comment on your reconstruction by adding meta-statements in the Argdown text without 'polluting' your argument map with them. If you want to disable this feature you can use the excludeDisconnected: false selection setting:

===
title: Including disconnected nodes
selection:
    excludeDisconnected: false
===

<a>: I am currently in no relation.

<b>: It's complicated.

<c>: I feel disconnected.
Argument Map n0 a I am currently in no relation. n1 b It's complicated. n2 c I feel disconnected.
Including disconnected nodes

Click on the map button in the top right to see these three sad arguments appearing in the map.

# Choosing a statementSelectionMode

The Argdown parser supports several different general methods to exlude equivalence classes from the selection. You can change the method used by choosing a statementSelectionMode in the selection settings. This section describes the different modes currently supported.

Managing complexity in your map

In contrast to arguments, not all preselected and connected equivalence classes will appear as statement nodes in the map. While you can easily change this behaviour, it is quite important to keep the number of statement nodes in your map as low as possible.

If you include all statements of a a complex debate as nodes in your map, it will become overcrowded and readers will have difficulty to stay orientated. Choosing which statements you visualize as nodes in your map is a crucial method of managing complexity.

In three special cases, any of the modes described further below will not exclude equivalence classes:

Equivalence classes that will be selected as nodes by all modes

  1. The isInMap data flag is set to true.
  2. The statement title is included in the includeStatements selection setting.
  3. The equivalence class - has relations - and is not used in any preselected argument as premise or conclusion.

The third case may need an explanation: Relations of such equivalence classes can not be represented by edges of argument nodes, so it is important to represent them with statement nodes or they will be lost. In most cases you will want to include them in your map.

If you still want to exclude such equivalence classes you have to use the excludeStatements selection setting or set its isInMap data flag to false.

Now let's take a look at what the different modes are doing:

# all mode

Includes each equivalence class that is connected to a preselected element (argument or statement).

===
selection:
    statementSelectionMode: all
===

<a>

(1) [title]: I am selected
(2) I am selected
----
(3) I am selected
    -> I am selected
        + <b>

<a>
    - I am selected

[another title]: not very exciting, isn't it? // not selected
Argument Map n0 title I am selected n5 a n0->n5 n1 I am selected n1->n5 n2 I am selected n3 I am selected n2->n3 n4 I am selected n4->n5 n5->n2 n6 b n6->n3

# not-used-in-argument mode

Excludes any equivalence class that is used in an argument (as premise or conclusion).

===
selection:
    statementSelectionMode: not-used-in-argument
===

<a>

(1) [title]: I am not selected
(2) I am not selected
----
(3) I am not selected
    -> I am selected
        + <b>

<a>
    - I am selected

[another title]: I am not selected
Argument Map n0 I am selected n1 I am selected n2 a n1->n2 n2->n0 n3 b n3->n0

# with-title mode (default mode)

Excludes any equivalence class that is anonymous (has no title).

===
selection:
    statementSelectionMode: with-title
===

<a>

(1) [title]: I am selected
(2) I am not selected
----
(3) I am not selected
    -> I am selected

<a>
    - I am selected
        + <b>

[another title]: slightly more interesting. // still not selected
Argument Map n0 title I am selected n3 a n0->n3 n1 I am selected n2 I am selected n2->n3 n3->n1 n4 b n4->n2

# with-relations mode

Excludes any equivalence class that has no relations.

===
selection:
    statementSelectionMode: with-relations
===

<a>

(1) [title]: I am not selected
(2) I am selected
    -> <b>
----
(3) I am selected
    -> I am selected

<a>
    - I am selected
        + <b>

[another title]: still not selected
Argument Map n0 I am selected n4 a n0->n4 n5 b n0->n5 n1 I am selected n2 I am selected n1->n2 n3 I am selected n3->n4 n4->n1 n5->n3

# with-more-than-one-relation mode

Excludes any equivalence class that has less than two relations.

===
selection:
    statementSelectionMode: with-more-than-one-relation
===

<a>

(1) [title]: I am not selected
(2) I am not selected
    -> <b>
----
(3) I am not selected
    -> I am selected

<a>
    - I am selected
        + <b>

[another title]: still not selected
Argument Map n0 I am selected n1 I am selected n2 a n1->n2 n2->n0 n3 b n3->n1

# top-level mode

Excludes any equivalence class that is not used as top-level block element. See the introduction of the syntax documentation for the definition of a top-level block element.

===
selection:
    statementSelectionMode: top-level
===

<a>

(1) [title]
(2) I am not selected
----
(3) I am not selected
    -> I am selected

<a>
    - I am selected
        + <b>

[title]: I am selected.

[another title]: still not selected
Argument Map n0 title I am selected. n3 a n0->n3 n1 I am selected n2 I am selected n2->n3 n3->n1 n4 b n4->n2

# Selecting nodes by tag

You can use the selectedTags selection setting to preselect only those arguments and statements for further selection which are tagged with any of the chosen hashtags.

===
title: >
    Preselecting only statements and arguments with the #core tag.
selection:
    selectedTags:
        - core
===

[t1] #core
    + <a> #core
        - <b>
    - <c> #core
        - <d>
            + <e>

<f>
    + [t1]
Argument Map n0 t1 n1 a n1->n0 n2 c n2->n0
Preselecting only statements and arguments with the #core tag.

Only t1, a and c are selected. You can choose to also include statements or arguments without any tags by using the selectElementsWithoutTag:

===
title: >
    Preselecting only statements and arguments without tag or with the #pro tag.
selection:
    selectedTags:
        - pro
    selectElementsWithoutTag: true
===

[t1] #core #pro
    + <a> #pro #core
        - <b> #con
    - <c> #core
        - <d> #con
            + <e> #pro

<f>
    + [t1]
Argument Map n0 t1 n2 f n0->n2 n1 a n1->n0
Preselecting only statements and arguments without tag or with the #pro tag.

Now argument f is included in the map, even though it is not tagged as well. You may have noticed that not all arguments with the #pro tag were selected. Argument e is missing from the map.

The reason is once again that disconnected nodes are excluded from the map. Argument e's only connection is to d, but d is neither tagged with the #pro tag nor is it without any tags (it is tagged with the #con tag). As a result, it is excluded from the map. This leaves e disconnected. So it is excluded as well.

# Selecting nodes by section

You can use the selectedSections selection setting to preselect only those arguments and statements for further selection, that are members of chosen sections. See the section on creating groups to learn more about sections.

===
title: >
    Preselecting only statements and arguments within the section H1
selection:
    selectedSections:
        - H1
===

[t1]: text
    + <a>
    - <b>

# H1

<a>: argument description
    + <c>: argument description
    - <d>: argument description

# H2

<b>: argument description
    + <e>: argument description
    - <f>: argument description
Argument Map cluster_1 H1 n0 a argument description n1 c argument description n1->n0 n2 d argument description n2->n0
Preselecting only statements and arguments within the section H1

You can choose to also include statements or arguments without any section by using the selectElementsWithoutSection:

===
title: >
    Preselecting only statements and arguments within the section H1 or without any section
selection:
    selectedSections:
        - H1
    selectElementsWithoutSection: true
===

[t1]: text
    + <a>
    - <b>

# H1

<a>: argument description
    + <c>: argument description
    - <d>: argument description

# H2

<b>: argument description
    + <e>: argument description
    - <f>: argument description
Argument Map cluster_1 H1 n1 a argument description n0 t1 text n1->n0 n2 c argument description n2->n1 n3 d argument description n3->n1
Preselecting only statements and arguments within the section H1 or without any section

Note, that argument b is excluded, even though it is used outside of any section. This is because b is defined first in section H2 and sections are by default assigned by their first definition. For more about how sections are assigned see creating groups.

# Selecting nodes by title

You can use the includeStatements, excludeStatements and excludeArguments selection settings to include or exclude elements by title.

===
title: Including and excluding elements by title
selection:
    includeStatements:
        - t1
        - t2
    excludeStatements:
        - t3
    excludeArguments:
        - b
        - c
===

<a>

(1) [t1]: s1
(2) [t2]: s2
----
(3) [t3]: s3

[t3]: s3
    - <b>

<a>
    - <c>
    + <d>
Argument Map n0 t1 s1 n2 a n0->n2 n1 t2 s2 n1->n2 n3 d n3->n2
Including and excluding elements by title

Note that argument b, which would normally appear in the map together with t3, is now also excluded, because its only connection was to t3. Because t3 is excluded b is now disconnected and falls victim to the excludeDisconnected default policy.

Why is there not also an includeArguments setting? It is not needed because by default all connected arguments are added as nodes to the map. In contrast, only connected statements selected by the statementSelectionMode are added by default to the map. The includeStatements setting includes additional statements to the map that were not added by the statementSelectionMode.

# Selecting nodes with the isInMap data flag

You can also pick single arguments or statements for the map by using the isInMap data flag directly in the Argdown code:

<a>

(1) s1 {isInMap: true}
(2) s2
----
(3) s3 {isInMap: true}

<b> {isInMap: false}
    - <a>
Argument Map n0 s1 n2 a n0->n2 n1 s3 n2->n1
Using the isInMap flag to select or deselect single elements.

The downside of this method is that you add map-specific data to elements in your Argdown document, thereby making it more difficult for others to change the selection and to generate a different map from the same document. This "tight coupling" of data and visualization is not recommended. If you want to pick single elements you should use the includeStatements, excludeStatements and excludeArguments selection settings instead. See the previous section for further details.

If you still prefer to use the isInMap data flag or if you want to override the flags of other authors, you can use the ignoreIsInMap selection setting. If set to true, all isInMap data flags in your document will be ignored:

===
title: Ignoring isInMap flags
selection:
    ignoreIsInMap: true
    statementSelectionMode: not-used-in-argument
===

<a>

(1) s1 {isInMap: true}
(2) s2
----
(3) s3 {isInMap: true}

<b> {isInMap: false}
    - <a>
Argument Map n0 a n1 b n0->n1
Ignoring isInMap flags

# Creating argument nodes for each inferential step

Using the explodeArguments option you can automatically create several argument nodes from a singular complex argument. Your premise-conclusion-structures will be divided up into separate inferential steps (containing only one inference and conclusion). Each step will be put into its own argument so that each inferential step is represented as an argument node in the map. The arguments will be renamed, appending the step number to their name.

Here is an example:

===
model:
    explodeArguments: true
selection:
    statementSelectionMode: with-relations
===

<my complex argument>

(1) first premise
    - <a2> #con
(2) second premise
----
(3) intermediary conclusion
    - <a3> #con
(4) fourth premise
----
(5) main conclusion
    - <a5> #con
Argument Map n0 first premise n6 my complex argument - 1 n0->n6 n1 intermediary conclusion n7 my complex argument - 2 n1->n7 n2 main conclusion n3 a2 n3->n0 n4 a3 n4->n1 n5 a5 n5->n2 n6->n1 n7->n2

Note how in this case attacks against the intermediary conclusion can be visualized, because it was automatically added as a statement to the map (using the statementSelectionMode with-relations).

# Defining which statements are used in an inferential step

In complex arguments an inferential step sometimes does use statements for its inference that were already listed as premise in another inferential step. In other cases a conclusion of another inferential step is used that is not the directly preceding step.

In both of these cases you have to tell Argdown explicitely which statements were used in the inferential step. You can do so by adding a metadata list to the conclusion or the inference:

===
model:
    explodeArguments: true
selection:
    statementSelectionMode: all
dot:
    vizJsSettings:
        rankDir: TB
===

<my complex argument>

(1) first premise
(2) second premise
----
(3) first intermediary conclusion
(4) third premise
--
{uses: [1,4]}
--
(5) second intermediary conclusion
----
(6) main conclusion {uses: [3,5]}
Argument Map n0 first premise n6 my complex argument - 1 n0->n6 n7 my complex argument - 2 n0->n7 n1 second premise n1->n6 n2 first intermediary conclusion n8 my complex argument - 3 n2->n8 n3 third premise n3->n7 n4 second intermediary conclusion n4->n8 n5 main conclusion n6->n2 n7->n4 n8->n5

The perfect configuration for your inference trees

Jump over to the section on how to create oldschool argument maps and inference trees for even more configuration tips on how to visualize the inferential structure of complex arguments.