Class: IGV

Inherits:
Object
  • Object
show all
Defined in:
lib/igv.rb,
lib/igv/version.rb

Overview

The Integrative Genomics Viewer (IGV) Ruby client. Provides a Ruby interface to control IGV via its batch command protocol.

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION =
'0.0.10'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd) ⇒ IGV

Create IGV client object.

Parameters:

  • host (String) (defaults to: '127.0.0.1')

    Hostname or IP address of IGV server.

  • port (Integer) (defaults to: 60_151)

    Port number of IGV server.

  • snapshot_dir (String) (defaults to: Dir.pwd)

    Directory path to save snapshots.

Raises:

  • (ArgumentError)


23
24
25
26
27
28
29
30
# File 'lib/igv.rb', line 23

def initialize(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd)
  raise ArgumentError, 'IGV#initialize does not accept a block.' if block_given?

  @host = host
  @port = port
  @snapshot_dir = File.expand_path(snapshot_dir)
  @history = []
end

Instance Attribute Details

#historyObject (readonly)

Returns the value of attribute history.



15
16
17
# File 'lib/igv.rb', line 15

def history
  @history
end

#hostObject (readonly)

Returns the value of attribute host.



15
16
17
# File 'lib/igv.rb', line 15

def host
  @host
end

#portObject (readonly)

Returns the value of attribute port.



15
16
17
# File 'lib/igv.rb', line 15

def port
  @port
end

Class Method Details

.open(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd) {|IGV| ... } ⇒ IGV

Create IGV object and connect to IGV server. This method accepts a block.

Parameters:

  • host (String) (defaults to: '127.0.0.1')

    Hostname or IP address of IGV server.

  • port (Integer) (defaults to: 60_151)

    Port number of IGV server.

  • snapshot_dir (String) (defaults to: Dir.pwd)

    Directory path to save snapshots.

Yields:

  • (IGV)

    IGV client object.

Returns:

  • (IGV)

    IGV client object.



40
41
42
43
44
45
46
47
48
49
50
51
# File 'lib/igv.rb', line 40

def self.open(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd)
  igv = new(host: host, port: port, snapshot_dir: snapshot_dir)
  igv.connect
  return igv unless block_given?

  begin
    yield igv
  ensure
    @socket&.close
  end
  igv
end

.start(port: 60_151, command: 'igv', snapshot_dir: Dir.pwd) ⇒ IGV

Note:

This will spawn a new IGV process and connect to it.

Launch IGV from Ruby script.

Parameters:

  • port (Integer) (defaults to: 60_151)

    Port number.

  • command (String) (defaults to: 'igv')

    Command to launch IGV.

  • snapshot_dir (String) (defaults to: Dir.pwd)

    Directory path to save snapshots.

Returns:

  • (IGV)

    IGV client object.



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
# File 'lib/igv.rb', line 68

def self.start(port: 60_151, command: 'igv', snapshot_dir: Dir.pwd)
  case port_open?(port)
  when nil   then warn "[ruby-igv] Cannot tell if port #{port} is open"
  when true  then raise("Port #{port} is already in use")
  when false then warn "[ruby-igv] Port #{port} is available"
  else raise "Unexpected return value from port_open?(#{port})"
  end
  r, w = IO.pipe
  pid_igv = spawn(command, '-p', port.to_s, pgroup: true, out: w, err: w)
  pgid_igv = Process.getpgid(pid_igv)
  Process.detach(pid_igv)
  puts "\e[33m"
  while (line = r.gets.chomp("\n"))
    puts line
    break if line.include? "Listening on port #{port}"
  end
  puts "\e[0m"
  igv = self.open(port: port, snapshot_dir: snapshot_dir)
  igv.instance_variable_set(:@pgid_igv, pgid_igv)
  igv
end

Instance Method Details

#clearself

Note:

IGV Batch command: clear

Clear all loaded tracks and data.

Examples:

igv.clear

Returns:

  • (self)

    Returns self for method chaining.



329
330
331
332
# File 'lib/igv.rb', line 329

def clear
  send :clear
  self
end

#clear_access_tokensString

Note:

