Template:Cladex/doc

From blackwiki
< Template:Cladex
Revision as of 04:38, 9 November 2011 by imported>Anomie (Replace link to https://secure.wikimedia.org/wikipedia/meta with link to //meta.wikimedia.org)
Jump to navigation Jump to search

This template is an eXtended version of {{Clade}}, hence the name. Both templates are for drawing branching trees with the node and base labels being clickable links. Such diagrams are especially suited to represent evolutionary trees (cladograms).

Most of the documentation is the same as the parent template, {{Clade}}, and is included below for convenience. Unless the two extra features of {{Cladex}} are needed, you are advised to use {{Clade}}.

The two extra features of {{Cladex}} are:

  • Double lines leading to a node can be produced as easily as dotted lines.
  • Brackets or bars of a chosen colour can be placed to the right of a set of leaf nodes in the cladogram, thus allowing paraphyletic groups to be identified. See #Bracketting nodes. Text labels for these brackets/bars can be provided using {{Barlabel}}.

{{Clade}} and {{Cladex}} can be freely mixed, so if only some clades require the extra features, only these need be specified using {{Cladex}}.

Basic features

Use {{Clade}} unless the extra features of {tl|Cladex}} are needed.

Usage


{{clade
|label1=Base
|1=Node
}}

produces

Base

Node


{{clade
|1={{clade
   |label1=[[Subtree1]]
   |1=Leaf1
   |label2=Subtree2
   |2=[[Leaf2]]
   }}
}}

produces

Subtree1 

Leaf1

Subtree2 

Leaf2


{{clade| style=font-size:75%;line-height:75%
|1={{clade
   |label1=Subtree1
   |1=Leaf1
   |label2=Subtree2
   |2=Leaf2
   }}
}}

produces

Subtree1

Leaf1

Subtree2

Leaf2

Note that the order of the parameters does not matter. Exactly the same output is produced by


{{clade| style=font-size:75%;line-height:75%
|1={{clade
   |2=Leaf2
   |1=Leaf1
   |label1=Subtree1
   |label2=Subtree2
   }}
}}
Subtree1

Leaf1

Subtree2

Leaf2


{{clade
|1={{clade
   |1={{clade | thickness=3
      |1=Leaf1
      |2=Leaf2
      }}
   |2=Leaf3
   }}
}}

produces

Leaf1

Leaf2

Leaf3

To replace a solid line leading to the Nth child with a dashed line, use |stateN=dashed.


{{clade
|1={{clade
   |1={{clade
      |1=Leaf1|state1=dashed
      |2=Leaf2
      }}
   |2=Leaf3
   }}
}}

produces

Leaf1

Leaf2

Leaf3

{{Cladex}} only. To replace a single line leading to the Nth child by a double line, use |stateN=double. Notice that {{Cladex}} has only been used for the (sub)clade where the double line is wanted. The outermost clade should always be specified with {{Clade}} unless its style is altered – see below.


{{clade
|1={{clade
   |1={{cladex
      |1=Leaf1
      |2=Leaf2|state2=double
      }}
   |2=Leaf3
   }}
}}

produces

Leaf1

Leaf2

Leaf3

Tips

An easy way of creating larger cladograms is to use the Newick format and proceed to edit it using a suitable text editor to produce the markup.

  1. Start with Newick format ((a,b),(c,d))
  2. Replace "(" with "{{clade|"
  3. Replace ")" with "}}"
  4. Edit to replace commas with pipes and numbers
  5. Edit clade labels if needed

{{clade
 |1={{clade
    |1=a
    |2=b
    }}
 |2={{clade
    |1=c
    |2=d
    }}
}}

Example Perl script to automate the conversion:

use constant N=>"\n";
use constant T=>"\t";

