~stk-developers/supertree-toolkit/releases : revision 11

1

The STK Graphical User Interface

2

=================================

3

4

The Graphical User Interface (GUI) is used to perform all of the STKs primary

4

The Graphical User Interface (GUI) is used to perform all of the STK's primary

5

functionality. It allows you to enter data, visualise data and process data all

6

within a single interface.

7

13

14

.. code-block:: bash

15

16

stk-gui [filename]

16

stk-gui [file]

17

18

The GUI looks like this.

19

25

:figclass: align-center

26

27

The STK GUI with no data loaded. The GUI consists of two vertical panels

28

where data is edited (left) and entered (right).

28

where data are edited (left) and entered (right).

29

30

The GUI consists of two main halves (Fig. :num:`#img-stk-gui`). The left-hand

31

side is a tree-structure that allows you to navigate the data (tree panel). The

32

data is structured into a project, which in turn contains sources, which in turn

32

data are structured into a project, which in turn contains sources, which in turn

33

contain trees and meta data. The right-hand side (data panel) contains three

34

sub-panels. Each of these divisions is called an element (Fig.

35

:num:`#img-stk-gui-lab`). The top gives user context-sensitive documentation on

35

:num:`#img-stk-gui-lab`). The top gives context-sensitive documentation on

36

the current selection in the left-hand side. The middle is where you add data.

37

Depending on what part of the data you are editing, the middle panel will change

38

to suit the data to be edited/input. The lowermost sub-panel is where you can

51

To navigate the left hand side, click the small arrows on the left. These will

52

open and close sub-data within the hierarchy. On the right-hand side of the tree,

53

there are small "+" and "-" signs to allow you add or remove data. Where the

54

data is a choice, a dropdown list is activated on the right hand side.

54

data are a choice, a dropdown list is activated on the right hand side.

55

56

The colour in the left-hand side tree informs you if there is missing data. Blue

57

lines show you are missing required data. The blue then progresses upwards from

70

* Help

71

72

Of these, the File and STK Functions are most often used. More on these will be

73

covered later, but briefly the File menu contains command to open and save data,

74

plus import and export. The STK Functions menu contains all the STK-only

73

covered later, but briefly the File menu contains commands to open and save data,

74

plus import and export data. The STK Functions menu contains all the STK-only

75

functionality.

76

77

The right click menu allows you to copy and paste elements (e.g. you can copy

78

and past a source from the same or another file) and change how the data is

78

and past a source from the same or another file) and change how the data are

79

visualised. These are covered later.

80

81

Entering data

82

-------------

83

84

The best way of starting a new dataset is to import bibliographic file. The STK

85

uses `bibtex format <http://www.bibtex.org/>`_, which is a common format and all

84

The best way to start a new dataset is to import a bibliographic file. The STK

85

uses `bibtex format <http://www.bibtex.org/>`_, which is a common format and that all

86

decent reference managers can output, as can most journal websites. We recommend

87

using `JabRef <http://jabref.sourceforge.net/>`_, which is free, open source and

88

available on most OS. We have tested the STK extensively with output from

125

Once done, your tree string will appear in the data panel.

126

127

.. warning:: Avoid non-standard characters in taxa names. Your names *must* not contain commas,

128

parantheses, colons, asterisks, hyphens, slashes or percentage signs (percentage signs are allowed for polyphyletic taxa - see later).

128

parentheses, colons, asterisks, hyphens, slashes or percentage signs (percentage signs are allowed for non-monophyletic taxa - see later).

129

These are not allowed in taxa names in Newick format as they mean other things.

130

131

