Class: HTS::Bcf

Inherits:
Hts
  • Object
show all
Includes:
Enumerable
Defined in:
lib/hts/bcf.rb,
lib/hts/bcf/info.rb,
lib/hts/bcf/errors.rb,
lib/hts/bcf/format.rb,
lib/hts/bcf/header.rb,
lib/hts/bcf/record.rb,
lib/hts/bcf/header_record.rb

Overview

A class for working with VCF, BCF files.

Defined Under Namespace

Classes: Error, FieldError, Format, FormatDefinitionError, FormatError, FormatReadError, FormatTypeError, FormatUpdateError, Header, HeaderError, HeaderRecord, IndexError, Info, InfoError, InfoReadError, InfoTypeError, InfoUpdateError, MissingIndexError, OpenError, QueryError, Record, SubsetError, UnknownSampleError, UnsupportedFormatOperationError, UnsupportedInfoOperationError

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Hts

#closed?, #fai=, #file_format, #file_format_version, #rewind, #seek, #set_threads, #struct, #tell, #to_ptr

Constructor Details

#initialize(file_name, mode = "r", index: nil, threads: nil, build_index: false, subset: nil) ⇒ Bcf

Returns a new instance of Bcf.

Raises:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/hts/bcf.rb', line 50

def initialize(file_name, mode = "r", index: nil, threads: nil,
               build_index: false, subset: nil)
  if block_given?
    message = "HTS::Bcf.new() does not take block; Please use HTS::Bcf.open() instead"
    raise message
  end

  # NOTE: Do not check for the existence of local files, since file_names may be remote URIs.

  @file_name  = file_name
  @index_name = index
  @mode       = mode
  @nthreads   = threads
  @hts_file   = LibHTS.hts_open(@file_name, mode)

  raise OpenError, "Failed to open #{@file_name}" if @hts_file.null?

  set_threads(threads) if threads

  raise SubsetError, "Sample subsetting is only available when reading BCF/VCF files" if subset && @mode[0] == "w"

  return if @mode[0] == "w"

  @read_header = Bcf::Header.new(@hts_file)
  @header = subset ? @read_header.subset(subset) : @read_header
  build_index(index) if build_index
  @idx = load_index(index)
  @start_position = tell
end

Instance Attribute Details

#file_name ⇒ Object (readonly)

Returns the value of attribute file_name.



17
18
19
 
# File 'lib/hts/bcf.rb', line 17

def file_name
  @file_name
end

#header ⇒ Object

Returns the value of attribute header.



17
18
19
 
# File 'lib/hts/bcf.rb', line 17

def header
  @header
end

#index_name ⇒ Object (readonly)

Returns the value of attribute index_name.



17
18
19
 
# File 'lib/hts/bcf.rb', line 17

def index_name
  @index_name
end

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



17
18
19
 
# File 'lib/hts/bcf.rb', line 17

def mode
  @mode
end

#nthreads ⇒ Object (readonly)

Returns the value of attribute nthreads.



17
18
19
 
# File 'lib/hts/bcf.rb', line 17

def nthreads
  @nthreads
end

Class Method Details

.build_index(file_name, index_name = nil, min_shift = 14, threads = 0, verbose = true) ⇒ Object 



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/hts/bcf.rb', line 31

def self.build_index(file_name, index_name = nil, min_shift = 14, threads = 0, verbose = true)
  if verbose
    if index_name
      warn "Create index for #{file_name} to #{index_name}"
    else
      warn "Create index for #{file_name}"
    end
  end

  case LibHTS.bcf_index_build3(file_name, index_name, min_shift, threads)
  when 0 # successful
  when -1 then raise IndexError, "Indexing failed for #{file_name}"
  when -2 then raise IndexError, "Opening #{file_name} failed while building the index"
  when -3 then raise IndexError, "#{file_name} is not in an indexable format"
  when -4 then raise IndexError, "Failed to create or save the index for #{file_name}"
  else raise IndexError, "Unknown index build error for #{file_name}"
  end