my $tree='((a,b),(c,d));'; # get sequence
$tree=~s/[\n\r]//g; # loose those spaces
$tree=~ s/\:[\.\d]+//g; # loose those lengths
while ($tree=~ m/\(/) {
	foreach my $clade ($tree=~ m/\(([^\(\)]+)\)/g) {
		my @branches=split /\,/,$clade;
		s/(\t+)/$1\t/g for @branches;
		die 'ERROR: degenerate/empty node!'.N if $#branches<1;
		$tree=~ s/\(\Q$clade\E\)/${\join('','{{clade',N,map(T.'|'.($_+1).'='.$branches[$_].N,0..$#branches),T.'}}')}/; # substitute
	}
	pos($tree)=0;
}
$tree=~s/(\t*)\t\}\}/$1\}\}/g; # lazy fix

print $tree;

Using a box

You can nest the templates and use links around the text. You may use non-breaking spaces (&nbsp;) to obtain spaces or to have labels that have spaces.

The entire cladogram can be placed in a box so that text flows nicely around it. You can use Template:Tl:Cladogram to produce the box.

Example
Neornithes  
Paleognathae

 

 Neognathae 
 

Other birds

Galloanserae 

Anseriformes

    

Galliformes

Craciformes

Sample of Template:Tl:Cladogram
{{cladogram|title=Example
|caption=Sample of {{tl:Cladogram}}
|clades={{clade| style=font-size:75%;line-height:75%
|label1=[[Neornithes]]  
|1={{clade
	|label1=[[Paleognathae]]
	|1= 
	|label2= [[Neognathae]] 
	|2={{clade
	   |1=Other birds
	   |label1= 
	   |label2=[[Galloanserae]] 
	   |2={{clade
	       |1=[[Anseriformes]]
		   |label2=    
		   |2={{clade
		      |1=[[Galliformes]]
		      |2=[[Craciformes]]
		      }}
	      }}
	   }}
       }}
  }}
}}

Controlling the layout of sisters

When one sister is represented as a leaf node and the other as a labelled subclade, they do not appear to be at the same level. Consider this cladogram:

Banksia subser. Sphaerocarpae (5 taxa)

Banksia subser. Leptophyllae

Banksia telmatiaea

(4 other taxa)

Although Banksia subser. Sphaerocarpae and Banksia subser. Leptophyllae are sisters, their names are not aligned in the cladogram. If this is considered undesirable, one solution is to use a label in both cases, as shown below, which now shows the sisters at the same level.

Banksia subser. Sphaerocarpae

(5 taxa)

Banksia subser. Leptophyllae

Banksia telmatiaea

(4 other taxa)

Another 'trick' is to introduce a dummy clade. The dotted line below shows where an extra clade has been inserted:

Banksia subser. Sphaerocarpae

Banksia subser. Leptophyllae

Banksia telmatiaea

(4 other taxa)

To achieve this, instead of

{{clade
|1=Sister1
|label2=Sister2
|2={{clade
   ...
   }}
}}

use

{{clade
|1=Sister1
|2={{clade
   |label1=Sister2
   |2={{clade
       ...
      }}
   }}
}}

Bracketting nodes

{{Cladex}} only. To insert a coloured 'bracket' around a set of leaf nodes which follow one another in the generated cladogram:

  • Add barbeginN=colour for the first leaf node, where N is the order of that leaf node within its clade, and colour is the required colour.
  • Add barN=colour for the remaining nodes other than the last (note that N must be the order of that node within its clade).
  • Add barendN=colour for the last node.

Either the outermost clade must be specified by {{Clade}} or if {{Cladex}} is needed there, |style=width:auto must be present.


{{clade|style=font-size:85%;line-height:100%
|1={{cladex
   |1=Leaf A
   |2=Leaf B|barbegin2=green
   |3=Leaf C|bar3=green
   |4={{cladex
      |1=Leaf D|barend1=green
      |2=Leaf E
      |3=Leaf F|barbegin3=purple  
      |4={{cladex
         |1=Leaf G|bar1=purple
         |2=Leaf H|barend2=purple
         }}
      }}
   }}
}}

produces

Leaf A

Leaf B

Leaf C

Leaf D

Leaf E

