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
 
# File 'lib/hts/bam/header.rb', line 46

def initialize(arg = nil)
  case arg
  when Native::SamHeaderHandle
    @native = arg
  when nil
    @native = Native::SamHeaderHandle.create
  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(Native::SamHeaderHandle.parse(text))
end

Instance Method Details

#<<(obj) ⇒ Object

experimental



97
98
99
100
101
102
103
104
105
106
 
# File 'lib/hts/bam/header.rb', line 97

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



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

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

  self
end

#add_rg(id, **tags) ⇒ Object 



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

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 



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

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 



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

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

#count_lines(type) ⇒ Object 



140
141
142
 
# File 'lib/hts/bam/header.rb', line 140

def count_lines(type)
  @native.count_lines(type)
end

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



132
133
134
 
# File 'lib/hts/bam/header.rb', line 132

def delete_line(type, key = nil, value = nil)
  @native.remove_line(type, key, value).zero?
end

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



136
137
138
 
# File 'lib/hts/bam/header.rb', line 136

def delete_tag(type, id_key, id_value, key)
  @native.remove_tag(type, id_key, id_value, key) == 1
end

#find_line(type, key, value) ⇒ Object

experimental



109
110
111
 
# File 'lib/hts/bam/header.rb', line 109

def find_line(type, key, value)
  @native.find_line(type, key, value)
end

#find_line_at(type, pos) ⇒ Object

experimental



118
119
120
 
# File 'lib/hts/bam/header.rb', line 118

def find_line_at(type, pos)
  @native.find_line_at(type, pos)
end

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



113
114
115
 
# File 'lib/hts/bam/header.rb', line 113

def find_tag(type, id_key, id_value, key)
  @native.find_tag(type, id_key, id_value, key)
end

#get_tid(name) ⇒ Object

experimental



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

def get_tid(name)
  name2tid(name)
end

#line_index(type, key) ⇒ Object 



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

def line_index(type, key)
  @native.line_index(type, key)
end

#line_name(type, pos) ⇒ Object 



148
149
150
 
# File 'lib/hts/bam/header.rb', line 148

def line_name(type, pos)
  @native.line_name(type, pos)
end

#remove_line(type, key, value) ⇒ Object

experimental



123
124
125
 
# File 'lib/hts/bam/header.rb', line 123

def remove_line(type, key, value)
  @native.remove_line(type, key, value)
end

#remove_line_at(type, pos) ⇒ Object

experimental



128
129
130
 
# File 'lib/hts/bam/header.rb', line 128

def remove_line_at(type, pos)
  @native.remove_line_at(type, pos)
end

#remove_rg(id) ⇒ Object 



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

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

#remove_sq(name) ⇒ Object 



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

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

#target_count ⇒ Object 



67
68
69
 
# File 'lib/hts/bam/header.rb', line 67

def target_count
  @native.target_count
end

#target_len ⇒ Object 



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

def target_len
  Array.new(target_count) do |i|
    @native.target_length(i)
  end
end

#target_name(tid) ⇒ Object 



71
72
73
 
# File 'lib/hts/bam/header.rb', line 71

def target_name(tid)
  tid2name(tid)
end

#target_names ⇒ Object 



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

def target_names
  Array.new(target_count) do |i|
    @native.target_name(i)
  end
end

#targets ⇒ Object 



59
60
61
62
63
64
65
 
# File 'lib/hts/bam/header.rb', line 59

def targets
  Array.new(target_count) do |i|
    name = @native.target_name(i)
    len = @native.target_length(i)
    { name:, len: }
  end
end

#to_s ⇒ Object 



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

def to_s
  @native.to_s
end

#update_hd(**tags) ⇒ Object 



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

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 



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

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 



174
175
176
177
178
 
# File 'lib/hts/bam/header.rb', line 174

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 



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

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