Class | Bio::Reference
In: | lib/bio/reference.rb
Parent: | Object

# DESCRIPTION

A class for journal reference information.

# USAGE

       hash = {'authors' => [ "Hoge, J.P.", "Fuga, F.B." ],
               'title' => "Title of the study.",
               'journal' => "Theor. J. Hoge",
               'volume' => 12,
               'issue' => 3,
               'pages' => "123-145",
               'year' => 2001,
               'pubmed' => 12345678,
               'medline' => 98765432,
               'abstract' => "Hoge fuga. ...",
               'url' => "http://example.com",
               'mesh' => [],
               'affiliations' => []}
       ref = Bio::Reference.new(hash)

       # Formats in the BiBTeX style.
       ref.format("bibtex")

       # Short-cut for Bio::Reference#format("bibtex")
       ref.bibtex

### Methods

== bibitem bibtex cell current embl endnote format general genome_biol genome_res nar nature new pubmed_url rd science trends

### Attributes

abstract | [R] | Abstract text in String.
affiliations | [R] | Affiliations in an Array.
authors | [R] | Author names in an Array, [ "Hoge, J.P.", "Fuga, F.B." ].
comments | [R] | Comments for the reference (typically Array of String, or nil)
doi | [R] | DOI identifier (typically String, e.g. "10.1126/science.1110418")
embl_gb_record_number | [R] | Sequence number in EMBL/GenBank records
issue | [R] | issue number (typically Fixnum)
journal | [R] | String with journal name
medline | [R] | medline identifier (typically Fixnum)
mesh | [R] | MeSH terms in an Array.
pages | [R] | page range (typically String, e.g. "123-145")
pubmed | [R] | pubmed identifier (typically Fixnum)
sequence_position | [R] | Position in a sequence that this reference refers to
title | [R] | String with title of the study
url | [R] | An URL String.
volume | [R] | volume number (typically Fixnum)
year | [R] | year of publication (typically Fixnum)

### Public Class methods

new(hash)

Create a new Bio::Reference object from a Hash of values. Data is extracted from the values for keys:

- authors - expected value: Array of Strings
- title - expected value: String
- journal - expected value: String
- volume - expected value: Fixnum or String
- issue - expected value: Fixnum or String
- pages - expected value: String
- year - expected value: Fixnum or String
- pubmed - expected value: Fixnum or String
- medline - expected value: Fixnum or String
- abstract - expected value: String
- url - expected value: String
- mesh - expected value: Array of Strings
- affiliations - expected value: Array of Strings

       hash = {'authors' => [ "Hoge, J.P.", "Fuga, F.B." ],
               'title' => "Title of the study.",
               'journal' => "Theor. J. Hoge",
               'volume' => 12,
               'issue' => 3,
               'pages' => "123-145",
               'year' => 2001,
               'pubmed' => 12345678,
               'medline' => 98765432,
               'abstract' => "Hoge fuga. ...",
               'url' => "http://example.com",
               'mesh' => [],
               'affiliations' => []}
       ref = Bio::Reference.new(hash)

Arguments:

- (required) hash: Hash

Returns: | Bio::Reference object

[Source]

         # File lib/bio/reference.rb, line 133
    133:     def initialize(hash)
    134:       @authors  = hash['authors'] || [] # [ "Hoge, J.P.", "Fuga, F.B." ]
    135:       @title    = hash['title']   || '' # "Title of the study."
    136:       @journal  = hash['journal'] || '' # "Theor. J. Hoge"
    137:       @volume   = hash['volume']  || '' # 12
    138:       @issue    = hash['issue']   || '' # 3
    139:       @pages    = hash['pages']   || '' # 123-145
    140:       @year     = hash['year']    || '' # 2001
    141:       @pubmed   = hash['pubmed']  || '' # 12345678
    142:       @medline  = hash['medline'] || '' # 98765432
    143:       @doi      = hash['doi']
    144:       @abstract = hash['abstract'] || ''
    145:       @url      = hash['url']
    146:       @mesh     = hash['mesh'] || []
    147:       @embl_gb_record_number = hash['embl_gb_record_number'] || nil
    148:       @sequence_position = hash['sequence_position'] || nil
    149:       @comments  = hash['comments']
    150:       @affiliations = hash['affiliations'] || []
    151:     end

