Class: Bio::Reference

Inherits:
Object show all
Defined in:
lib/bio/reference.rb

Overview

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

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Reference) initialize(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



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/bio/reference.rb', line 133

def initialize(hash)
  @authors  = hash['authors'] || [] # [ "Hoge, J.P.", "Fuga, F.B." ]
  @title    = hash['title']   || '' # "Title of the study."
  @journal  = hash['journal'] || '' # "Theor. J. Hoge"
  @volume   = hash['volume']  || '' # 12
  @issue    = hash['issue']   || '' # 3
  @pages    = hash['pages']   || '' # 123-145
  @year     = hash['year']    || '' # 2001
  @pubmed   = hash['pubmed']  || '' # 12345678
  @medline  = hash['medline'] || '' # 98765432
  @doi      = hash['doi']
  @abstract = hash['abstract'] || '' 
  @url      = hash['url']
  @mesh     = hash['mesh'] || []
  @embl_gb_record_number = hash['embl_gb_record_number'] || nil
  @sequence_position = hash['sequence_position'] || nil
  @comments  = hash['comments']
  @affiliations = hash['affiliations'] || []
end

Instance Attribute Details

- (Object) abstract (readonly)

Abstract text in String.



77
78
79
 
# File 'lib/bio/reference.rb', line 77

def abstract
  @abstract
end

- (Object) affiliations (readonly)

Affiliations in an Array.



86
87
88
 
# File 'lib/bio/reference.rb', line 86

def affiliations
  @affiliations
end

- (Object) authors (readonly)

Author names in an Array, [ "Hoge, J.P.", "Fuga, F.B." ].



47
48
49
 
# File 'lib/bio/reference.rb', line 47

def authors
  @authors
end

- (Object) comments (readonly)

Comments for the reference (typically Array of String, or nil)



95
96
97
 
# File 'lib/bio/reference.rb', line 95

def comments
  @comments
end

- (Object) doi (readonly)

DOI identifier (typically String, e.g. "10.1126/science.1110418")



74
75
76
 
# File 'lib/bio/reference.rb', line 74

def doi
  @doi
end

- (Object) embl_gb_record_number (readonly)

Sequence number in EMBL/GenBank records



89
90
91
 
# File 'lib/bio/reference.rb', line 89

def embl_gb_record_number
  @embl_gb_record_number
end

- (Object) issue (readonly)

issue number (typically Fixnum)



59
60
61
 
# File 'lib/bio/reference.rb', line 59

def issue
  @issue
end

- (Object) journal (readonly)

String with journal name



53
54
55
 
# File 'lib/bio/reference.rb', line 53

def journal
  @journal
end

- (Object) medline (readonly)

medline identifier (typically Fixnum)



71
72
73
 
# File 'lib/bio/reference.rb', line 71

def medline
  @medline
end

- (Object) mesh (readonly)

MeSH terms in an Array.



83
84
85
 
# File 'lib/bio/reference.rb', line 83

def mesh
  @mesh
end

- (Object) pages (readonly)

page range (typically String, e.g. "123-145")



62
63
64
 
# File 'lib/bio/reference.rb', line 62

def pages
  @pages
end

- (Object) pubmed (readonly)

pubmed identifier (typically Fixnum)



68
69
70
 
# File 'lib/bio/reference.rb', line 68

def pubmed
  @pubmed
end

- (Object) sequence_position (readonly)

Position in a sequence that this reference refers to



92
93
94
 
# File 'lib/bio/reference.rb', line 92

def sequence_position
  @sequence_position
end

- (Object) title (readonly)

String with title of the study



50
51
52
 
# File 'lib/bio/reference.rb', line 50

def title
  @title
end

- (Object) url (readonly)

An URL String.



80
81
82
 
# File 'lib/bio/reference.rb', line 80

def url
  @url
end

- (Object) volume (readonly)

volume number (typically Fixnum)



56
57
58
 
# File 'lib/bio/reference.rb', line 56

def volume
  @volume
end

- (Object) year (readonly)

year of publication (typically Fixnum)



65
66
67
 
# File 'lib/bio/reference.rb', line 65

def year
  @year
end

Instance Method Details

- (Object) ==(other)

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

Arguments:

  • (required) other: any object

Returns

true or false



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/bio/reference.rb', line 159

def ==(other)
  return true if super(other)
  return false unless other.instance_of?(self.class)
  flag = false
  [ :authors, :title, :journal, :volume, :issue, :pages,
    :year, :pubmed, :medline, :doi, :abstract,
    :url, :mesh, :embl_gb_record_number,
    :sequence_position, :comments, :affiliations ].each do |m|
    begin
      flag = (self.__send__(m) == other.__send__(m))
    rescue NoMethodError, ArgumentError, NameError
      flag = false
    end
    break unless flag
  end
  flag
end

- (Object) 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



316
317
318
319
320
321
322
323
324
325
 
# File 'lib/bio/reference.rb', line 316

def bibitem(item = nil)
  item  = "PMID:#{@pubmed}" unless item
  pages = @pages.sub('-', '--')
  return <<-"END".enum_for(:each_line).collect {|line| line.strip}.join("\n")
    \\bibitem{#{item}}
    #{@authors.join(', ')}
    #{@title},
    {\\em #{@journal}}, #{@volume}(#{@issue}):#{pages}, #{@year}.
  END
end

- (Object) 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



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/bio/reference.rb', line 366

def bibtex(section = nil, label = nil, keywords = {})
  section = "article" unless section
  authors = authors_join(' and ', ' and ')
  thepages = pages.to_s.empty? ? nil : pages.sub(/\-/, '--')
  unless label then
    label = "PMID:#{pubmed}"
  end
  theurl = if !(url.to_s.empty?) then
             url
           elsif pmurl = pubmed_url and !(pmurl.to_s.empty?) then
             pmurl
           else
             nil
           end
  hash = {
    'author'  => authors.empty?    ? nil : authors,
    'title'   => title.to_s.empty? ? nil : title,
    'number'  => issue.to_s.empty? ? nil : issue,
    'pages'   => thepages,
    'url'     => theurl
  }
  keys = %w( author title journal year volume number pages url )
  keys.each do |k|
    hash[k] = self.__send__(k.intern) unless hash.has_key?(k)
  end
  hash.merge!(keywords) { |k, v1, v2| v2.nil? ? v1 : v2 }
  bib = [ "@#{section}{#{label}," ]
  keys.concat((hash.keys - keys).sort)
  keys.each do |kw|
    ref = hash[kw]
    bib.push "  #{kw.ljust(12)} = {#{ref}}," if ref
  end
  bib.push "}\n"
  return bib.join("\n")
end

- (Object) 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



560
561
562
563
 
# File 'lib/bio/reference.rb', line 560

def cell
  authors = authors_join(' and ')
  "#{authors} (#{@year}). #{@title} #{@journal} #{@volume}, #{pages}."
end

- (Object) 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



518
519
520
 
# File 'lib/bio/reference.rb', line 518

def current 
  self.genome_biol
end

- (Object) 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).


296
297
298
299
300
301
 
# File 'lib/bio/reference.rb', line 296

def embl
  r = self
  Bio::Sequence::Format::NucFormatter::Embl.new('').instance_eval {
    reference_format_embl(r)
  }
end

- (Object) 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



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/bio/reference.rb', line 262

def endnote
  lines = []
  lines << "%0 Journal Article"
  @authors.each do |author|
    lines << "%A #{author}"
  end
  lines << "%D #{@year}" unless @year.to_s.empty?
  lines << "%T #{@title}" unless @title.empty?
  lines << "%J #{@journal}" unless @journal.empty?
  lines << "%V #{@volume}" unless @volume.to_s.empty?
  lines << "%N #{@issue}" unless @issue.to_s.empty?
  lines << "%P #{@pages}" unless @pages.empty?
  lines << "%M #{@pubmed}" unless @pubmed.to_s.empty?
  u = @url.to_s.empty? ? pubmed_url : @url
  lines << "%U #{u}" unless u.empty?
  lines << "%X #{@abstract}" unless @abstract.empty?
  @mesh.each do |term|
    lines << "%K #{term}"
  end
  lines << "%+ #{@affiliations.join(' ')}" unless @affiliations.empty?
  return lines.join("\n")
end

- (Object) 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



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/bio/reference.rb', line 210

def format(style = nil, *options)
  case style
  when 'embl'
    return embl
  when 'endnote'
    return endnote
  when 'bibitem'
    return bibitem(*options)
  when 'bibtex'
    return bibtex(*options)
  when 'rd'
    return rd(*options)
  when /^nature$/i
    return nature(*options)
  when /^science$/i
    return science
  when /^genome\s*_*biol/i
    return genome_biol
  when /^genome\s*_*res/i
    return genome_res
  when /^nar$/i
    return nar
  when /^current/i
    return current
  when /^trends/i
    return trends
  when /^cell$/i
    return cell
  else
    return general
  end
end

- (Object) 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



410
411
412
413
 
# File 'lib/bio/reference.rb', line 410

def general
  authors = @authors.join(', ')
  "#{authors} (#{@year}). \"#{@title}\" #{@journal} #{@volume}:#{@pages}."
end

- (Object) 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



503
504
505
506
507
 
# File 'lib/bio/reference.rb', line 503

def genome_biol
  authors = @authors.collect {|name| strip_dots(name)}.join(', ')
  journal = strip_dots(@journal)
  "#{authors}: #{@title} #{journal} #{@year}, #{@volume}:#{@pages}."
end

- (Object) 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



532
533
534
535
 
# File 'lib/bio/reference.rb', line 532

def genome_res
  authors = authors_join(' and ')
  "#{authors} #{@year}.\n  #{@title} #{@journal} #{@volume}: #{@pages}."
end

- (Object) 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



546
547
548
549
 
# File 'lib/bio/reference.rb', line 546

def nar
  authors = authors_join(' and ')
  "#{authors} (#{@year}) #{@title} #{@journal}, #{@volume}, #{@pages}."
end

- (Object) 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



459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/bio/reference.rb', line 459

def nature(short = false)
  if short
    if @authors.size > 4
      authors = "#{@authors[0]} et al."
    elsif @authors.size == 1
      authors = "#{@authors[0]}"
    else
      authors = authors_join(' & ')
    end
    "#{authors} #{@journal} #{@volume}, #{@pages} (#{@year})."
  else
    authors = authors_join(' & ')
    "#{authors} #{@title} #{@journal} #{@volume}, #{@pages} (#{@year})."
  end
end

- (Object) pubmed_url

Returns a valid URL for pubmed records

Returns

String



588
589
590
591
592
593
594
 
# File 'lib/bio/reference.rb', line 588

def pubmed_url
  unless @pubmed.to_s.empty?
    head = "http://www.ncbi.nlm.nih.gov/pubmed"
    return "#{head}/#{@pubmed}"
  end
  ''
end

- (Object) 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



433
434
435
436
437
438
439
440
441
 
# File 'lib/bio/reference.rb', line 433

def rd(str = nil)
  @abstract ||= str
  lines = []
  lines << "== " + @title
  lines << "* " + authors_join(' and ')
  lines << "* #{@journal} #{@year} #{@volume}:#{@pages} [PMID:#{@pubmed}]"
  lines << @abstract
  return lines.join("\n\n")
end

- (Object) 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



484
485
486
487
488
489
490
491
492
 
# File 'lib/bio/reference.rb', line 484

def science
  if @authors.size > 4
    authors = rev_name(@authors[0]) + " et al."
  else
    authors = @authors.collect {|name| rev_name(name)}.join(', ')
  end
  page_from, = @pages.split('-')
  "#{authors}, #{@journal} #{@volume} #{page_from} (#{@year})."
end

- (Object) 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



574
575
576
577
578
579
580
581
582
583
 
# File 'lib/bio/reference.rb', line 574

def trends
  if @authors.size > 2
    authors = "#{@authors[0]} et al."
  elsif @authors.size == 1
    authors = "#{@authors[0]}"
  else
    authors = authors_join(' and ')
  end
  "#{authors} (#{@year}) #{@title} #{@journal} #{@volume}, #{@pages}"
end