end

.open(*args, **kw) ⇒ Object 



19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/hts/bcf.rb', line 19

def self.open(*args, **kw)
  file = new(*args, **kw) # do not yield
  return file unless block_given?

  begin
    yield file
  ensure
    file.close
  end
  file
end

Instance Method Details

#<<(var) ⇒ Object 



144
145
146
 
# File 'lib/hts/bcf.rb', line 144

def <<(var)
  write(var)
end

#alt ⇒ Array

Get alt array

Returns:

  • (Array) —

    the alt array



169
 
# File 'lib/hts/bcf.rb', line 169

define_getter :alt

#build_index(index_name = nil, min_shift: 14, verbose: true) ⇒ Object 



80
81
82
83
84
85
 
# File 'lib/hts/bcf.rb', line 80

def build_index(index_name = nil, min_shift: 14, verbose: true)
  check_closed

  self.class.build_index(@file_name, index_name, min_shift, @nthreads || 0, verbose)
  self # for method chaining
end

#chrom ⇒ Array

Get chrom array

Returns:

  • (Array) —

    the chrom array



164
 
# File 'lib/hts/bcf.rb', line 164

define_getter :chrom

#close ⇒ Object 



112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/hts/bcf.rb', line 112

def close
  if @idx && !@idx.null?
    case @index_format
    when :bcf
      LibHTS.hts_idx_destroy(@idx)
    when :tabix
      @idx.close
    end
  end
  @idx = nil
  super
end

#each(copy: false, &block) ⇒ Object 



231
232
233
234
235
236
237
 
# File 'lib/hts/bcf.rb', line 231

def each(copy: false, &block)
  if copy
    each_record_copy(&block)
  else
    each_record_reuse(&block)
  end
end

#each_alt ⇒ Object

Get alt iterator



209
 
# File 'lib/hts/bcf.rb', line 209

define_iterator :alt

#each_chrom ⇒ Object

Get chrom iterator



204
 
# File 'lib/hts/bcf.rb', line 204

define_iterator :chrom

#each_endpos ⇒ Object

Get endpos iterator



206
 
# File 'lib/hts/bcf.rb', line 206

define_iterator :endpos

#each_filter ⇒ Object

Get filter iterator



211
 
# File 'lib/hts/bcf.rb', line 211

define_iterator :filter

#each_format(key) ⇒ Object 



222
223
224
225
226
227
228
229
 
# File 'lib/hts/bcf.rb', line 222

def each_format(key)
  check_closed
  return to_enum(__method__, key) unless block_given?

  each do |r|
    yield r.format(key)
  end
end

#each_id ⇒ Object

Get id iterator



207
 
# File 'lib/hts/bcf.rb', line 207

define_iterator :id

#each_info(key) ⇒ Object 



213
214
215
216
217
218
219
220
 
# File 'lib/hts/bcf.rb', line 213

def each_info(key)
  check_closed
  return to_enum(__method__, key) unless block_given?

  each do |r|
    yield r.info(key)
  end
end

#each_pos ⇒ Object

Get pos iterator



205
 
# File 'lib/hts/bcf.rb', line 205

define_iterator :pos

#each_qual ⇒ Object

Get qual iterator



210
 
# File 'lib/hts/bcf.rb', line 210

define_iterator :qual

#each_ref ⇒ Object

Get ref iterator



208
 
# File 'lib/hts/bcf.rb', line 208

define_iterator :ref

#endpos ⇒ Array

Get endpos array

Returns:

  • (Array) —

    the endpos array



166
 
# File 'lib/hts/bcf.rb', line 166

define_getter :endpos

#filter ⇒ Array

Get filter array

Returns:

  • (Array) —

    the filter array



171
 
# File 'lib/hts/bcf.rb', line 171

define_getter :filter

#format(key = nil) ⇒ Object