IGV Batch command: clearAccessTokens

Clears all access tokens.

Examples:

igv.clear_access_tokens

Returns:

  • (String)

    IGV response.



630
631
632
# File 'lib/igv.rb', line 630

def clear_access_tokens
  send :clearAccessTokens
end

#closenil

Close the socket. This does not exit IGV.

Returns:

  • (nil)

    Closes the socket and returns nil.



121
122
123
124
# File 'lib/igv.rb', line 121

def close
  @socket&.close
  nil
end

#closed?Boolean

Check if the socket is closed.

Returns:

  • (Boolean)


128
129
130
131
132
# File 'lib/igv.rb', line 128

def closed?
  return true if @socket.nil?

  @socket.closed?
end

#collapse(track = nil) ⇒ String

Note:

IGV Batch command: collapse

Collapse a given track. If not specified, collapses all tracks.

Examples:

igv.collapse
igv.collapse("track1")

Parameters:

  • track (String, nil) (defaults to: nil)

    Track name (optional).

Returns:

  • (String)

    IGV response.



284
285
286
# File 'lib/igv.rb', line 284

def collapse(track = nil)
  send :collapse, track
end

#color_by(option, tag) ⇒ String

Note:

IGV Batch command: colorBy

Set the “color by” option for alignment tracks.

Examples:

igv.color_by("SAMPLE")
igv.color_by("TAG", "NM")

Parameters:

  • option (String)

    Color by option (e.g. “SAMPLE”, “READ_GROUP”, “TAG”, …).

  • tag (String, nil)

    Tag name (required for option “TAG”).

Returns:

  • (String)

    IGV response.



562
563
564
# File 'lib/igv.rb', line 562

def color_by(option, tag)
  send :colorBy, option, tag
end

#commandsObject

Open IGV batch command documentation in the browser.



171
172
173
174
# File 'lib/igv.rb', line 171

def commands
  require 'launchy'
  Launchy.open('https://igv.org/doc/desktop/#UserGuide/tools/batch/#script-commands')
end

#connect(host2 = @host, port2 = @port, connect_timeout: nil) ⇒ self

Connect to IGV server.

Parameters:

  • host2 (String) (defaults to: @host)

    Hostname or IP address.

  • port2 (Integer) (defaults to: @port)

    Port number.

  • connect_timeout (Integer, nil) (defaults to: nil)

    Timeout in seconds.

Returns:

  • (self)

    Returns self for method chaining.



113
114
115
116
117
# File 'lib/igv.rb', line 113

def connect(host2 = @host, port2 = @port, connect_timeout: nil)
  @socket&.close
  @socket = Socket.tcp(host2, port2, connect_timeout: connect_timeout)
  self
end

#echo(param = nil) ⇒ String

Note:

IGV Batch command: echo

Write the value of “param” back to the response.

Examples:

igv.echo("Hello!") #=> "Hello!"

Parameters:

  • param (String, nil) (defaults to: nil)

    The parameter to echo.

Returns:

  • (String)

    The value of “param”. If param is not specified, “echo”.



183
184
185
# File 'lib/igv.rb', line 183

def echo(param = nil)
  send :echo, param
end

#exitnil Also known as: quit

Note:

IGV Batch command: exit

Exit (close) the IGV application and close the socket.

Examples:

igv.exit

Returns:

  • (nil)

    Exits IGV and closes the socket.



340
341
342
343
344
# File 'lib/igv.rb', line 340

def exit
  send :exit
  @socket.close
  nil
end

#expand(track = nil) ⇒ String

Note:

IGV Batch command: expand

Expand a given track. If not specified, expands all tracks.

Examples:

igv.expand
igv.expand("track1")

Parameters:

  • track (String, nil) (defaults to: nil)

    Track name (optional).

Returns:

  • (String)

    IGV response.



272
273
274
# File 'lib/igv.rb', line 272

def expand(track = nil)
  send :expand, track
end

#genome(name_or_path) ⇒ String

Note:

IGV Batch command: genome

Select a genome by id, or load a genome (or indexed fasta) from the supplied path.

Examples:

igv.genome("hg19")
igv.genome("/path/to/genome.fa")

