README.rst 10.9 KB
Newer Older
jhoogenboom's avatar
jhoogenboom committed
1
2
3
4
5
6
7
8
9
Forensic DNA Sequencing Tools
=============================

Tools for filtering and interpretation of Next Generation Sequencing data of
forensic DNA samples. To obtain a list of included tools with a brief
description of each tool, run:

    ``fdstools -h``

10
For a complete description of a specific tool and its command line arguments,
jhoogenboom's avatar
jhoogenboom committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
run:

    ``fdstools -h TOOLNAME``


Installation
------------

The recommended way to install FDSTools is by using the ``pip`` package
installer. If you have ``pip`` installed, you can easily install FDSTools by
typing:

    ``pip install fdstools``

Alternatively, FDSTools can be installed by running:
26

jhoogenboom's avatar
jhoogenboom committed
27
28
29
30
31
    ``python setup.py install``


FDSTools Changelog
------------------
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
v0.0.4
    - FDSTools will now print profiling information to stdout when the
      -d/--debug option was specified.
    - Fixed bug where specifying '-' as the output filename would be taken
      literally, while it should have been interpreted as 'write to standard
      out' (Affected tools: BGCorrect, Samplestats, Seqconvert, Stuttermark).
    - Added more detailed license information to FDSTools.
    - Updated bundled JavaScript library Vega to v2.6.0
    - Updated bundled JavaScript library D3 to v3.5.17
    - Includes BGCorrect v1.0.1
    - Includes BGEstimate v1.1.0
    - Includes BGMerge v1.0.1
    - Includes BGPredict v1.0.1
    - Includes Libconvert v1.0.1
    - Includes Samplestats v1.0.1
    - Includes Seqconvert v1.0.1
    - Includes Stuttermodel v1.1.0
    - Includes TSSV v1.0.1
    - Includes Vis v1.0.1
    - Includes Allelevis v1.0.0beta2
    - Includes BGRawvis v1.0.1
    - Includes Profilevis v1.0.1
    - Includes Samplevis v2.0.1
    - Includes Stuttermodelvis v1.0.0beta2

57
v0.0.3
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
    - Updated bundled JavaScript library Vega to v2.5.0
    - Updated bundled JavaScript library D3 to v3.5.12
    - Includes Allelefinder v1.0.0
    - Includes BGCorrect v1.0.0
    - Includes BGEstimate v1.0.0
    - Includes BGHomRaw v1.0.0
    - Includes BGHomStats v1.0.0
    - Includes BGMerge v1.0.0
    - Includes BGPredict v1.0.0
    - Includes Blame v1.0.0
    - Includes FindNewAlleles v1.0.0
    - Includes Libconvert v1.0.0
    - Includes Samplestats v1.0.0
    - Includes Seqconvert v1.0.0
    - Includes Stuttermark v1.5.0
    - Includes Stuttermodel v1.0.0
    - Includes TSSV v1.0.0
    - Includes Vis v1.0.0
    - Includes Allelevis v1.0.0beta1
    - Includes BGRawvis v1.0.0
    - Includes Profilevis v1.0.0
    - Includes Samplevis v2.0.0
    - Includes Stuttermodelvis v1.0.0beta1
81

jhoogenboom's avatar
jhoogenboom committed
82
83
84
85
v0.0.2
    - Added global -d/--debug switch
    - Includes Stuttermark v1.4

jhoogenboom's avatar
jhoogenboom committed
86
87
88
89
90
v0.0.1
    - Initial version
    - Includes Stuttermark v1.3


91
92
93
94
95
96
97
Allelefinder
~~~~~~~~~~~~
v1.0.0
    - Initial version


BGCorrect
jhoogenboom's avatar
jhoogenboom committed
98
~~~~~~~~~
99
100
101
102
103
v1.0.1
    - Added new column 'weight' to the output. The value in this column
      expresses the number of times that the noise profile of that allele
      fitted in the sample.

104
105
106
107
108
109
v1.0.0
    - Initial version


BGEstimate
~~~~~~~~~~
110
111
112
113
114
115
116
117
118
119
120
121
v1.1.0
    - Added a new option -g/--min-genotypes (default: 3). Only alleles that
      occur in at least this number of unique heterozygous genotypes will be
      considered. This is to avoid 'contamination' of the noise profile of one
      allele with the noise of another. If homozygous samples are available for
      an allele, this filter is not applied to that allele. Setting this option
      to 1 effectively disables it. This option has the same cascading effect
      as the -s/--min-samples option, that is, if one allele does not meet the
      threshold, the samples with this allele are excluded which may cause some
      of the other alleles of these samples to fall below the threshold as
      well.