Raises:

  • (NotImplementedError) 


187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/hts/bcf.rb', line 187

def format(key = nil)
  check_closed
  position = tell
  raise NotImplementedError unless key

  ary = map { |r| r.format(key) }

  # ary = each_copy.map { |r| r.format }
  # ary = map { |r| r.format.clone }

  seek(position)
  ary
end

#id ⇒ Array

Get id array

Returns:

  • (Array) —

    the id array



167
 
# File 'lib/hts/bcf.rb', line 167

define_getter :id

#index_loaded? ⇒ Boolean

Returns:

  • (Boolean) 


106
107
108
109
110
 
# File 'lib/hts/bcf.rb', line 106

def index_loaded?
  check_closed

  !@idx.null?
end

#info(key = nil) ⇒ Object

Raises:

  • (NotImplementedError) 


173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/hts/bcf.rb', line 173

def info(key = nil)
  check_closed
  position = tell
  raise NotImplementedError unless key

  ary = map { |r| r.info(key) }

  # ary = each_copy.map { |r| r.info }
  # ary = map { |r| r.info.clone }

  seek(position)
  ary
end

#load_index(index_name = nil) ⇒ Object 



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/hts/bcf.rb', line 87

def load_index(index_name = nil)
  check_closed

  if file_format == "vcf"
    @index_format = :tabix
    if index_name
      LibHTS.tbx_index_load2(@file_name, index_name)
    else
      LibHTS.tbx_index_load3(@file_name, nil, 2)
    end
  elsif index_name
    @index_format = :bcf
    LibHTS.bcf_index_load2(@file_name, index_name)
  else
    @index_format = :bcf
    LibHTS.bcf_index_load3(@file_name, nil, 2)
  end
end

#nsamples ⇒ Object 



148
149
150
151
152
 
# File 'lib/hts/bcf.rb', line 148

def nsamples
  check_closed

  header.nsamples
end

#pos ⇒ Array

Get pos array

Returns:

  • (Array) —

    the pos array



165
 
# File 'lib/hts/bcf.rb', line 165

define_getter :pos

#qual ⇒ Array

Get qual array

Returns:

  • (Array) —

    the qual array



170
 
# File 'lib/hts/bcf.rb', line 170

define_getter :qual

#query(region, beg = nil, end_ = nil, copy: false, &block) ⇒ Object

Raises:



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/hts/bcf.rb', line 239

def query(region, beg = nil, end_ = nil, copy: false, &block)
  check_closed

  raise MissingIndexError, "Index file is required to call the query method for #{@file_name}" unless index_loaded?

  case region
  when Array
    raise ArgumentError, "beg and end must not be specified when region is an Array" unless beg.nil? && end_.nil?

    query_regions(region, copy:, &block)
  else
    if beg && end_
      tid = header.name2id(region)
      queryi(tid, beg, end_, copy:, &block)
    elsif beg.nil? && end_.nil?
      querys(region, copy:, &block)
    else
      raise ArgumentError, "beg and end must be specified together"
    end
  end
end

#ref ⇒ Array

Get ref array

Returns:

  • (Array) —

    the ref array



168
 
# File 'lib/hts/bcf.rb', line 168

define_getter :ref

#samples ⇒ Object 



154
155
156
157
158
 
# File 'lib/hts/bcf.rb', line 154

def samples
  check_closed

  header.samples
end

#write(record) ⇒ Object 



136
137
138
139
140
141
142
 
# File 'lib/hts/bcf.rb', line 136

def write(record)
  check_closed

  # record = record.dup
  r = LibHTS.bcf_write(@hts_file, header, record)
  raise "Failed to write record" if r < 0
end

#write_header(header) ⇒ Object 



125
126
127
128
129
130
 
# File 'lib/hts/bcf.rb', line 125

def write_header(header)
  check_closed

  @header = header.dup
  LibHTS.bcf_hdr_write(@hts_file, header)
end