Leaf F

Leaf G

Leaf H

The horizontal lines can be omitted by using |barN=colour throughout. Thus the following (note the use of |style=width:auto since the outermost clade uses the extra features of {{Cladex}}):


{{cladex|style=width:auto;font-size:85%;line-height:100%
|1=Leaf A
|2={{cladex
   |1=Leaf B|bar1=midnightblue
   |2=Leaf C|bar2=midnightblue
   }}
|3=Leaf D|bar3=midnightblue 
}}

produces

Leaf A

Leaf B

Leaf C

Leaf D

Note that brackets or bars must only be applied to leaf nodes. In the example above, it may be tempting to write


{{cladex|style=width:auto;font-size:85%;line-height:100%
|1=Leaf A
|bar2=midnightblue
|2={{cladex
   |1=Leaf B
   |2=Leaf C
   }}
|3=Leaf D|bar3=midnightblue
}}

with the expectation that the bar will be to the right of the whole of the clade containing Leaf B and Leaf C. This does not produce the required output.

Specifying colours

You can use any of the ways in which colours can be specified in HTML; e.g. the standard colour names, the three or six hex digit notations, such as #FC3 or #F3C630, or the rgb() notation.

Supplying text labels

Text labels for each bracket/bar can be added using {{Barlabel}}. Accessibility guidelines require pages not to rely on colour alone, so it's particularly important to add labels if you have more than one bracket/bar and need to refer to them separately.

Debugging

If your cladogram doesn't display brackets/bars as you expected, check that:

  • You understand the numbering system for the parameters barN, etc. The N must be the same as the number of the child within its clade. Thus typically you should write |N=label for leaf|barN=colour for bar, e.g. |2=[[Passeridae]]|bar2=midnightblue.
  • You have only attempted to apply brackets/bars to leaf nodes.
  • Either the outermost clade uses {{Clade}} or if it has to use {{Cladex}}, then |style=width:auto is present.

Limitations

Label length

Labels produced by |labelN=, where N is 1, 2, ..., can lead to poor layout of the resulting cladogram. (This does not apply to the text of leaves, i.e. text produced by |N=.) To avoid problems:

  • labels should be kept as short as possible, ideally a single word
  • any necessary spaces in labels should be represented as &nbsp; not as actual spaces
  • line breaks (i.e. <br>) should not be used.

Browser differences

Clade template browser differences.jpg

{{Clade}} and {{Cladex}} work by producing hidden tables. The horizontal and vertical lines making up the tree are actually the edges of table cells. The tables are then drawn by the browser or user agent using its internal algorithms. As these differ from browser to browser, the trees produced will not look the same on all browsers.

In particular, as of July 2011 there are two algorithms for laying out tables with empty cells, used by two groups of browsers. Safari, Chrome and Opera use one algorithm, producing cladograms like that on the left in the diagram. Internet Explorer and Firefox use another algorithm, producing cladograms like that on the right in the diagram.

No automated "fix" for these differences exists at present.

Position of brackets/bars

The bracket/bar drawing part of {{Cladex}} is probably close to the limits of what can be done using table-drawing algorithms to produce cladograms. The vertical bar is always drawn at the very right-hand edge of the hidden outermost table, which is often not how it would be drawn manually. As of 21 June 2011, there is no known way round this.

Large cladograms

{{Clade}} and {{Cladex}} have some size limitations.

  • They currently allow only a maximum of 17 children per node. It may seem that this could easily be increased by editing the templates, but see the next point.
  • They will only expand a cladogram up to a certain level of complexity because the MediaWiki software limits the resources available for template expansion. The cladogram at APG_III_system#Phylogeny has had to be broken into two parts, because {{Clade}} will not handle the entire cladogram; it runs out of the allowed resources. Any change to the template could result in large cladograms failing to display correctly.

Inclusion in books

There are many known bugs in rendering tables in the software which produces Wikipedia books; see the book tool feedback page. As of July 2011 these result in the lines in cladograms not displaying in books.