# Creating group nodes

Headings define sections in the Argdown document. In the argument map, sections are represented as groups of arguments and statements (visualized as grey boxes). By default, the following rules decide to which group a statement or argument belongs:

How groups are assigned to statements and arguments

Statements: If a statement (equivalence class) is used in several sections in the Argdown document, it will appear in the group of the section where it was first defined. If no definition exists for this statement, it will appear in the group where it was first referred to.

Arguments: The same is true for arguments, except for recontructed arguments. In this case the argument belongs to the group of the section in which its premise-conclusion-structure (pcs) was defined.

Let us look at an example. In the following map, two headings were used to define two groups in the argument map. Click on the "Source" button to see how it was done.

# H1

[p]: text
    - <a> // only referred to, not defined
    + <b>: text // first definition of b

## H2

<a>: text // first definition of a

<b> // only referred to, not defined

// but reconstruction takes precedence over definition:
(1) text
(2) text
-----
(3) text
Argument Map cluster_1 H1 cluster_2 H2 n0 p text n1 a text n1->n0 n2 b text n2->n0
From headings to groups

Because H2 is a subsection of H1, its group is a child group of H1's group. Notice that argument a is first used in section H1, but is a member of H2's group because it was not defined in H1.

On the other hand, argument b is defined in H1, but it is reconstructed in H2 and reconstructions take precedence over definitions. So b is a member of H2's group.

# The groupDepth group setting

To understand how the groupDepth setting works, we need to first define the level of a group:

The group and section level

Let us call the number of ancestors a section or group has its "level", starting with level 1 for a section or group that is not a subsection or child group of another one of its kind. So a subsection has level 2, a subsubsection has level 3 and so on (you can simply count the number of # characters in a heading to get the level of a section).

Sometimes it is useful to use the lowest section levels of an Argdown document for structuring the text, while only using the higher levels to define groups in the argument map. You can achieve that by using the groupDepth parameter of the group settings. In general, if the following is true for a section, it will be ignored in the map:

Ignored sections

If the following is true, a section will not be turned into a group:

sectionLevel <= maxLevel - groupDepth

where maxLevel is the maximum section level in the document.

By default, the groupDepth is set to two, which means that it will only use the two highest levels of sections to define groups in the map. If we use three levels, the lowest level will be ignored in the map (1 <= 3 - 2). If we set the groupDepth parameter to 1 in the previous example, we get the following result:

===
group:
    groupDepth: 1
===

# H1 // level 1 will be ignored (1 <= 2 - 1)

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

## H2 // level 2 will not be ignored (2 > 2 - 1)

<a>: text

<b>

(1) text
(2) text
-----
(3) text
Argument Map cluster_1 H2 n1 a text n0 p text n1->n0 n2 b text n2->n0

# The isGroup data flag

Sometimes you might want to have even more control over which sections should be used as groups in the argument map.

In this case you can use the isGroup data flag to explicitely define which sections are defining groups.

===
group:
    groupDepth: 1
===

# H1

[p]: text

## H2 {isGroup: false}

[p]
    - <a>: text

## H3 {isGroup: true}

[p]
    + <b>: text
Argument Map cluster_1 H3 n2 b text n0 p text n2->n0 n1 a text n1->n0

# The isInGroup data flag

If you want to have more control over which statement or argument is in which group, you can use the isInGroup data flag.

The flag will put the statement or argument in the group of the current section, even if it is used with a statement or argument reference.

Note that it makes only sense to set the flag once to true. If you use it a second time in a second section, the first flag will be overriden.

The flag will also be ignored if the isGroup flag of the current section is set to false or if the current section is outside of the current groupDepth.

# H1

[p]: text
    - <a> {isInGroup: true} // only referred to, but with flag true
    + <b>: text {isInGroup: false} // first definition of b, but with flag false

## H2

<a>: text // first definition of a

<b> {isInGroup: true} // only referred to, but with flag true
Argument Map cluster_1 H1 cluster_2 H2 n0 p text n1 a text n1->n0 n2 b text n2->n0

# Regrouping

With the regroup group setting you can completely overwrite the groups derived from headings. By using this method in your config files, you can apply as many arbitrary groupings to the same Argdown document as you like.

===
group:
    regroup:  [{
            title: "New group 1",
            statements: ["q"],
            tags: ["tag-1", "tag-2"],
            children: [{
                title: "New group 2",
                arguments: ["a", "c"]
            },
            {
                title: "New group 3",
                arguments: ["b", "d"]
            }]
        }]
===

# H1

[p]: text

[q]: text
    +> <a>

## H2 {isGroup: false}

[p]
    - <a>: text
    - <b>: text

## H3 {isGroup: true}

[p]
    + <c>: text
    + <d>: text
Argument Map cluster_1 New group 1 cluster_3 New group 3 cluster_2 New group 2 n1 q text n2 a text n1->n2 n0 p text n2->n0 n4 c text n4->n0 n3 b text n3->n0 n5 d text n5->n0

# Closing Groups

A group can be closed to hide all its children. This is useful to reduce complexity in huge maps.

# Usage with Data Flag:

[s1]

<a4>
    -> <a2>

# A Closed Group  {isClosed: true}

[s1]
    - <a2> {isInGroup: true}
    + <a3>
Argument Map s1 A Closed Group n0 s1 s1->n0 s1->n0 n1 a4 n1->s1

# Usage in Group Configuration:

The new group.sections setting allows to define which sections are closed and which are not groups:

===
group:
    sections: {"A Closed Group": {isClosed: true}, "Just a Heading": {isGroup: false}}
===

# A Closed Group

<s1>: I am hidden.
    -> [s2]

# Just a Heading

[s2]: I am free!
Argument Map s1 A Closed Group n0 s2 I am free! s1->n0

This allows to use headings as groups without "polluting" the Argdown document with data flags.

# Usage in Regroup Configuration:

===
group:
    regroup: [{
            title: "first group",
            statements: ["s1"], arguments: ["a1"],
            children: [
                {
                    title: "some other group",
                    isClosed: true,
                    arguments: ["a2"]
                }
            ]
            }]
===


[s1]: I am a proud member of the first group
    - <a1>: I am a proud member of the first group
        - <a2>: The other group is much more exclusive!

<a3>: Who needs groups?
    -> [s1]
Argument Map cluster_1 first group n0 s1 I am a proud member of the first group n1 a1 I am a proud member of the first group n1->n0 s1 some other group s1->n1 n3 a3 Who needs groups? n3->n0

# Ignoring Group Data flags

Group data flags can be ignored by using group.ignoreIsGroup and group.ignoreIsClosed

===
group:
    ignoreIsClosed: true
===

[s1]

<a4>
    -> <a2>

# A Closed Group  {isClosed: true}

[s1]
    - <a2> {isInGroup: true}
    + <a3>
Argument Map n2 a2 n0 s1 n2->n0 n3 a3 n3->n0 n1 a4 n1->n2