Parameters:

  • name_or_path (String)

    Genome id (e.g. “hg19”) or path to fasta/indexed genome.

Returns:

  • (String)

    IGV response.



195
196
197
198
199
200
201
202
# File 'lib/igv.rb', line 195

def genome(name_or_path)
  path = File.expand_path(name_or_path)
  if File.exist?(path)
    send :genome, path
  else
    send :genome, name_or_path
  end
end

#goto(position) ⇒ String Also known as: go

Note:

IGV Batch command: goto

Go to the specified location or list of loci.

Examples:

igv.goto("chr1:1000-2000")

Parameters:

  • position (String)

    Locus or list of loci (e.g. “chr1:1000-2000”).

Returns:

  • (String)

    IGV response.



232
233
234
# File 'lib/igv.rb', line 232

def goto(position)
  send :goto, position
end

#group(option, tag) ⇒ String

Note:

IGV Batch command: group

Group alignments by the specified option.

Examples:

igv.group("SAMPLE")
igv.group("TAG", "NM")

Parameters:

  • option (String)

    Group option (e.g. “SAMPLE”, “READ_GROUP”, “TAG”, …).

  • tag (String, nil)

    Tag name or position (required for option “TAG”).

Returns:

  • (String)

    IGV response.



575
576
577
# File 'lib/igv.rb', line 575

def group(option, tag)
  send :group, option, tag
end

#killnil

Note:

Only works for IGV processes started by IGV.start.

Kill IGV process by process group id.

Returns:

  • (nil)

    Kills the IGV process if started by this client, otherwise does nothing.



94
95
96
97
98
99
100
101
102
103
104
105
# File 'lib/igv.rb', line 94

def kill
  if instance_variable_defined?(:@pgid_igv)
    warn '[ruby-igv] This method kills the process with the group ID specified at startup. Please use exit or quit if possible.'
  else
    warn '[ruby-igv] The kill method terminates only IGV commands invoked by the start method. Otherwise, use exit or quit.'
    return nil
  end
  pgid = @pgid_igv
  Process.kill(:TERM, -pgid)
  close
  nil
end

#load(path_or_url, index: nil) ⇒ String

Note:

IGV Batch command: load

Load a data or session file by specifying a full path to a local file or a URL.

Examples:

igv.load("http://example.com/data.bam")
igv.load("/path/to/data.bam", index: "/path/to/data.bai")

Parameters:

  • path_or_url (String)

    Path to a local file or a URL.

  • index (String, nil) (defaults to: nil)

    Optional index file path.

Returns:

  • (String)

    IGV response.



213
214
215
216
217
218
219
220
221
222
223
# File 'lib/igv.rb', line 213

def load(path_or_url, index: nil)
  path_or_url = if URI.parse(path_or_url).scheme
                  path_or_url
                else
                  File.expand_path(path_or_url)
                end
  index = "index=#{index}" if index
  send :load, path_or_url, index
rescue URI::InvalidURIError
  raise ArgumentError, "Invalid URI or file path: #{path_or_url}"
end

#max_panel_height(height) ⇒ String

Note:

IGV Batch command: maxPanelHeight

Set the number of vertical pixels (height) of each panel to include in image.

Examples:

igv.max_panel_height(2000)

Parameters:

  • height (Integer)

    Height in pixels.

Returns:

  • (String)

    IGV response.



549
550
551
# File 'lib/igv.rb', line 549

def max_panel_height(height)
  send :maxPanelHeight, height
end

#newself

Note:

IGV Batch command: new

Create a new session. Unloads all tracks except the default genome annotations.

Examples:

igv.new

Returns:

  • (self)

    Returns self for method chaining.



318
319
320
321
# File 'lib/igv.rb', line 318

def new
  send :new
  self
end

#overlay(overlaid_track, *tracks) ⇒ String

Note:

IGV Batch command: overlay

Overlay a list of tracks.

Examples:

igv.overlay("track1", "track2", "track3")

Parameters:

  • overlaid_track (String)

    The track to overlay.

  • tracks (Array<String>)

    List of tracks to overlay.

Returns:

  • (String)

    IGV response.