122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
v1.0.0
    - Initial version


BGHomRaw
~~~~~~~~
v1.0.0
    - Initial version


BGHomStats
~~~~~~~~~~
v1.0.0
    - Initial version


BGMerge
~~~~~~~
140
141
142
v1.0.1
    - Reduced memory usage

143
144
145
146
147
148
v1.0.0
    - Initial version


BGPredict
~~~~~~~~~
149
150
151
152
153
154
155
156
v1.0.1
    - Greatly reduced memory usage.
    - BGPredict will now output nonzero values below the threshold set by
      -n/--min-pct if the predicted noise ratio of the same stutter on the
      other strand is above the threshold. Previously, values below the
      threshold were clipped to zero, which may cause unnecessarily high strand
      bias in the predicted profile.

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
v1.0.0
    - Initial version


Blame
~~~~~
v1.0.0
    - Initial version


FindNewAlleles
~~~~~~~~~~~~~~
v1.0.0
    - Initial version


Libconvert
~~~~~~~~~~
175
176
177
178
179
v1.0.1
    - Specifying '-' as the first positional argument to libconvert will now
      correctly interpret this as "read from stdin" instead of throwing a "file
      not found" error (or reading from a file named "-" if it exists)

180
181
182
183
184
185
v1.0.0
    - Initial version


Samplestats
~~~~~~~~~~~
186
187
188
189
190
191
192
193
194
195
196
197
198
199
v1.0.1
    - Samplestats will now round to 4 or 5 significant digits if a value is
      above 1000 or 10000, respectively. Previously, this was only done for the
      combined 'Other sequences' values
    - The 'Other sequences' lines will now also include values for
      total_recovery, forward_recovery, and reverse_recovery
    - The total_recovery, forward_recovery, and reverse_recovery columns are no
      longer placed to the left of all the other columns generated by
      Samplestats
    - The help text for Samplestats erroneously listed the X_recovery_pct
      instead of X_recovery
    - Added support for the new 'weight' column produced by BGCorrect when the
      -a/--filter-action option is set to 'combine'

200
201
202
203
204
205
v1.0.0
    - Initial version


Seqconvert
~~~~~~~~~~
206
207
208
209
210
211
v1.0.1
    - Internal naming of the first positional argument was changed from
      'format' to 'sequence-format'. This was done for consistency with the
      -F/--sequence-format option in other tools, giving it the same name in
      Pipeline configuration files.

212
213
v1.0.0
    - Initial version
jhoogenboom's avatar
jhoogenboom committed
214

215
216
217
218

Stuttermark
~~~~~~~~~~~
v1.5.0
219
    - Changed column names 'name' and 'allele' to 'marker' and 'sequence',
220
      respectively. WARNING: Stuttermark is now INCOMPATIBLE with output
221
222
      from TSSV_ but made compatible with TSSV-Lite and the new, bundled TSSV
      tool instead.
223

224
v1.4.0
jhoogenboom's avatar
jhoogenboom committed
225
226
227
228
229
    - Stuttermark now accepts raw sequences and allele names as input, which
      are automatically rewritten as TSSV-style sequences using a specified
      library file
    - The 'name' column is now optional

230
v1.3.0
jhoogenboom's avatar
jhoogenboom committed
231
232
233
234
    - First version of Stuttermark to be included in ``fdstools``
    - Fixed crash that occurred when an empty allele (e.g., a primer dimer)
      was encountered
    - Stuttermark now prints a warning if an allele is encountered that is
jhoogenboom's avatar
jhoogenboom committed
235
      not a TSSV_-style sequence
jhoogenboom's avatar
jhoogenboom committed
236

237
v1.2.0
jhoogenboom's avatar
jhoogenboom committed
238
239
240
    - All settings are now available from the command line
    - Use 1-based indexing in ``STUTTER`` annotations

241
v1.1.0
jhoogenboom's avatar
jhoogenboom committed
242
243
244
    - Stuttermark now accepts file names and the minimum number of reads to
      evaluate as command line arguments

245
v1.0.0
jhoogenboom's avatar
jhoogenboom committed
246
247
248
    - Initial version


249
250
Stuttermodel
~~~~~~~~~~~~
251
252
253
254
255
256
257
258
v1.1.0
    - Stuttermodel will now only output a fit for one strand if it could also
      obtain a fit for the other strand (for the same marker, unit, and stutter
      depth). This new behaviour can be disabled with a new -O/--orphans
      option.
    - Fixed bug that caused Stuttermodel to output only the raw data points for
      -1 and +1 stutter when normal output was supressed