### Public Instance methods

==(other)

If other is equal with the self, returns true. Otherwise, returns false.

Arguments:

- (required) other: any object

Returns: | true or false

[Source]

         # File lib/bio/reference.rb, line 159
    159:     def ==(other)
    160:       return true if super(other)
    161:       return false unless other.instance_of?(self.class)
    162:       flag = false
    163:       [ :authors, :title, :journal, :volume, :issue, :pages,
    164:         :year, :pubmed, :medline, :doi, :abstract,
    165:         :url, :mesh, :embl_gb_record_number,
    166:         :sequence_position, :comments, :affiliations ].each do |m|
    167:         begin
    168:           flag = (self.__send__(m) == other.__send__(m))
    169:         rescue NoMethodError, ArgumentError, NameError
    170:           flag = false
    171:         end
    172:         break unless flag
    173:       end
    174:       flag
    175:     end

bibitem(item = nil)

Returns reference formatted in the bibitem style

      # ref is a Bio::Reference object
      puts ref.bibitem

        \bibitem{PMID:12345678}
        Hoge, J.P., Fuga, F.B.
        Title of the study.,
        {\em Theor. J. Hoge}, 12(3):123--145, 2001.

Arguments:

- (optional) item: label string (default: `"PMID:#{pubmed}"`).

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 316
    316:     def bibitem(item = nil)
    317:       item  = "PMID:#{@pubmed}" unless item
    318:       pages = @pages.sub('-', '--')
    319:       return "\\\\bibitem{\#{item}}\n\#{@authors.join(', ')}\n\#{@title},\n{\\\\em \#{@journal}}, \#{@volume}(\#{@issue}):\#{pages}, \#{@year}.\n".enum_for(:each_line).collect {|line| line.strip}.join("\n")
    320:     end

bibtex(section = nil, label = nil, keywords = {})

Returns reference formatted in the BiBTeX style.

      # ref is a Bio::Reference object
      puts ref.bibtex

        @article{PMID:12345678,
          author  = {Hoge, J.P. and Fuga, F.B.},
          title   = {Title of the study.},
          journal = {Theor. J. Hoge},
          year    = {2001},
          volume  = {12},
          number  = {3},
          pages   = {123--145},
        }

      # using a different section (e.g. "book")
      # (but not really configured for anything other than articles)
      puts ref.bibtex("book")

        @book{PMID:12345678,
          author  = {Hoge, J.P. and Fuga, F.B.},
          title   = {Title of the study.},
          journal = {Theor. J. Hoge},
          year    = {2001},
          volume  = {12},
          number  = {3},
          pages   = {123--145},
        }

Arguments:

- (optional) section: BiBTeX section as String
- (optional) label: Label string cited by LaTeX documents.

                          Default is <tt>"PMID:#{pubmed}"</tt>.