587
588
589
# File 'lib/igv.rb', line 587

def overlay(overlaid_track, *tracks)
  send :overlay, overlaid_track, *tracks
end

#preferences(key, value) ⇒ String

Note:

IGV Batch command: preference

Temporarily set the preference named key to the specified value.

Examples:

igv.preferences("SAM.READ_GROUP_COLOR", "sample")

Parameters:

  • key (String)

    Preference key.

  • value (String)

    Preference value.

Returns:

  • (String)

    IGV response.

See Also:



423
424
425
# File 'lib/igv.rb', line 423

def preferences(key, value)
  send :preferences, key, value
end

#region(chr, start, end_) ⇒ String

Note:

IGV Batch command: region

Define a region of interest bounded by the two loci.

Examples:

igv.region("chr1", 100, 200)

Parameters:

  • chr (String)

    Chromosome name.

  • start (Integer)

    Start position.

  • end_ (Integer)

    End position.

Returns:

  • (String)

    IGV response.



246
247
248
# File 'lib/igv.rb', line 246

def region(chr, start, end_)
  send :region, chr, start, end_
end

#save_session(file_path) ⇒ String

Note:

IGV Batch command: saveSession

Save the current session.

Examples:

igv.save_session("session.xml")

Parameters:

  • file_path (String)

    Path to the session file.

Returns:

  • (String)

    IGV response.



440
441
442
443
# File 'lib/igv.rb', line 440

def save_session(file_path)
  file_path = File.expand_path(file_path)
  send :saveSession, file_path
end

#scroll_to_topString

Note:

IGV Batch command: scrollToTop

Scroll all panels to the top of the view.

Examples:

igv.scroll_to_top

Returns:

  • (String)

    IGV response.



597
598
599
# File 'lib/igv.rb', line 597

def scroll_to_top
  send :scrollToTop
end

#send(*cmds) ⇒ String

Send batch commands to IGV.

Examples:

igv.send("goto", "chr1:1000-2000")

Parameters:

  • cmds (Array<String, Symbol, Numeric>)

    Batch commands.

Returns:

  • (String)

    Response from IGV.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
# File 'lib/igv.rb', line 140

def send(*cmds)
  cmd = \
    cmds
    .compact
    .map do |cm|
      case cm
      when String, Symbol, Numeric          then cm.to_s
      when ->(c) { c.respond_to?(:to_str) } then cm.to_str
      else raise ArgumentError, "#{cm.inspect} is not a string"
      end.strip.encode(Encoding::UTF_8)
    end
    .join(' ')
  @history << cmd
  @socket.puts(cmd)
  @socket.gets&.chomp("\n")
end

#separate(overlaid_track_name) ⇒ String

Note:

IGV Batch command: separate

Separate an overlaid track into its constituitive tracks.

Examples:

igv.separate("track1")

Parameters:

  • overlaid_track_name (String)

    The name of the overlaid track to separate.

Returns:

  • (String)

    IGV response.



608
609
610
# File 'lib/igv.rb', line 608

def separate(overlaid_track_name)
  send :separate, overlaid_track_name
end

#set(cmd, *params) ⇒ String

Syntactic sugar for IGV commands that begin with set.

Examples:

igv.set :SleepInterval, 100
igv.send "setSleepInterval", 100 # same as above

Parameters:

  • cmd (String, Symbol)

    Batch command name (without “set” prefix).

  • params (Array<String, Symbol, Numeric>)

    Parameters for the command.

Returns:

  • (String)

    Response from IGV.



165
166
167
168
# File 'lib/igv.rb', line 165

def set(cmd, *params)
  cmd = "set#{cmd}"
  send(cmd, *params)
end

#set_access_token(token, host = nil) ⇒ String

Note:

IGV Batch command: setAccessToken

Set an access token to be used in an Authorization header for all requests to host.

Examples:

igv.set_access_token("mytoken", "example.com")

Parameters:

  • token (String)

    The access token.

  • host (String, nil) (defaults to: nil)

    The host to use the token for (optional).

Returns:

  • (String)

    IGV response.



620
621
622
# File 'lib/igv.rb', line 620

