Class: HTS::Bam::Header

Inherits:
Object
  • Object
show all
Defined in:
lib/hts/bam/header.rb

Overview

A class for working with alignment header.

Constant Summary collapse

HD_TAG_MAP = 
{
  version: "VN",
  sort_order: "SO",
  group_order: "GO",
  subsorting: "SS"
}.freeze
SQ_TAG_MAP = 
{
  name: "SN",
  length: "LN",
  assembly: "AS",
  md5: "M5",
  species: "SP",
  uri: "UR",
  alt_names: "AN"
}.freeze
RG_TAG_MAP = 
{
  id: "ID",
  sample: "SM",
  library: "LB",
  platform: "PL",
  platform_unit: "PU",
  center: "CN",
  description: "DS",
  date: "DT",
  flow_order: "FO",
  key_sequence: "KS",
  program: "PG",
  insert_size: "PI",
  molecule_topology: "PM"
}.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(arg = nil) {|_self| ... } ⇒ Header

Returns a new instance of Header.

Yields:

  • (_self)

Yield Parameters:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/hts/bam/header.rb', line 46

def initialize(arg = nil)
  case arg
  when LibHTS::HtsFile
    @sam_hdr = LibHTS.sam_hdr_read(arg)
  when LibHTS::SamHdr
    @sam_hdr = arg
  when nil
    @sam_hdr = LibHTS.sam_hdr_init
  else
    raise TypeError, "Invalid argument"
  end

  yield self if block_given?
end

Class Method Details

.parse(text) ⇒ Object 



42
43
44
 
# File 'lib/hts/bam/header.rb', line 42

def self.parse(text)
  new(LibHTS.sam_hdr_parse(text.size, text))
end

Instance Method Details

#<<(obj) ⇒ Object

experimental



108
109
110
111
112
113
114
115
116
117
 
# File 'lib/hts/bam/header.rb', line 108

def <<(obj)
  case obj
  when Array, Hash
    args = obj.flatten(-1).map { |i| i.to_a if i.is_a?(Hash) }
    add_line(*args)
  else
    add_lines(obj.to_s)
  end
  self
end

#add_pg(program_name, **options) ⇒ Integer

Add a @PG (program) line to the header This is a convenience wrapper around sam_hdr_add_pg that automatically:

  • Generates a unique ID if the specified one clashes

  • Manages PP (previous program) chains automatically

Examples:

header.add_pg("bwa", VN: "0.7.17", CL: "bwa mem ref.fa read.fq")
header.add_pg("samtools", VN: "1.15", PP: "bwa")

Parameters:

  • program_name (String) —

    Name of the program

  • options (Hash) —

    Key-value pairs for @PG tags (ID, PN, VN, CL, PP, etc.)

Returns:

  • (Integer) —

    0 on success, -1 on failure



242
243
244
245
246
247
248
 
# File 'lib/hts/bam/header.rb', line 242

def add_pg(program_name, **options)
  line = build_pg_line(program_name.to_s, options)
  result = LibHTS.sam_hdr_add_lines(@sam_hdr, line, line.bytesize)
  raise "Failed to add @PG line" if result < 0

  self
end

#add_rg(id, **tags) ⇒ Object 



213
214
215
216
217
218
 
# File 'lib/hts/bam/header.rb', line 213

def add_rg(id, **tags)
  pairs = [["ID", id.to_s]]
  pairs.concat normalize_rg_tags(tags)
  add_structured_sam_line("RG", pairs, %w[ID SM LB PL PU CN DS DT FO KS PG PI PM])
  self
end

#add_sq(name, length:, **tags) ⇒ Object 



196
197
198
199
200
201
 
# File 'lib/hts/bam/header.rb', line 196

def add_sq(name, length:, **tags)
  pairs = [["SN", name.to_s], ["LN", length.to_s]]
  pairs.concat normalize_sq_tags(tags)
  add_structured_sam_line("SQ", pairs, %w[SN LN AS M5 SP UR AN])
  self
end

#append(line) ⇒ Object 



102
103
104
105
 
# File 'lib/hts/bam/header.rb', line 102

def append(line)
  add_lines(ensure_newline(line.to_s))
  self
end

#count_lines(type) ⇒ Object 



169
170
171
 
# File 'lib/hts/bam/header.rb', line 169

def count_lines(type)
  LibHTS.sam_hdr_count_lines(@sam_hdr, type)
end

#delete_line(type, key = nil, value = nil) ⇒ Object 



161
162
163
 
# File 'lib/hts/bam/header.rb', line 161

def delete_line(type, key = nil, value = nil)
  LibHTS.sam_hdr_remove_line_id(@sam_hdr, type, key, value).zero?
end

#delete_tag(type, id_key, id_value, key) ⇒ Object 



165
166
167
 
# File 'lib/hts/bam/header.rb', line 165

def delete_tag(type, id_key, id_value, key)
  LibHTS.sam_hdr_remove_tag_id(@sam_hdr, type, id_key, id_value, key) == 1
end

#find_line(type, key, value) ⇒ Object

experimental



120
121
122
123
124
125
126
127
128
 
# File 'lib/hts/bam/header.rb', line 120

def find_line(type, key, value)
  ks = LibHTS::KString.new
  begin
    r = LibHTS.sam_hdr_find_line_id(@sam_hdr, type, key, value, ks)
    r == 0 ? ks.read_string_copy : nil
  ensure
    ks.free_buffer
  end
end

#find_line_at(type, pos) ⇒ Object

experimental



141
142
143
144
145
146
147
148
149
 