- (optional) keywords: Hash of additional keywords,

                             e.g. { 'abstract' => 'This is abstract.' }.
                             You can also override default keywords.
                             To disable default keywords, specify false as
                             value, e.g. { 'url' => false, 'year' => false }.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 367
    367:     def bibtex(section = nil, label = nil, keywords = {})
    368:       section = "article" unless section
    369:       authors = authors_join(' and ', ' and ')
    370:       thepages = pages.to_s.empty? ? nil : pages.sub(/\-/, '--')
    371:       unless label then
    372:         label = "PMID:#{pubmed}"
    373:       end
    374:       theurl = if !(url.to_s.empty?) then
    375:                  url
    376:                elsif pmurl = pubmed_url and !(pmurl.to_s.empty?) then
    377:                  pmurl
    378:                else
    379:                  nil
    380:                end
    381:       hash = {
    382:         'author'  => authors.empty?    ? nil : authors,
    383:         'title'   => title.to_s.empty? ? nil : title,
    384:         'number'  => issue.to_s.empty? ? nil : issue,
    385:         'pages'   => thepages,
    386:         'url'     => theurl
    387:       }
    388:       keys = %w( author title journal year volume number pages url )
    389:       keys.each do |k|
    390:         hash[k] = self.__send__(k.intern) unless hash.has_key?(k)
    391:       end
    392:       hash.merge!(keywords) { |k, v1, v2| v2.nil? ? v1 : v2 }
    393:       bib = [ "@#{section}{#{label}," ]
    394:       keys.concat((hash.keys - keys).sort)
    395:       keys.each do |kw|
    396:         ref = hash[kw]
    397:         bib.push "  #{kw.ljust(12)} = {#{ref}}," if ref
    398:       end
    399:       bib.push "}\n"
    400:       return bib.join("\n")
    401:     end

cell()

Returns reference formatted in the CELL Press style.

      # ref is a Bio::Reference object
      puts ref.cell

        Hoge, J.P. and Fuga, F.B. (2001). Title of the study. Theor. J. Hoge 12, 123-145.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 561
    561:     def cell
    562:       authors = authors_join(' and ')
    563:       "#{authors} (#{@year}). #{@title} #{@journal} #{@volume}, #{pages}."
    564:     end

current()

Returns reference formatted in the Current Biology (current-biology.com) style. (Same as the Genome Biology style)

      # ref is a Bio::Reference object
      puts ref.current

        Hoge JP, Fuga FB: Title of the study. Theor J Hoge 2001, 12:123-145.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 519
    519:     def current
    520:       self.genome_biol
    521:     end

embl()

Returns reference formatted in the EMBL style.

      # ref is a Bio::Reference object
      puts ref.embl

        RP   1-1859
        RX   PUBMED; 1907511.
        RA   Oxtoby E., Dunn M.A., Pancoro A., Hughes M.A.;
        RT   "Nucleotide and derived amino acid sequence of the cyanogenic
        RT   beta-glucosidase (linamarase) from white clover (Trifolium repens L.)";
        RL   Plant Mol. Biol. 17(2):209-219(1991).

[Source]

         # File lib/bio/reference.rb, line 296
    296:     def embl
    297:       r = self
    298:       Bio::Sequence::Format::NucFormatter::Embl.new('').instance_eval {
    299:         reference_format_embl(r)
    300:       }
    301:     end

endnote()

Returns reference formatted in the Endnote style.

      # ref is a Bio::Reference object
      puts ref.endnote

        %0 Journal Article
        %A Hoge, J.P.
        %A Fuga, F.B.
        %D 2001
        %T Title of the study.
        %J Theor. J. Hoge
        %V 12
        %N 3
        %P 123-145
        %M 12345678
        %U http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?cmd=Retrieve&db=PubMed&dopt=Citation&list_uids=12345678
        %X Hoge fuga. ...

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 262
    262:     def endnote
    263:       lines = []
    264:       lines << "%0 Journal Article"
    265:       @authors.each do |author|
    266:         lines << "%A #{author}"
    267:       end
    268:       lines << "%D #{@year}" unless @year.to_s.empty?
    269:       lines << "%T #{@title}" unless @title.empty?
    270:       lines << "%J #{@journal}" unless @journal.empty?
    271:       lines << "%V #{@volume}" unless @volume.to_s.empty?
    272:       lines << "%N #{@issue}" unless @issue.to_s.empty?
    273:       lines << "%P #{@pages}" unless @pages.empty?
    274:       lines << "%M #{@pubmed}" unless @pubmed.to_s.empty?
    275:       u = @url.empty? ? pubmed_url : @url
    276:       lines << "%U #{u}" unless u.empty?
    277:       lines << "%X #{@abstract}" unless @abstract.empty?
    278:       @mesh.each do |term|
    279:         lines << "%K #{term}"
    280:       end
    281:       lines << "%+ #{@affiliations.join(' ')}" unless @affiliations.empty?
    282:       return lines.join("\n")
    283:     end