.. note:: Quoted taxa should be done with single quotes only ('), not double or "smart

134

Using the interface

135

-------------------

136

137

There are a number of useful functionality in the STK to aid in data entering

138

and exploration. They are slicing and grouping data, and copy and pasting

139

elements.

137

There are a number of useful functions in the STK GUI to aid in data entering

138

and exploration. They are slicing data, grouping data, and copy and pasting

139

data sections.

140

141

.. index:: grouping

142

189

Functions->Data Summary. Activating this brings up a window containing the

190

number of trees in the dataset, the taxa list, character list, and years (Fig.

191

:num:`#img-stk-data-summary`). The output can be saved or copy and pasted as

192

required. This can be used to **carefully** check the taxa list for example for

193

user errors.

194

195

.. note:: Incomplete data (with blue elements) may not produce a data summary

196

197

.. note:: See the tutorial for more information on how taxonomy should be dealt with

192

required. This can be used to **carefully** check the taxa list for

193

user errors, for example

194

195

.. note:: Incomplete data (with blue elements) may not produce a data summary.

196

197

.. note:: See the tutorial for more information on how nomenclature and taxonomy should be standardised.

198

199

.. _img-stk-data-summary:

200

251

252

In order to construct a supertree the source trees must have sufficient

253

taxonomic overlap; that is at least two taxa in a source tree must occur in at

254

least one other tree. The STK allows you to both check and visualise this.

254

least one other tree. The STK allows you to both check and visualise this overlap.

255

256

The interface (Fig. :num:`#img-stk-data-overlap-gui`) contains options to select

257

the level of overlap (default is 2), which is the number of taxa trees should

279

:figclass: align-center

280

281

Normal graphical view of data overlap. For a correctly connected dataset

282

there should be a single node (circle). These data is not sufficiently well

282

there should be a single node (circle). These data are not sufficiently well

283

connected.

284

285

.. _img-stk-data-overlap-detailed:

291

:figclass: align-center

292

293

Detailed graphical view of data overlap. For a correctly connected dataset

294

there should be no red nodes (circles) in the graph. These data is not sufficiently well

294

there should be no red nodes (circles) in the graph. These data are not sufficiently well

295

connected.

296

297

299

********

300

301

Taxa substitutions and deletions are a key part of ensuring a standardised

302

taxonomy for supertree analysis. However, it is usually quite cumbersome to

302

nomenclature and taxonomy for supertree analysis. However, it is usually quite cumbersome to

303

carry out this operation on a number of tree or matrix files. The STK will

304

ensure that taxa substitutions are consistent across the whole dataset and any

305

taxonomic information is also updated. You can construct taxa deletions and

306

substitutions using the *Sub taxa* interface (Fig. :num:`#img-stk-sub-taxa`).

307

Move taxa from the dataset to the right-hand side and add the replacements or

308

leave blank for a deletion. The substitutions created can be saved to a *subs

309

file*. A subs file can also be imported, either as a substitusion (or subs) file

309

file*. A subs file can also be imported, either as a substitution (or subs) file

310

or as a CSV file.

311

312

.. _img-stk-sub-taxa:

330

Enantiornithes = Avisaurus archibaldi,Avisaurus gloriae

331

332

The above file deletes MRPoutgroup and replaces Dinornithidae and Enantiornithes

333

with polytomys of the taxa listed. Deletions cause collapsing of nodes where the

333

with polytomies of the taxa listed. Deletions cause collapsing of nodes where the

334

deletion occurred.

335

336

.. note:: There *must* be a space either side of the = symbol.

339

the old taxon name. For example to replace A_a with A_f in the tree:

340

341

.. code-block:: none

342

343

(A_a%1, A_b%1, (A_a%2, A_b%2, A_c, A_d));

343

344

345

the subs file should contain:

345

346

347

.. code-block:: none

348

347

349

A_a = A_f

348

350

349

351

Permute all trees

350

352

*****************

351

353

352

When recording trees from the literature inclusions of sub-species can be done

354

When recording trees from the literature inclusions of non-monophyletic can be done

353

355

using a special encoding of the taxa. Placing a '%' symbol at the end of a taxon

354

356

name, followed by a number allows the STK to identify these taxa.

355

357

356

To remove polyphyletic taxa and sub-species, the tree permutation function is

358

To remove non-monophyletic taxa, the tree permutation function is

357

359

used. This creates a number of trees per source tree, each with a different

358

combination of the paraphyletic taxa (which sub-species can be). Note that this

360

combination of the non-monophyletic taxa. Note that this

359

361

produces a tree file containing the unique trees only or a matrix for each

360

362

source tree in the dataset.

361

363

362

These trees or matrices can then be combined into a single tree using PAUP, TNT

364

These trees or matrices can then be combined into a single tree using PAUP*, TNT

363

365

or similar. The consensus of these trees then become the source tree for this

364

source.

366

source by importing back into the GUI.

365

367

366

368

Replace genera

367

369

**************

368

370

369

Generic taxa can be replaced with a polytomy of all species that belong in that

371

Genus-level taxa can be replaced with a polytomy of all species that belong in that

370

372

genera and exist in the dataset. Replace genera automates this process. It can

371

either create a new Phyml file or a subs file. The latter can be imported into

373

either create a new Phyml file or a subs file; the latter can be imported into

372

374

the Sub taxa function.

373

375

374

376

STR

375

377

***

376

378

377

Safe Taxonomic Reduction identifies possible problem taxa in the dataset. These

379

Safe Taxonomic Reduction identifies possible problem taxa in the dataset, which

378

380

may cause instabilities in the supertree analysis. The output files from STR

379

381

are (Fig. :num:`#img-stk-str`):

380

382

* Subs files for deletion and replacement of appropriate taxa (optional)

384

386

385

387

.. note:: This can take a long time for even small datasets. For anything over 100 taxa use the command line interface.

386

388

387

For further details on STR see

388

389

.. todo:: Add references and citations

389

For further details on STR see `Wilkinson (1995) <http://sysbio.oxfordjournals.org/content/44/4/501.abstract>`_.

390

391

.. _img-stk-str:

392

396

:alt: STR interface

397

:figclass: align-center

398

399

STR interface. The file requested contains the equivalency matrix. The two

399

STR interface. The output file contains the equivalency matrix. The two

400

optional sub files will automatically allow deletion and reinsertion of taxa

401

where this is safe to do so.

402

444

*************

445

446

After all your processing, the final step is to create a matrix of your data.

447

This function will create a matrix suitable for reading into Paup, TNT and most

447

This function will create a matrix suitable for reading into PAUP**, TNT and most

448

other supertree software. Note that some software require a set of "input

449

trees". In this case, use the "Export trees" function under the the "File" menu.

450

Matrices can be output in Nexus or Hennig (TNT) format. Simply select "Create