def set_access_token(token, host = nil)
  send :setAccessToken, token, host
end

#set_alt_color(color, track) ⇒ String

Note:

IGV Batch command: setAltColor

Set the track “altColor”, used for negative values in a wig track or negative strand features.

Examples:

igv.set_alt_color("255,0,0", "track1")

Parameters:

  • color (String)

    Color string (e.g. “255,0,0” or “FF0000”).

  • track (String)

    Track name.

Returns:

  • (String)

    IGV response.



453
454
455
# File 'lib/igv.rb', line 453

def set_alt_color(color, track)
  send :setAltColor, color, track
end

#set_color(color, track) ⇒ String

Note:

IGV Batch command: setColor

Set the track color.

Examples:

igv.set_color("FF0000", "track1")

Parameters:

  • color (String)

    Color string (e.g. “255,0,0” or “FF0000”).

  • track (String)

    Track name.

Returns:

  • (String)

    IGV response.



465
466
467
# File 'lib/igv.rb', line 465

def set_color(color, track)
  send :setColor, color, track
end

#set_data_range(range, track) ⇒ String

Note:

IGV Batch command: setDataRange

Set the data range (scale) for all numeric tracks, or a specific track.

Examples:

igv.set_data_range("0,100", "track1")

Parameters:

  • range (String)

    Range string (e.g. “0,100” or “auto”).

  • track (String)

    Track name.

Returns:

  • (String)

    IGV response.



477
478
479
# File 'lib/igv.rb', line 477

def set_data_range(range, track)
  send :setDataRange, range, track
end

#set_log_scale(bool, track) ⇒ String

Note:

IGV Batch command: setLogScale

Set the data scale to log (true) or linear (false).

Examples:

igv.set_log_scale(true, "track1")

Parameters:

  • bool (Boolean)

    true for log scale, false for linear.

  • track (String)

    Track name (optional).

Returns:

  • (String)

    IGV response.



489
490
491
492
493
# File 'lib/igv.rb', line 489

def set_log_scale(bool, track)
  bool = 'true' if bool == true
  bool = 'false' if bool == false
  send :setLogScale, bool, track
end

#set_sequence_show_translation(bool) ⇒ String

Note:

IGV Batch command: setSequenceShowTranslation

Show or hide the 3-frame translation rows of the sequence track.

Examples:

igv.set_sequence_show_translation(true)

Parameters:

  • bool (Boolean)

    true to show, false to hide.

Returns:

  • (String)

    IGV response.



513
514
515
516
517
# File 'lib/igv.rb', line 513

def set_sequence_show_translation(bool)
  bool = 'true' if bool == true
  bool = 'false' if bool == false
  send :setSequenceShowTranslation, bool
end

#set_sequence_strand(strand) ⇒ String

Note:

IGV Batch command: setSequenceStrand

Set the sequence strand to positive (+) or negative (-).

Examples:

igv.set_sequence_strand("+")

Parameters:

  • strand (String)

    “+” or “-”.

Returns:

  • (String)

    IGV response.



502
503
504
# File 'lib/igv.rb', line 502

def set_sequence_strand(strand)
  send :setSequenceStrand, strand
end

#set_sleep_interval(ms) ⇒ String

Note:

IGV Batch command: setSleepInterval

Set a delay (sleep) time in milliseconds between successive commands.

Examples:

igv.set_sleep_interval(200)

Parameters:

  • ms (Integer)

    Milliseconds to sleep.

Returns:

  • (String)

    IGV response.



526
527
528
# File 'lib/igv.rb', line 526

def set_sleep_interval(ms)
  send :setSleepInterval, ms
end

#set_track_height(height, track) ⇒ String

Note:

IGV Batch command: setTrackHeight

Set the specified track’s height in integer units.

Examples:

igv.set_track_height(50, "track1")

Parameters:

  • height (Integer)

    Height in pixels.

  • track (String)

    Track name.

Returns:

  • (String)

    IGV response.



538
539
540
# File 'lib/igv.rb', line 538

def set_track_height(height, track)
  send :setTrackHeight, height, track
end

#show_preferences_tableObject