# File 'lib/hts/bam/header.rb', line 141

def find_line_at(type, pos)
  ks = LibHTS::KString.new
  begin
    r = LibHTS.sam_hdr_find_line_pos(@sam_hdr, type, pos, ks)
    r == 0 ? ks.read_string_copy : nil
  ensure
    ks.free_buffer
  end
end

#find_tag(type, id_key, id_value, key) ⇒ Object 



130
131
132
133
134
135
136
137
138
 
# File 'lib/hts/bam/header.rb', line 130

def find_tag(type, id_key, id_value, key)
  ks = LibHTS::KString.new
  begin
    r = LibHTS.sam_hdr_find_tag_id(@sam_hdr, type, id_key, id_value, key, ks)
    r == 0 ? ks.read_string_copy : nil
  ensure
    ks.free_buffer
  end
end

#get_tid(name) ⇒ Object

experimental



186
187
188
 
# File 'lib/hts/bam/header.rb', line 186

def get_tid(name)
  name2tid(name)
end

#line_index(type, key) ⇒ Object 



173
174
175
 
# File 'lib/hts/bam/header.rb', line 173

def line_index(type, key)
  LibHTS.sam_hdr_line_index(@sam_hdr, type, key)
end

#line_name(type, pos) ⇒ Object 



177
178
179
 
# File 'lib/hts/bam/header.rb', line 177

def line_name(type, pos)
  LibHTS.sam_hdr_line_name(@sam_hdr, type, pos)
end

#remove_line(type, key, value) ⇒ Object

experimental



152
153
154
 
# File 'lib/hts/bam/header.rb', line 152

def remove_line(type, key, value)
  LibHTS.sam_hdr_remove_line_id(@sam_hdr, type, key, value)
end

#remove_line_at(type, pos) ⇒ Object

experimental



157
158
159
 
# File 'lib/hts/bam/header.rb', line 157

def remove_line_at(type, pos)
  LibHTS.sam_hdr_remove_line_pos(@sam_hdr, type, pos)
end

#remove_rg(id) ⇒ Object 



226
227
228
 
# File 'lib/hts/bam/header.rb', line 226

def remove_rg(id)
  delete_line("RG", "ID", id.to_s)
end

#remove_sq(name) ⇒ Object 



209
210
211
 
# File 'lib/hts/bam/header.rb', line 209

def remove_sq(name)
  delete_line("SQ", "SN", name.to_s)
end

#struct ⇒ Object 



61
62
63
 
# File 'lib/hts/bam/header.rb', line 61

def struct
  @sam_hdr
end

#target_count ⇒ Object 



77
78
79
80
 
# File 'lib/hts/bam/header.rb', line 77

def target_count
  # FIXME: sam_hdr_nref
  @sam_hdr[:n_targets]
end

#target_len ⇒ Object 



92
93
94
95
96
 
# File 'lib/hts/bam/header.rb', line 92

def target_len
  Array.new(target_count) do |i|
    LibHTS.sam_hdr_tid2len(@sam_hdr, i)
  end
end

#target_name(tid) ⇒ Object 



82
83
84
 
# File 'lib/hts/bam/header.rb', line 82

def target_name(tid)
  tid2name(tid)
end

#target_names ⇒ Object 



86
87
88
89
90
 
# File 'lib/hts/bam/header.rb', line 86

def target_names
  Array.new(target_count) do |i|
    LibHTS.sam_hdr_tid2name(@sam_hdr, i)
  end
end

#targets ⇒ Object 



69
70
71
72
73
74
75
 
# File 'lib/hts/bam/header.rb', line 69

def targets
  Array.new(target_count) do |i|
    name = LibHTS.sam_hdr_tid2name(@sam_hdr, i)
    len = LibHTS.sam_hdr_tid2len(@sam_hdr, i)
    { name:, len: }
  end
end

#to_ptr ⇒ Object 



65
66
67
 
# File 'lib/hts/bam/header.rb', line 65

def to_ptr
  @sam_hdr.to_ptr
end

#to_s ⇒ Object 



181
182
183
 
# File 'lib/hts/bam/header.rb', line 181

def to_s
  LibHTS.sam_hdr_str(@sam_hdr)
end

#update_hd(**tags) ⇒ Object 



190
191
192
193
194
 
# File 'lib/hts/bam/header.rb', line 190

def update_hd(**tags)
  pairs = merge_sam_pairs(find_line_pairs("HD", nil, nil), normalize_hd_tags(tags))
  replace_sam_line("HD", nil, nil, pairs, %w[VN SO GO SS])
  self
end

#update_rg(id, **tags) ⇒ Object 



220
221
222
223
224
 
# File 'lib/hts/bam/header.rb', line 220

def update_rg(id, **tags)
  pairs = merge_identified_sam_line("RG", "ID", id.to_s, normalize_rg_tags(tags), protected_keys: ["ID"])
  replace_sam_line("RG", "ID", id.to_s, pairs, %w[ID SM LB PL PU CN DS DT FO KS PG PI PM])
  self
end

#update_sq(name, **tags) ⇒ Object 



203
204
205
206
207
 
# File 'lib/hts/bam/header.rb', line 203

def update_sq(name, **tags)
  pairs = merge_identified_sam_line("SQ", "SN", name.to_s, normalize_sq_tags(tags), protected_keys: ["SN"])
  replace_sam_line("SQ", "SN", name.to_s, pairs, %w[SN LN AS M5 SP UR AN])
  self
end

#write ⇒ Object 



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

def write(...)
  add_lines(...)
end