Class: HTS::Tabix

Inherits:
Hts
  • Object
show all
Includes:
Enumerable
Defined in:
lib/hts/tabix.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file_name, index: nil, threads: nil, build_index: false) ⇒ Tabix

Returns a new instance of Tabix.



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/hts/tabix.rb', line 26

def initialize(file_name, index: nil, threads: nil, build_index: false)
  if block_given?
    message = "HTS::Tabix.new() does not take block; Please use HTS::Tabix.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       = "r"
  @nthreads   = threads
  @index_load_attempted = false
  @native = Native::TabixHandle.open(@file_name)

  set_threads(threads) if threads

  # build_index(index) if build_index
  load_index(index) if index
end

Instance Attribute Details

#file_name ⇒ Object (readonly)

Returns the value of attribute file_name.



12
13
14
 
# File 'lib/hts/tabix.rb', line 12

def file_name
  @file_name
end

#index_name ⇒ Object (readonly)

Returns the value of attribute index_name.



12
13
14
 
# File 'lib/hts/tabix.rb', line 12

def index_name
  @index_name
end

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



12
13
14
 
# File 'lib/hts/tabix.rb', line 12

def mode
  @mode
end

#nthreads ⇒ Object (readonly)

Returns the value of attribute nthreads.



12
13
14
 
# File 'lib/hts/tabix.rb', line 12

def nthreads
  @nthreads
end

Class Method Details

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



14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/hts/tabix.rb', line 14

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

#build_index(index_name = nil, min_shift: 0) ⇒ Object 



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/hts/tabix.rb', line 47

def build_index(index_name = nil, min_shift: 0)
  check_closed

  if index_name
    warn "Create index for #{@file_name} to #{index_name}"
    case Native::TabixHandle.build(@file_name, index_name, min_shift)
    when 0 # successful
    when -1 then raise "general failure"
    when -2 then raise "compression not BGZF"
    else raise "unknown error"
    end
  else
    warn "Create index for #{@file_name}"
    case Native::TabixHandle.build(@file_name, nil, min_shift)
    when 0 # successful
    when -1 then raise "general failure"
    when -2 then raise "compression not BGZF"
    else raise "unknown error"
    end
  end
  @index_name = index_name
  @index_load_attempted = false
  self # for method chaining
end

#close ⇒ Object 



139
140
141
142
143
 
# File 'lib/hts/tabix.rb', line 139

def close
  return if closed?

  @native.close
end

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


145
146
147
 
# File 'lib/hts/tabix.rb', line 145

def closed?
  @native.nil? || @native.closed?
end

#each_fields(region, start = nil, end_ = nil, &block) ⇒ Object

Explicit name for the legacy split-fields API.



103
104
105
 
# File 'lib/hts/tabix.rb', line 103

def each_fields(region, start = nil, end_ = nil, &block)
  query_with_mode(region, start, end_, :fields, nil, &block)
end

#each_line(region, start = nil, end_ = nil, &block) ⇒ Object

Iterate raw rows, allocating one String per row and no field Array.



108
109
110
 
# File 'lib/hts/tabix.rb', line 108

def each_line(region, start = nil, end_ = nil, &block)
  query_with_mode(region, start, end_, :line, nil, &block)
end

#each_selected_fields(region, *columns, &block) ⇒ Object

Extract only requested zero-based columns without materializing unused field strings. This Ruby implementation scans tab delimiters once.

Raises:

  • (ArgumentError) 


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

def each_selected_fields(region, *columns, &block)
  raise ArgumentError, "at least one column index is required" if columns.empty?

  normalized = columns.map do |column|
    index = Integer(column)
    raise ArgumentError, "column indices must be non-negative" if index.negative?

    index
  end
  query_with_mode(region, nil, nil, :selected, normalized, &block)
end

#file_format ⇒ Object 



149
 
# File 'lib/hts/tabix.rb', line 149

def file_format = @native.file_format

#file_format_version ⇒ Object 



150
 
# File 'lib/hts/tabix.rb', line 150

def file_format_version = @native.file_format_version

#index_loaded? ⇒ Boolean

Returns:

  • (Boolean) 


79
80
81
82
 
# File 'lib/hts/tabix.rb', line 79

def index_loaded?
  check_closed
  @native.index_loaded?
end

#load_index(index_name = nil) ⇒ Object 



72
73
74
75
76
77
 
# File 'lib/hts/tabix.rb', line 72

def load_index(index_name = nil)
  check_closed
  @index_name = index_name
  @index_load_attempted = true
  @native.load_index(index_name)
end

#name2id(name) ⇒ Object 



84
85
86
87
88
89
 
# File 'lib/hts/tabix.rb', line 84

def name2id(name)
  check_closed
  raise "Index file is required to call the name2id method." unless ensure_index_loaded

  @native.name2id(name)
end

#query(region, start = nil, end_ = nil, &block) ⇒ Object 



98
99
100
 
# File 'lib/hts/tabix.rb', line 98

def query(region, start = nil, end_ = nil, &block)
  query_with_mode(region, start, end_, :fields, nil, &block)
end

#query_with_mode(region, start, end_, mode, columns, &block) ⇒ Object 



126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/hts/tabix.rb', line 126

def query_with_mode(region, start, end_, mode, columns, &block)
  check_closed
  raise "Index file is required to call the query method." unless ensure_index_loaded

  if start && end_
    queryi(name2id(region), start, end_, mode, columns, &block)
  elsif start.nil? && end_.nil?
    querys(region, mode, columns, &block)
  else
    raise ArgumentError, "start and end must be specified together"
  end
end

#seqnames ⇒ Object 



91
92
93
94
95
96
 
# File 'lib/hts/tabix.rb', line 91

def seqnames
  check_closed
  raise "Index file is required to call the seqnames method." unless ensure_index_loaded

  @native.seqnames
end

#set_threads(n = nil) ⇒ Object

Raises:

  • (TypeError) 


152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/hts/tabix.rb', line 152

def set_threads(n = nil)
  if n.nil?
    require "etc"
    n = [Etc.nprocessors - 1, 1].max
  end
  raise TypeError unless n.is_a?(Integer)
  raise ArgumentError, "Number of threads must be positive" if n < 1
  raise "Failed to set number of threads: #{n}" if @native.set_threads(n).negative?

  @nthreads = n
  self
end