How to write bioinformatics software people will use and cite. Includes discoverability, usability and marketing. Does NOT cover testing.

1. How to write bioinformatics software
that people will use & cite
A/Prof Torsten Seemann
@torstenseemann
Bioinfosummer 2016 - Adelaide AU, Fri 2 Dec

2. Who am I ?

3. Doherty Applied
Microbial Genomics
Microbial genomics and bioinformatics

4. Public health and clinical microbiology

5. Before bioinformatics
● Undergraduate
○ Science / Engineering - Computer Science + Electrical En
● Honours
○ Computer Science - Digital image compression
● PhD
○ Computer Science - Digital image processing
● Never studied any biology

6. An opportunity

7. First “fully Aussie” bacterial genome
● Leptospira hardjobovis str. L550
● 2 chromosomes
● 4 Mbp
● $1M dollar project
● Sanger sequencing
● Led by Dieter Bulach

8. First Illumina instrument in Australia
● Dept Microbiology
Monash University, 2008
● 36 bp single end reads
● 2 weeks to run
● 2 lanes for 1.6 Mbp genome

9. Things have improved a bit since then
Q32
36 bp
Q20

10. Why am I here?

11. Bioinformatics software and me
Installed >1000 packages manually
Authored >100 packages into Brew
Written and maintain >10 packages

12. How to get a bioinformatics headache
1. See tweet about new published tool
2. Read abstract - sounds awesome!
3. Fail to find link to source code - eventually Google it
4. Attempt to compile and install it
5. Google for 30 min for fixes
6. Finally get it built
7. Run it on tiny data set
8. Get a vague error
9. Delete and never revisit it again

15. Should I stay for this talk ?
YES
It will help you write good tools
YES
It will help you identify bad tools

16. Should you write a tool?

17. Should you write a new tool?
● NO
○ It already exists
○ You are unable to maintain it
○ You won’t really use it
● YES
○ YOU need the tool
○ YOU will use the tool
○ YOU want others to use the tool
○ Desire to give back to the community

18. Eating my own dog food

19. Lessons from the Prokka experience
● Nearly all feedback is positive
● People all over the world are grateful
● Warm fuzzy feeling inside
● Increase your public profile
● But maintenance burden and guilt

20. Discoverability

21. Choosing a home base
University page
Personal home page

22. Naming
● Try to be unique
○ Google to check for conflicts
○ Consider how internationals will pronounce it
○ Be creative!
● Avoid dodgy acronyms
○ Try not to win a JABBA Award
○ “Just Another Bogus Bioinformatics Acronym”

23. Don’t be this person

24. First impressions count
● Keep It Simple Stupid
● First page of documentation
○ What does it do?
○ How do I install it?
○ How do I run it?
● Try to keep in one place
○ Otherwise becomes inconsistent or missed

25. Usability

26. A lesson from history

27. Print something useful if no parameters
% biotool
Please use --help for instructions

28. Always have a --help flag
% biotool -h
% biotool --help
Usage: biotool [options] seq.fa
--help Show this help
--version Print version and exit
--top N Keep top N sequences

29. Always have a --version flag
% biotool -v
% biotool -V
% biotool --version
biotool 1.3

30. Always raise an error when things go wrong
% biotool seq.fa
ERROR: can not open file ‘seq.fa’

31. Check that dependencies are installed
% biotool seq.fa
Checking BLAST... ok
Checking SAMtools... NOT FOUND!
Please install ‘samtools’ and add
it to your PATH.

32. Always let users control output filenames
% biotool seq.fa
Processing ‘seq.fa’
Wrote result to ‘filt.seq.fa.out’
# ARGH!
% biotool --out seq.filt.fa

33. KISS - run with minimum parameters
% biotool seq.fa
ERROR: missing -x parameter
% biotool -x 3 seq.fa
ERROR: missing -y parameter
% biotool -x 3 -y 7 seq.fa
ERROR: need -n name
# ARGH!

34. Standards

36. Use the standard getopt interface
Short options ( -h ) and long options ( --help )
● C #include <getopt.h>
● C++ boost:program_options
● Python import argparse
● Perl use Getopt::Long
● R library(argparse)
Command line interface

37. Unix exit codes
● A positive integer
● Loose standards
○ 0 = success
○ 1 = general failure
○ 2 = error with command line
○ 3..127 = user defined specific failures
● Result in shell $? Variable

38. Accessing exit codes in the shell
% ls /tmp/fake
ls: cannot access /tmp/fake
% echo $?
1
% ls /proc/cpuinfo
/proc/cpuinfo
% echo $?
0

39. Using stdin, stderr and stdout
● Stdin (0) command < input
● Stdout (1) command > output
● Stderr(2) command 2> errors
● All command < input > output 2> errors
● Allows piping!
sort input | command1 1> output 2> errors

40. This makes your tool useful in streaming
% zcat seq.fastq.gz |
cutadapt -a adapters.fa |
qualtrim -Q 20 |
bwa mem -t 8 ref.fa |
samtools sort --threads 4
> seq.bam

41. Use standards compliant files *
● Feature coordinates
○ BED, GFF
● Columnar data (put headings!)
○ TSV
○ CSV
● Structured data
○ JSON
○ YAML
* XML excepted

42. Installation

43. Keeping your audience
“Each equation in a book
will halve your audience”
“Each difficulty encountered in installation
will halve your number of users”

44. Traditional systems level packaging
● Debian / DEB
apt-get install blast
dpkg -i blast-2.2.5-amd64.deb
● Redhat / RPM
yum install blast
rpm -i blast-2.2.5-x86_64.rpm
● Various others

45. Cross platform solutions: Linux, Mac, Windows
● Brew
brew install blast
● Conda
conda install blast
● Others
○ GUIX, ...
○ Docker, AMI images

46. Language specific repositories
● Python - PIP
pip install ariba
● Perl - CPAN
cpanm Bio::Roary
● R - CRAN
install.packages(“edgeseq3”)

47. Marketing

48. Publish it
● Preprint archive
○ PeerJ, bioRxiv
● Method focussed journal
○ Bioinformatics, BMC Bioinformatics
● Software focussed journal
○ Journal of Open Source Software

49. Plug it
● Twitter
○ Ask someone popular you know to retweet it
● Blog
○ Start a general blog and slot
● Conferences
○ Tell people about it

50. Support your users
● Reply to emails
● Monitor your “Issues” web site
● Monitor Biostars and SeqAnswers
● Have a mailing list
● Update your documentation
● Fix bugs

51. Conclusions

52. Take home messages
● Make it as painless as possible to install
● Keep documentation clear and simple
● Get people to use it before you publish
● People are not judging your coding skills
● But they will curse you if waste their time
● Most users are grateful - leads to free beer
● A good tools worth much more than a paper

53. Acknowledgments
● Gary Glonek
● David Adelson
● Bernard Pope - VLSCI
● Dieter Bulach - VLSCI
● Anna Syme - VLSCI
● David Powell - Monash University
● Anders Goncalves da Silva - University of Melbourne

54. References
1. https://gigascience.biomedcentral.com/articles/10.1186/2047-217X-2-15
2. http://berniepope.id.au/scientific_software_etiquette.html
3. http://thegenomefactory.blogspot.com.au/

55. The end.