259
260
v1.0.0
    - Initial version
jhoogenboom's avatar
jhoogenboom committed
261
262


263
264
TSSV
~~~~
265
266
267
268
269
270
v1.0.1
    - Renamed the '--is_fastq' option to '--is-fastq', which was the only
      option with an underscore instead of a hyphen in FDSTools
    - Fixed crash that would occur if -F/--sequence-format was set to anything
      other than 'raw'

271
272
v1.0.0
    - Initial version
jhoogenboom's avatar
jhoogenboom committed
273
274


275
276
Vis
~~~
277
278
279
280
281
v1.0.1
    - Added -j/--jitter option for Stuttermodelvis (default: 0.25)
    - Fixed bug where Vis would not allow the -n/--min-abs and the
      -s/--min-per-strand options to be set to 0

282
283
v1.0.0
    - Initial version
jhoogenboom's avatar
jhoogenboom committed
284
285


286
287
Allelevis
~~~~~~~~~
288
289
290
291
292
293
294
295
v1.0.0beta2
    - Fixed potential crash/corruption that could occur with very unfortunate
      combinations of sample names and marker names
    - HTML visualisations made with the -O/--online option of the Vis tool will
      now contain https URLs instead of http
    - Added two more colours to the legend, such that a maximum of 22 markers
      is now supported without re-using colours

296
297
298
v1.0.0beta1
    - Initial version

jhoogenboom's avatar
jhoogenboom committed
299

300
301
BGRawvis
~~~~~~~~
302
303
304
305
306
307
308
309
310
v1.0.1
    - Fixed a JavaScript crash that would occur in HTML visualisations if the
      Marker name filter resulted in an invalid regular expression (e.g., when
      the entered value ends with a backslash)
    - Reduced Vega graph spec complexity by using the new Rank transform to
      position the subgraphs
    - HTML visualisations made with the -O/--online option of the Vis tool will
      now contain https URLs instead of http

311
312
313
314
315
316
v1.0.0
    - Initial version


Profilevis
~~~~~~~~~~
317
318
319
320
321
322
323
324
325
v1.0.1
    - Fixed a JavaScript crash that would occur in HTML visualisations if the
      Marker name filter resulted in an invalid regular expression (e.g., when
      the entered value ends with a backslash)
    - Reduced Vega graph spec complexity by using the new Rank transform to
      position the subgraphs.
    - HTML visualisations made with the -O/--online option of the Vis tool will
      now contain https URLs instead of http

326
327
328
329
330
331
v1.0.0
    - Initial version


Samplevis
~~~~~~~~~
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
v2.0.1
    - Fixed a JavaScript crash that would occur in HTML visualisations if the
      Marker name filter resulted in an invalid regular expression (e.g., when
      the entered value ends with a backslash)
    - Reduced Vega graph spec complexity by using the new Rank transform to
      position the subgraphs
    - Fixed a glitch in HTML visualisations where clicking the 'Truncate
      sequences to' label would select the marker spacing input
    - In HTML visualisations, the 'Notes' table cells with 'BGPredict' in them
      now get a light orange background to warn the user that their background
      profile was computed. If a sequence was explicitly 'not corrected', 'not
      in ref db', or 'corrected as background only', the same colour is used.
    - The message bar at the bottom of Samplevis HTML visualisations will now
      grow no larger than 3 lines. A scroll bar will appear as needed.
    - HTML visualisations made with the -O/--online option of the Vis tool will
      now contain https URLs instead of http

349
350
351
352
353
354
v2.0.0
    - Initial version


Stuttermodelvis
~~~~~~~~~~~~~~~
355
356
357
358
359
360
361
362
363
364
365
366
v1.0.0beta2
    - HTML visualisations now support drawing raw data points on top of the fit
      functions. The points can be drawn with an adjustable jitter to reduce
      overlap.
    - Fixed a JavaScript crash that would occur in HTML visualisations if the
      Repeat unit or Marker name filter resulted in an invalid regular
      expression (e.g., when the entered value ends with a backslash)
    - Reduced Vega graph spec complexity by using the new Rank transform to
      position the subgraphs.
    - HTML visualisations made with the -O/--online option of the Vis tool will
      now contain https URLs instead of http

367
368
v1.0.0beta1
    - Initial version
jhoogenboom's avatar
jhoogenboom committed
369
370
371


.. _TSSV: https://pypi.python.org/pypi/tssv/