Show “preference.tab” in your browser.



428
429
430
431
# File 'lib/igv.rb', line 428

def show_preferences_table
  require 'launchy'
  Launchy.open('https://raw.githubusercontent.com/igvteam/igv/master/src/main/resources/org/broad/igv/prefs/preferences.tab')
end

#snapshot(file_name = nil) ⇒ Object

Note:

IGV Batch command: snapshot

Save a snapshot of the IGV window to an image file.

Examples:

igv.snapshot("region.png")

Parameters:

  • file_name (String, nil) (defaults to: nil)

    Name of the image file. If nil, uses the current locus. If filename is omitted, writes a PNG file with a filename generated based on the locus. If filename is specified, the filename extension determines the image file format, which must be either .png or .svg. Passing a path might work, but is not recommended.



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
# File 'lib/igv.rb', line 382

def snapshot(file_name = nil)
  return send(:snapshot) if file_name.nil?
  dir_path = File.dirname(file_name)

  # file_name is a file name
  return send(:snapshot, file_name) if dir_path == "."

  # file_name is a path
  file_path = file_name
  warn "[ruby-igv] snapshot: Passing a path is not recommended. "

  if File.absolute_path?(file_path)
    dir_path = File.expand_path(dir_path)
  else
    dir_path = File.expand_path(File.join(@snapshot_dir, dir_path))
  end

  filename = File.basename(file_path)
  
  # Only change directory if needed
  if dir_path == @snapshot_dir
    send(:snapshot, filename)
  else
    # Temporarily change snapshot directory
    original_dir = @snapshot_dir
    snapshot_dir_internal(dir_path)
    result = send(:snapshot, filename)
    snapshot_dir_internal(original_dir)
    result
  end
end

#snapshot_dir(dir_path = nil) ⇒ String

Note:

IGV Batch command: snapshotDirectory

Set or get the directory in which to write images (snapshots).

Examples:

igv.snapshot_dir("/tmp/snapshots")
igv.snapshot_dir #=> "/tmp/snapshots"

Parameters:

  • dir_path (String, nil) (defaults to: nil)

    Directory path. If nil, returns current snapshot directory.

Returns:

  • (String)

    IGV response or current directory.



355
356
357
358
359
360
361
362
363
364
# File 'lib/igv.rb', line 355

def snapshot_dir(dir_path = nil)
  return @snapshot_dir if dir_path.nil?

  dir_path = File.expand_path(dir_path)
  return if dir_path == @snapshot_dir

  r = snapshot_dir_internal(dir_path)
  @snapshot_dir = dir_path
  r
end

#sort(option = 'base') ⇒ String

Note:

IGV Batch command: sort

Sort alignment or segmented copy number tracks.

Examples:

igv.sort("position")

Parameters:

  • option (String) (defaults to: 'base')

    Sort option (e.g. “base”, “position”, “strand”, “quality”, “sample”, “readGroup”).

Returns:

  • (String)

    IGV response.



257
258
259
260
261
262
# File 'lib/igv.rb', line 257

def sort(option = 'base')
  vop = %w[base position strand quality sample readGroup]
  raise "options is one of: #{vop.join(', ')}" unless vop.include? option

  send :sort, option
end

#squish(track = nil) ⇒ String

Note:

IGV Batch command: squish

Squish a given track. If not specified, squishes all annotation tracks.

Examples:

igv.squish
igv.squish("track1")

Parameters:

  • track (String, nil) (defaults to: nil)

    Track name (optional).

Returns:

  • (String)

    IGV response.



296
297
298
# File 'lib/igv.rb', line 296

def squish(track = nil)
  send :squish, track
end

#viewaspairs(track = nil) ⇒ String

Note:

IGV Batch command: viewaspairs

Set the display mode for an alignment track to “View as pairs”.

Examples:

igv.viewaspairs
igv.viewaspairs("track1")

Parameters:

  • track (String, nil) (defaults to: nil)

    Track name (optional).

Returns:

  • (String)

    IGV response.



308
309
310
# File 'lib/igv.rb', line 308

def viewaspairs(track = nil)
  send :viewaspairs, track
end