~ubuntu-branches/ubuntu/trusty/boxshade/trusty : revision 2

1

<?xml version='1.0' encoding='ISO-8859-1'?>

2

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

3

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

4

5

<!--

6

7

Process this file with an XSLT processor: `xsltproc \

8

-''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\

9

manpages/docbook.xsl manpage.dbk'. A manual page

10

<package>.<section> will be generated. You may view the

11

manual page with: nroff -man <package>.<section> | less'. A

12

typical entry in a Makefile or Makefile.am is:

13

14

DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\

15

manpages/docbook.xsl

16

XP=xsltproc -''-nonet

17

18

manpage.1: manpage.dbk

19

$(XP) $(DB2MAN) $<

20

21

The xsltproc binary is found in the xsltproc package. The

22

XSL files are in docbook-xsl. Please remember that if you

23

create the nroff version in one of the debian/rules file

24

targets (such as build), you will need to include xsltproc

25

and docbook-xsl in your Build-Depends control field.

26

27

-->

28

29

30

<!ENTITY dhfirstname "<firstname>Steffen</firstname>">

31

<!ENTITY dhsurname "<surname>M�ller</surname>">

32

33

<!ENTITY dhdate "<date>February 26, 2004</date>">

34

<!-- SECTION should be 1-8, maybe w/ subsection other parameters are

35

allowed: see man(7), man(1). -->

36

<!ENTITY dhsection "<manvolnum>1</manvolnum>">

37

<!ENTITY dhemail "<email>moeller@pzr.uni-rostock.de</email>">

38

<!ENTITY dhusername "Steffen Moeller">

39

<!ENTITY dhucpackage "<refentrytitle>BOXSHADE</refentrytitle>">

40

<!ENTITY dhpackage "boxshade">

41

42

<!ENTITY debian "<productname>Debian</productname>">

43

<!ENTITY gnu "<acronym>GNU</acronym>">

44

<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">

45

]>

46

47

48

49

50

&dhemail;

51

</address>

52

53

&dhfirstname;

54

&dhsurname;

55

</author>

56

57

58

<holder>&dhusername;</holder>

59

</copyright>

60

&dhdate;

61

</refentryinfo>

62

63

&dhucpackage;

64

65

&dhsection;

66

</refmeta>

67

68

<refname>&dhpackage;</refname>

69

70

<refpurpose>Pretty-printing of multiple sequence alignments</refpurpose>

71

</refnamediv>

72

73

74

<command>&dhpackage;</command>

75

</cmdsynopsis>

76

</refsynopsisdiv>

77

78

<title>DESCRIPTION</title>

79

<para><command>BOXSHADE</command> is a program for pretty-printing multiple alignment output. The program itself doesn't do any alignment, you have to use a multiple alignment program like ClustalW or Pileup and use the output of these programs as input for BOXSHADE.</para>

80

81

<para>This manual page was written for the &debian; distribution

82

because the original program does not have a manual page. The presented information comes from the documentation of the Web Service of the 3.21 version that is not available as a Debian package.

83

</para>

84

85

<para>

86

BOXSHADE is a program for creating good looking printouts from

87

multiple-aligned protein or DNA sequences. The program does no alignment

88

by itself, it has to take as input a file preprocessed by a multiple

89

alignment program or a multiple file editor. See below for a list of

90

supported input formats and output devices. In the standard BOXSHADE

91

output, identical and similar residues in the multiple-alignment chart

92

are represented by different colors or shadings. There are some more

93

options concerning the kind of shading to be applied, sequence numbering,

94

consensus output and so on. The user interface is a bit clumsy at

95

the moment, one has to answer a lot of questions in order to get the

96

desired output. There is, however, the possibility to use default

97

parameters from a standard parameter file or to supply the program

98

with parameters from the command line. At the moment, the VMS and DOS

99

versions of BOXSHADE have identical user interfaces.

100

</para>

101

<para>- Input formats -</para>

102

<para>

103

BOXSHADE 3.2 knows about the following input file formats: (some of

104

the are generally used only for MSDOS or VMS systems) + CLUSTAL and

105

CLUSTALV, multiple alignment program, DOS/VMS/MAC default extension .ALN

106

+ ESEE, multiple sequence editor, DOS default extension .ESE + PHYLIP,

107

phylogenetic analysis package, DOS, VMS, UNIX default extension .PHY +

108

PILEUP and PRETTY of the GCG sequence analysis package VMS/UNIX default

109

extensions .MSF and .PRE NB!! you are strongly encouraged NOT to use the

110

PRETTY format as input, it may be incompatible with the revised version

111

of .MSF input. We can't actually think why anyone would use this format

112

now, .MSF files are more useful generally. + MALIGNED, multiple sequence

113

editor, VMS only default extension .MAL BOXSHADE tries to determine the

114

file type from the extension but will work also if different extensions

115

are used.

116

</para>

117

<para> - Output devices - </para>

118

<para>POSTSCRIPT/EPS creates POSTSCRIPT(TM) files for printing on

119

a Laserprinter or for further conversion with a POSTCRIPT interpreter

120

(like GHOSTSCRIPT) + HPGL for export to various graphics programs or

121

for conversion/printing with the shareware program PRINTGL. Plotting

122

BOXSHADE output on a plotter is generally not recommended + RTF for

123

export to various word-processing and graphics programs + CRT, uses direct

124

screen writes to the PC-monitor. Possible options depend on the graphics

125

adapter used. This output device is supported only in the MSDOS version. +

126

ANSI. On a PC, this option uses an ANSI device driver (ANSI.SYS) that has

127

to be loaded in CONFIG.SYS previously. Possible character renditions are

128

reverse, bold,underlined, blinking etc. On non-DOS systems, this option

129

behaves more or less like the VT100 output mode. + VT100 for display on a

130

VT100 compatible terminal or emulator. + ReGISterm for display on a ReGIS

131

compatible graphics terminal or emulator. + ReGISfile for later conversion

132

by the program RETOS (copyright DEC) in order to print on DIGITALs

133

printer series. + LJ250 for printing on DIGITALS LJ250 color printer. +

134

ASCII output showing either the conserved residues or the varying ones

135

(others as '-'). + FIG file for xfig 2.1. + PICT files for import to Mac

136

and PC graphics progs. Some of the formats above offer the possibility

137

of scaling the characters and of rotating the plot. Character size has

138

to be entered in 'point' units. Normal output orientation is in portrait

139

mode (PS/EPS/HPGL/PICT only), to obtain output in landscape orientation,

140

'rotate plot = y' has to be chosen. When creating multi-page output,

141

all pages are contained in a single output file. If one page per file

142

is desired, one has to use the command line parameter /SPLIT. This is

143

enforced when requesting EPSF or PICT file output, as multi-page EPSFs

144

are a contradiction of the purpose of an EPSF and large PICT files would

145

probably be too big for most personal computers. While using the terminal

146

as output device, the 'RETURN' key has to be pressed to obtain the next

147

page of output.

148

</para>

149

<para>- Sequence numbering - </para>

150

<para>Starting with version 2.2 there

151

is the possibility to add numbering to the output files. The numbers are

152

printed between the sequence names and the sequence itself. Since most of

153

the input-files either use no numbering or number the first position in

154

the alignment always with a "1" (and that does not necessarily reflect

155

the numbers within the original sequence), the user is asked to enter

156

the starting position for each sequence. The command line flag /DEFNUM

157

suppressed that question, a starting position of 1 is assumed for all

158

sequences. Boxshade starts with the value entered for the leftmost

159

position and continues numbering every valid symbol, skipping blanks,

160

'-','.' and stuff like that.

161

</para>

162

<para>- Default parameters -</para>

163

<para>Several people using

164

previous releases of BOXSHADE pointed me to the need of having default

165

parameters for the various questions asked by the program. They argued

166

that most sites only use one type of input files, one output device and

167

one choice of colors for the output. I therefore added a management of

168

default parameters allowing two levels of assistance to the user. 1) all

169

default parameters are contained in an ASCII file that can be modified

170

easily to accomodate the users taste. The format is roughly documented

171

within the file-header, it resembles the keyboard input one has to make

172

if using the program interactively. There are two such files supplied

173

with this release of BOXSHADE, BOX_DNA.PAR and BOX_PEP.PAR , holding

174

some example parameters for peptide and dna-comparisons. there are no

175

big differences between these two, the major one is that when shading

176

DNA-comparisons one doesn't care of "similar" residues. 2) to run the

177

program with minimal user interaction, I have added the possibility to

178

use command line parameters. At the moment, you can use: /check : list

179

all allowed command line paramters (this list) and allows parameters to

180

be added. /def : program runs without questions, BOX_PEP.PAR is used as

181

default /dna : makes the program use BOX_DNA.PAR as parameter file /pep :

182

makes the program use BOX_PEP.PAR as parameter file /in=xxx : makes the

183

program take xxx as input file /out=yyy : makes the program take yyy as

184

output file (note1) /par=zzz : makes the program use zzz as a default

185

parameter file /type=1 : makes the program assume an input file of type

186

1 (PRETTY/MSF) /dev=1 : makes the program assume and output device of

187

type 1 (CRT) /numdef : use default numbering (all sequences starting

188

with "1") /thr : threshold fraction of residues that must agree for a

189

consensus /split : forces one page per file output, creates multiple

190

output files. /cons : makes the program create an additional consensus

191

line (see below) /symbcons=: influences the way the consensus line is

192

displayed. (see below) /unix : writes output files in unix style (LF only)

193

(note2) /dos : writes output files in DOS style (CR/LF) (note2) note1:

194

on unix machines, use out=OUTPUT for terminal output on DOS machines,

195

use out=con: on VMS machines, use out=tt: note2: if no mode is specified,

196

the native style of the machine is used.

197

</para>

198

<para>ATTENTION</para>

199

<para>on unix systems, the dash (-) instead of the slash (/) has to be used as separation character for command line paramters. For example, a valid unix command line is: <command>boxshade -def -numdef -cons -symbcons=" .*" **************************************************************************</command>

200

</para>

201

<para>- Shading strategies (similarity to consensus or single sequence) -</para>

202

<para>

203

Starting with version 3, BOXSHADE has a new shading system. The first

204

difference is the introduction of a threshold fraction of residues that

205

must agree for there to be a consensus. Previously, the program assumed

206

that SOME residue was always the consensus. If no two residues were the

207

same, the first sequence provided the consensus residue. This threshold

208

fraction can be any number between 0.0 and 1.0. The number of sequences

209

that must agree for there to be a consensus is, as you might expect,

210

this fraction times the total number of sequences in the alignment

211

(fractions of a sequence count as one, e.g. 3.2 becomes 4). The second

212

difference is the idea of 'consensus by similarity'; this tries to take

213

account of the situations where all the sequences may have (for example)

214

R or K at a position, but neither in a majority. It would not be logical

215

to shade one type of residue as 'identical' and the other as 'similar';

216

the threshold function might also eliminate both as being in too small

217

numbers. Therefore, if there is not a single residue that is conserved

218

(greater than the threshold) at a position, the program looks for a

219

'group' of amino acids that fulfills the requirements. 'Groups' are

220

defined in the .grp files. Users can tailor these to their personal

221

prejudices. Any amino acid not listed is assumed not to be in a group. All

222

members of a group are considered to be mutually similar, unlike the

223

.sim files, described below. If consensus by similarity is found, all the

224

residues in the consensus are shaded using the 'similar' shading defined

225

by the user. If the user does not select 'shading by similarity', only

226

identity-type consensus is looked at. If an identity-type consensus is

227

found, and similarity shading is in operation, the program looks to see

228

if the remaining residues are similar to the consensus residue. Here the

229

box_xxx.sim files are used. The main difference between relationships

230

in these files and those in the .grp files is that, e.g. in a .grp

231

file the line STA means that all three a.a.s are mutually similar. In

232

a .sim file S TA means that both T and A are considered similar to S,

233

where there is a conserved S residue in more than threshold number of

234

sequences. However, it does NOT mean that T and A are similar to each

235

other. Note that cases where two residues, or groups of residues,

236

fulfill the threshold requirements (as could happen with values of

237

the thr. fraction less than or equal to 0.5) are treated as having no

238

consensus. This describes the main shading model 'shading according to

239

a consensus'. The alternative model is called 'shading according to

240

a master sequence'. In this case the user is prompted for a sequence

241

of the alignment and consecutively that sequence is taken to be the

242

'consensus'. Only those residues become shaded that are identical or

243

similar to the chosen sequence. Output obtained with this option tends

244

to be less shaded and neglects similarities beween the other (non-chosen)

245

sequences. Starting in V2.7, this 'master sequence' can be hidden. Thus,

246

it only influences the shading of the other sequences without being

247

shown itself.

248

</para>

249

<para>- Consensus display - </para>

250

<para>Starting with version 2.5, BOXSHADE

251

offers the possibility to create an additional line holding a consensus

252

symbol. This line can either be obtained by using the command line

253

qualifier /CONS or interactively by answering the question ' create

254

consensus? '. The way this consensus line is displayed can be modified

255

by the command line parameter SYMBCONS=xyz, by editing the respecitve

256

entry in the .PAR file or interactively. Since the SYMBCONS syntax is

257

not intuitive, here a brief description: The SYMBCONS parameter consist

258

of exactly three symbols: + the first one stands for 'normal' sequence

259

residues that are not involved in any similar/identical relationship. +

260

the second symbol represents positions that are similar in all sequences

261

of the alignment. See the files BOX_PEP.SIM and BOX_DNA.SIM to see

262

what residues are considered similar. + the third symbol represents

263

positions that are identical in all sequences of the alignment. A

264

SYMBCONS parameter string " .*" (blank/point/asterisc) means: label

265

all positions in the alignment with totally identical residues by an

266

asterisc, all positions with all similar residues by a point and do not

267

mark the other positions. The letter 'B' can be used instead of the blank,

268

this is necessary e.g. when using the command line option /SYMBCONS=B.*

269

which gives the same result as the above example. The option /SYMBCONS=

270

.* would result in an unexpected behaviour because MSDOS squeezes blanks

271

out of the command line. Besides points, asteriscs and other symbols,

272

there are two special characters when they appear in the SYMBCONS string:

273

'L' and 'U'. An 'L' means, that a lowercase representation of the

274

most abundant residue at that position is to be used instead of a fixed

275

consensus symbol while an 'U' means an uppercase character representation

276

of that residue. A possible application would be the SYMBCONS string "

277

LU" where similar residues are represented by lowercase characters and

278

identical by uppercase characters.

279

</para>

280

<para>

281

- shareware/PD programs useful in conjunction with BOXSHADE -

282

</para>

283

<para>

284

multiple alignment files that to be used by BOXSHADE can be created,

285

amongst others, by the following PD/freeware programs: + PHYLIP by Joe

286

Felsenstein, available by ftp from anthro.utah.edu + ESEE by Eric Cabot,

287

available from the same sources as BOXSHADE (see above) + CLUSTAL by Des

288

Higgins, ditto for preview/conversion of POSTSCRIPT files, the program

289

GHOSTSCRIPT from GNU software foundation is highly recommended. It is

290

available from all major MSDOS ftp-sites (e.g. SIMTEL or ftp.uni-koeln.de)

291

There is also a version tested for use with boxshade available at

292

vax0.biomed.uni-koeln.de although this might be not the most recent

293

release. for Mac users, there is MacGhostscript, also available from the

294

main archives (info-mac, umich and their mirrors). A *very* good tool

295

for putting a preview image into an EPSF file, often a prerequisite for

296

incorporating into a drawing package, is PS2EPS, by Peter Lerup. This can

297

be found on info-mac. for preview/conversion of HPGL files, the shareware

298

program PRINTGL 1.18 by Cary Ravitz is highly recommended. It is available

299

from many MSDOS ftp sites and from netserv@embl-heidelberg.de - output on

300

dot printers - Since PRINTGL offers a broad choice of printer types and

301

is a nice program, I recommend its use for printing BOXSHADE output on

302

non-POSTSCRIPT printers. Use HPGL output with options 0F1N for normal

303

residues 2F1N for identical residues 3F1N for similar residues 2F4N

304

for conserved residues 8 for character size not rotated (these are the

305

standard parameters in BOX_PEP.PAR) for creating a HPGL files. (lets call

306

it TEST.PLT) Now use PRINTGL either interactively by calling PMI or use

307

a command line like: PRINTGL /Fx/S0340/Waaac/Ptest.plt where test.plt is

308

to be replaced by the filename to convert and the x in the expression

309

/Fx is to be replaced by the letter of the printer you use. (See the

310

PRINTGL documentation for further details)

311

</para>

312

</refsect1>

313

314

RESTRICTIONS

315

</title></refsect1>

316

<para>

317

The RTF output and PHYLIP input implementations are still

318

experimental. Please tell me of your experiences with the program. +

319

the current DOS version supports only 13 sequences with 2000 residues

320

each. This parameters can be easily changed in the source code. If you

321

cannot compile the sources because you are lacking a pascal compiler,

322

contact the author for precompiled versions

323

</para>

324

<refsect1><title>DISTRIBUTION POLICY</title>

325

<para>

326

BOXSHADE is completely public-domain and may be passed around and modified without any notice to the author. If you have problems, suggestions or remarks, please contact either of us:

327

Kay Hofmann, PhD Tel: +49 (221) 950 4814 Bioinformatics Group FAX: +49 (221) 950 4848

328

MEMOREC Stoffel GmbH Stoeckheimer Weg 1 D50829 Koeln/Germany

329

E-mail: Kay.Hofmann@memorec.com

330

Michael D. Baron Institute for Animal Health Ash Road Pirbright Surrey GU24 0NF U.K.

331

E-mail: michael.baron@bbsrc.ac.uk

332

</para>

333

</refsect1>

334

335

336

337

<para>/etc/boxshade/*.par</para>

338

<para><application>seaview</application> (1),

339

<application>clustalw</application> (1)

340

</para>

341

</refsect1>

342

343

<title>AUTHOR</title>

344

345

<para>This manual page was written by &dhusername; &dhemail; for

346

the &debian; system (but may be used by others). Permission is

347

granted to copy, distribute and/or modify this document under

348

the terms of the &gnu; General Public License, Version 2 any

349

later version published by the Free Software Foundation.

350

</para>

351

<para>

352

On Debian systems, the complete text of the GNU General Public

353

License can be found in /usr/share/common-licenses/GPL.

354

</para>

355

356

</refsect1>

357

</refentry>

358