format(style = nil, *options)

Formats the reference in a given style.

Styles:

1. nil - general
2. endnote - Endnote
3. bibitem - Bibitem (option available)
4. bibtex - BiBTeX (option available)
5. rd - rd (option available)
6. nature - Nature (option available)
7. science - Science
8. genome_biol - Genome Biology
9. genome_res - Genome Research
10. nar - Nucleic Acids Research
11. current - Current Biology
12. trends - Trends in *
13. cell - Cell Press

See individual methods for details. Basic usage is:

      # ref is Bio::Reference object
      # using simplest possible call (for general style)
      puts ref.format

      # output in Nature style
      puts ref.format("nature")      # alternatively, puts ref.nature

      # output in Nature short style (see Bio::Reference#nature)
      puts ref.format("nature",true) # alternatively, puts ref.nature(true)

Arguments:

- (optional) style: String with style identifier
- (optional) options: Options for styles accepting one

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 210
    210:     def format(style = nil, *options)
    211:       case style
    212:       when 'embl'
    213:         return embl
    214:       when 'endnote'
    215:         return endnote
    216:       when 'bibitem'
    217:         return bibitem(*options)
    218:       when 'bibtex'
    219:         return bibtex(*options)
    220:       when 'rd'
    221:         return rd(*options)
    222:       when /^nature$/i
    223:         return nature(*options)
    224:       when /^science$/i
    225:         return science
    226:       when /^genome\s*_*biol/i
    227:         return genome_biol
    228:       when /^genome\s*_*res/i
    229:         return genome_res
    230:       when /^nar$/i
    231:         return nar
    232:       when /^current/i
    233:         return current
    234:       when /^trends/i
    235:         return trends
    236:       when /^cell$/i
    237:         return cell
    238:       else
    239:         return general
    240:       end
    241:     end

general()

Returns reference formatted in a general/generic style.

      # ref is a Bio::Reference object
      puts ref.general

        Hoge, J.P., Fuga, F.B. (2001). "Title of the study." Theor. J. Hoge 12:123-145.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 411
    411:     def general
    412:       authors = @authors.join(', ')
    413:       "#{authors} (#{@year}). \"#{@title}\" #{@journal} #{@volume}:#{@pages}."
    414:     end

genome_biol()

Returns reference formatted in the Genome Biology (genomebiology.com) style.

      # ref is a Bio::Reference object
      puts ref.genome_biol

        Hoge JP, Fuga FB: Title of the study. Theor J Hoge 2001, 12:123-145.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 504
    504:     def genome_biol
    505:       authors = @authors.collect {|name| strip_dots(name)}.join(', ')
    506:       journal = strip_dots(@journal)
    507:       "#{authors}: #{@title} #{journal} #{@year}, #{@volume}:#{@pages}."
    508:     end

genome_res()

Returns reference formatted in the Genome Research (genome.org) style.

      # ref is a Bio::Reference object
      puts ref.genome_res

        Hoge, J.P. and Fuga, F.B. 2001.
          Title of the study. Theor. J. Hoge 12: 123-145.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 533
    533:     def genome_res
    534:       authors = authors_join(' and ')
    535:       "#{authors} #{@year}.\n  #{@title} #{@journal} #{@volume}: #{@pages}."
    536:     end

nar()

Returns reference formatted in the Nucleic Acids Reseach (nar.oxfordjournals.org) style.

      # ref is a Bio::Reference object
      puts ref.nar

        Hoge, J.P. and Fuga, F.B. (2001) Title of the study. Theor. J. Hoge, 12, 123-145.

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 547
    547:     def nar
    548:       authors = authors_join(' and ')
    549:       "#{authors} (#{@year}) #{@title} #{@journal}, #{@volume}, #{@pages}."
    550:     end

