BioPerl:Style guide

From BioPerl
Jump to: navigation, search

Contents

Quick start

What you want Enter this To create this
Internal Wiki link [[BLAST]] BLAST
Internal Wiki link w/ display name [[BLAST|tblastn]] tblastn
HOWTO link {{HOWTO|SearchIO}} SearchIO HOWTO
HOWTO link w/ display name [[HOWTO:SearchIO|How to use SearchIO]] How to use SearchIO
BioPerl module link {{PM|Bio::SeqIO}} Bio::SeqIO
BioPerl module link w/ display name [[Module:Bio::SeqIO|the SeqIO module]] the SeqIO module
BioPerl script in SVN trunk {{PLS|examples/rev_and_trans.pl}} or {{PLS|examples/rev_and_trans.pl|rev_and_trans.pl}} examples/rev_and_trans.pl

or rev_and_trans.pl

External Wikipedia link [[wp:The Beatles|The Fab Four]] The Fab Four
CPAN module link {{CPAN|Class::DBI}} Class::DBI
Bare URL http://www.google.com/ http://www.google.com/
Display an image [[Image:Bioperl-pub-data.png]]
URL w/ display name [http://www.google.com/ Search Google] Search Google
Put page in category [[Category:Tools]] (link to other Tools in page footer)
Sign your name with date ~~~~ Tseemann 02:11, 28 December 2005 (EST) (for example)
Sign talk comments (with time stamp) --~~~~ --Tseemann 02:11, 28 December 2005 (EST) (for example)
Filenames, paths, $ENV_VARS <tt>$PREFIX/lib/perl.so</tt> $PREFIX/lib/perl.so
Inline code examples <code>$fh->print("BioPerl")</code> $fh->print("BioPerl")
Blocks of code Indent it, or use PRE tags:
<pre>
#!/usr/bin/perl -w
use strict;
use Bio::Perl;
</pre>
#!/usr/bin/perl -w
use strict;
use Bio::Perl;
Colored Perl code <perl>my $db = Bio::DB::GenBank->new</perl>
my $db = Bio::DB::GenBank->new

Wiki links

Typing [[BLAST]] will create this BLAST link, to the BLAST page within the BioPerl Wiki.

Modules

References to modules should be in the Module namespace we have created a template to make this easy. Just use the {{PM}} template like this.

{{PM|Bio::SeqIO}}

Which produces Bio::SeqIO automagically for you.

When writing a Module page, you should use the template {{Modules}} and {{Doclink|{{PAGENAME}} which will add the category link to the page and will autogenerate a Documentation link to the Pdoc documentation and CPAN. So literally copy+paste the following at the top of any new Module: namespace page and we'll be off to the races.

{{Module}}{{Doclink|{{PAGENAME}}}}

If we ever change something about this linking we can systematically fix it in one place by changing the template. Neat eh?

Some modules are in a separate repository module and thus a separate directory name for the Pdoc links. However their namespace is not unique (i.e. there are core modules in the Bio::DB namespace like Bio::DB::GenBank and there are modules in the bioperl-db distro which are in the core namespace like Bio::BioEntry). We can generaly handle all of the bioperl-run modules since they are in Run namespace. There is a special case for Bio::Tools::Run::StandAloneBlast and Bio::Tools::Run::RemoteBlast modules since they are still in the Core package. To get around this for the rest of the modules and CVS modules though, I've made special Templates. Use the {{DB Module}}{{DB Doclink|{{PAGENAMEE}}}} to link BioPerl db modules.

Similarly for bioperl-ext, bioperl-pedigree, bioperl-gui, and bioperl-microarray (and eventually bioperl-graph) modules you'll need to use the {{Ext Module}}, {{Pedigree Module}}, {{GUI Module}}, and {{Microarray Module}} templates (and add the appropriate prefix for the Doclink templates as well)

HOWTOs

Links to the HOWTO namespace take the form of [[HOWTO:<name>|<display name>]], or you can use the Template:HOWTO macro. e.g.

[[HOWTO:SearchIO|SearchIO HOWTO]]

or

{{HOWTO|SearchIO}}

both automagically create SearchIO HOWTO for you.

Warning: When using the HOWTO template (macro) make sure you use a "|" to separate the argument from the HOWTO string. If you use a ":" instead, you will get the SearchIO HOWTO page literally included in the page you are editing, instead of an simple Wiki link!

Interwiki

Wikipedia

As you know, Wikipedia has very good content, particularly in the areas of science and software. So, instead of creating a page for "XML" here in our Wiki use the existing entry over in Wikipedia.

 [[wp:XML|XML]]

creates XML for you. Don't waste effort re-inventing the wheel!

Custom Interwiki Linking

Instructions on how to create your own Interwiki links are here:

http://meta.wikimedia.org/wiki/Help:Guide_for_system_administrators_for_setting_up_interwiki_linking

CPAN

A lot of BioPerl code leverages the power of existing Perl modules in CPAN, so use the CPAN macro to link to them when needed:

 {{CPAN|List::Util}}

creates List::Util for you automatically.

URLs

  • To link to a bare URL, simply type it as is: http://sf.net/
  • To give it a display name, [http://sf.net/ SourceForge] creates SourceForge

Code markup

  • Indent big blocks of code, or explicitly surround with <pre></pre> tags.
  • Inline code samples, use <code></code> tags.
  • Inline filenames, paths, environmental variables, ... use <tt></tt> tags.
  • Perl syntax highlighting, use <perl></perl> tags.

Important Categories

To place a page in category CATNAME, type [[Category:CATNAME]]. Just use multiple tags if a page is in more than one category. Important categories are:

  • TODO - put pages that have "TODO" or "FIXME" strings here
  • Tools - for bioinformatics tools
  • Formats - for file formats
  • People - for pages that describe a person

There are also more finer grained categories, see Special:Categories for a list of them all.

References / Bibliography

Wiki will automagically create links to PubMed (doubtless Jason set this up, it's way cool).

Write something like this:

 TFBS <cite>tfbs</cite> is also a package of Bioperl-compatible 
 Perl modules that are used for TF binding site detection.

 ==References==
 <biblio>
 #tfbs pmid=12176838
 </biblio>

And Wiki, plus Jason's script, transforms the above text into this:

 TFBS [1] is also a package of Bioperl-compatible Perl modules that are used 
 for TF binding site detection.

 References

 1. Lenhard B and Wasserman WW. TFBS: Computational framework for transcription 
 factor binding site analysis. Bioinformatics 2002 Aug; 18(8) 1135-6   
 PubMed [tfbs]

Programming Language

You can use the Winter language if you want some Turing-completeness-but-with-syntactic-sugar in your macros aka Templates. It's "lotsa fun!"...

Be careful when calling other Wiki templates from this language. You have to enclose the paramters in <NOWIKI> tags to ensure they get passes as-is. See Template:Doclink for an example.

Perl-aware formatting

You can color-code your perl by enclosing it in <perl></perl> tags. For example:

<perl>
     use Bio::TreeIO;
     # parse in newick/new hampshire format
     my $input = new Bio::TreeIO(-file   => "tree.tre",
                                 -format => "newick");
</perl>

Creates:

      use Bio::TreeIO;
      # parse in newick/new hampshire format
      my $input = new Bio::TreeIO(-file   => "tree.tre",
                                  -format => "newick");
Personal tools
Variants
Actions
Main Links
documentation
community
development
Toolbox