nature(short = false)

Formats in the Nature Publishing Group (www.nature.com) style.

      # ref is a Bio::Reference object
      puts ref.nature

        Hoge, J.P. & Fuga, F.B. Title of the study. Theor. J. Hoge 12, 123-145 (2001).

      # optionally, output short version
      puts ref.nature(true)  # or puts ref.nature(short=true)

        Hoge, J.P. & Fuga, F.B. Theor. J. Hoge 12, 123-145 (2001).

Arguments:

- (optional) short: Boolean (default false)

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 460
    460:     def nature(short = false)
    461:       if short
    462:         if @authors.size > 4
    463:           authors = "#{@authors[0]} et al."
    464:         elsif @authors.size == 1
    465:           authors = "#{@authors[0]}"
    466:         else
    467:           authors = authors_join(' & ')
    468:         end
    469:         "#{authors} #{@journal} #{@volume}, #{@pages} (#{@year})."
    470:       else
    471:         authors = authors_join(' & ')
    472:         "#{authors} #{@title} #{@journal} #{@volume}, #{@pages} (#{@year})."
    473:       end
    474:     end

pubmed_url()

Returns a valid URL for pubmed records

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 589
    589:     def pubmed_url
    590:       unless @pubmed.to_s.empty?
    591:         cgi = "http://www.ncbi.nlm.nih.gov/entrez/query.fcgi"
    592:         opts = "cmd=Retrieve&db=PubMed&dopt=Citation&list_uids"
    593:         return "#{cgi}?#{opts}=#{@pubmed}"
    594:       end
    595:       ''
    596:     end

rd(str = nil)

Return reference formatted in the RD style.

      # ref is a Bio::Reference object
      puts ref.rd

        == Title of the study.

        * Hoge, J.P. and Fuga, F.B.

        * Theor. J. Hoge 2001 12:123-145 [PMID:12345678]

        Hoge fuga. ...

An optional string argument can be supplied, but does nothing.

Arguments:

- (optional) str: String (default nil)

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 434
    434:     def rd(str = nil)
    435:       @abstract ||= str
    436:       lines = []
    437:       lines << "== " + @title
    438:       lines << "* " + authors_join(' and ')
    439:       lines << "* #{@journal} #{@year} #{@volume}:#{@pages} [PMID:#{@pubmed}]"
    440:       lines << @abstract
    441:       return lines.join("\n\n")
    442:     end

science()

Returns reference formatted in the Science style.

      # ref is a Bio::Reference object
      puts ref.science

        J.P. Hoge, F.B. Fuga, Theor. J. Hoge 12 123 (2001).

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 485
    485:     def science
    486:       if @authors.size > 4
    487:         authors = rev_name(@authors[0]) + " et al."
    488:       else
    489:         authors = @authors.collect {|name| rev_name(name)}.join(', ')
    490:       end
    491:       page_from, = @pages.split('-')
    492:       "#{authors}, #{@journal} #{@volume} #{page_from} (#{@year})."
    493:     end

trends()

Returns reference formatted in the TRENDS style.

      # ref is a Bio::Reference object
      puts ref.trends

        Hoge, J.P. and Fuga, F.B. (2001) Title of the study. Theor. J. Hoge 12, 123-145

Returns: | String

[Source]

         # File lib/bio/reference.rb, line 575
    575:     def trends
    576:       if @authors.size > 2
    577:         authors = "#{@authors[0]} et al."
    578:       elsif @authors.size == 1
    579:         authors = "#{@authors[0]}"
    580:       else
    581:         authors = authors_join(' and ')
    582:       end
    583:       "#{authors} (#{@year}) #{@title} #{@journal} #{@volume}, #{@pages}"
    584:     end

[Validate]