Class: IGV

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

Overview

The Integrative Genomics Viewer (IGV) software.broadinstitute.org/software/igv/

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION = 
'0.0.9'

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

  • path (String) —

    directory path to save snapshots

Raises:

  • (ArgumentError) 


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

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

#history ⇒ Object (readonly)

Returns the value of attribute history.



13
14
15
 
# File 'lib/igv.rb', line 13

def history
  @history
end

#host ⇒ Object (readonly)

Returns the value of attribute host.



13
14
15
 
# File 'lib/igv.rb', line 13

def host
  @host
end

#port ⇒ Object (readonly)

Returns the value of attribute port.



13
14
15
 
# File 'lib/igv.rb', line 13

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

  • path (String) —

    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

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



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

def self.start(port: 60_151, command: 'igv', snapshot_dir: Dir.pwd)
  case port_open?(port)
  when nil   then warn "Cannot tell if port #{port} is open"
  when true  then raise("Port #{port} is already in use")
  when false then warn "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

#clear ⇒ Object

Note:

IGV Batch command



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

def clear
  send :clear
end

#close ⇒ Object

Close the socket. This method dose not exit IGV.



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

def close
  @socket&.close
end

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


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

def closed?
  return true if @socket.nil?

  @socket.closed?
end

#collapse(track = nil) ⇒ Object

Note:

IGV Batch command

Collapses a given track.

Parameters:

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

    The track to collapse. If not specified, collapses all tracks.



254
255
256
 
# File 'lib/igv.rb', line 254

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

#color_by(option, tag) ⇒ Object

Note:

IGV Batch command



434
435
436
 
# File 'lib/igv.rb', line 434

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

#commands ⇒ Object

Show IGV batch commands in the browser. github.com/igvteam/igv/wiki/Batch-commands



163
164
165
166
 
# File 'lib/igv.rb', line 163

def commands
  require 'launchy'
  Launchy.open('https://github.com/igvteam/igv/wiki/Batch-commands')
end

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

Connect to IGV server



107
108
109
110
 
# File 'lib/igv.rb', line 107

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

#echo(param = nil) ⇒ String

Note:

IGV Batch command

Writes the value of “param” back to the response

Parameters:

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

    The parameter to echo.

Returns:

  • (String) —

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



174
175
176
 
# File 'lib/igv.rb', line 174

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

#exit ⇒ Object Also known as: quit

Note:

IGV Batch command (modified)

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



292
293
294
295
 
# File 'lib/igv.rb', line 292

def exit
  send :exit
  @socket.close
end

#expand(track = nil) ⇒ Object

Note:

IGV Batch command

Expands the given track.

Parameters:

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

    The track to expand. If not specified, expands all tracks.



244
245
246
 
# File 'lib/igv.rb', line 244

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

#genome(name_or_path) ⇒ Object

Note:

IGV Batch command

Selects a genome by id, or loads a genome (or indexed fasta) from the supplied path.

Parameters:

  • name_or_path (String) —

    The genome to load



183
184
185
186
187
188
189
190
 
# File 'lib/igv.rb', line 183

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) ⇒ Object Also known as: go

Note:

IGV Batch command

Go to the specified location

Parameters:

  • location (String) —

    The location to go to.



215
216
217
 
# File 'lib/igv.rb', line 215

def goto(*position)
  send :goto, *position
end

#group(option, tag) ⇒ Object

Note:

IGV Batch command



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

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

#kill ⇒ Object

Kill IGV process by process group id



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

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

#load(path_or_url, index: nil) ⇒ Object

Note:

IGV Batch command

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

Parameters:

  • path_or_url (String) —

    The path to a local file or a URL

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

    The index of the file



198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/igv.rb', line 198

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) ⇒ Object

Note:

IGV Batch command



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

def max_panel_height(height)
  send :maxPanelHeight, height
end

#new ⇒ Object

Note:

IGV Batch command



279
280
281
 
# File 'lib/igv.rb', line 279

def new
  send :new
end

#overlay(overlaid_track, *tracks) ⇒ Object

Note:

IGV Batch command



446
447
448
 
# File 'lib/igv.rb', line 446

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

#preferences(key, value) ⇒ Object

Note:

IGV Batch command

Temporarily set the preference named key to the specified value.

Parameters:

  • key (String) —

    The preference name

  • value (String) —

    The preference value



352
353
354
 
# File 'lib/igv.rb', line 352

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

#region(chr, start, end_) ⇒ Object

Note:

IGV Batch command

Defines a region of interest bounded by the two loci

Parameters:

  • chr (String) —

    The chromosome of the region

  • start (Integer) —

    The start position of the region

  • end_ (Integer) —

    The end position of the region



227
228
229
 
# File 'lib/igv.rb', line 227

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

#save_session(file_path) ⇒ Object

Note:

IGV Batch command

Save the current session. It is recommended that a full path be used for filename. IGV release 2.11.1

Parameters:

  • filename (String) —

    The path to the session file



369
370
371
372
 
# File 'lib/igv.rb', line 369

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

#send(*cmds) ⇒ String

Send batch commands to IGV.

Parameters:

  • *cmds (String, Symbol, Numeric) —

    batch commands

Returns:

  • (String) —

    response from IGV



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/igv.rb', line 130

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

#set(cmd, *params) ⇒ Object

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 commands

  • *params (String, Symbol, Numeric) —

    batch commands



155
156
157
158
 
# File 'lib/igv.rb', line 155

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

#set_alt_color(color, track) ⇒ Object

Note:

IGV Batch command



376
377
378
 
# File 'lib/igv.rb', line 376

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

#set_color(color, track) ⇒ Object

Note:

IGV Batch command



382
383
384
 
# File 'lib/igv.rb', line 382

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

#set_data_range(range, track) ⇒ Object

Note:

IGV Batch command



388
389
390
 
# File 'lib/igv.rb', line 388

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

#set_log_scale(bool, track) ⇒ Object

Note:

IGV Batch command



394
395
396
397
398
 
# File 'lib/igv.rb', line 394

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) ⇒ Object

Note:

IGV Batch command



408
409
410
411
412
 
# File 'lib/igv.rb', line 408

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

#set_sequence_strand(strand) ⇒ Object

Note:

IGV Batch command



402
403
404
 
# File 'lib/igv.rb', line 402

def set_sequence_strand(strand)
  send :setSequenceStrand, strand
end

#set_sleep_interval(ms) ⇒ Object

Note:

IGV Batch command



416
417
418
 
# File 'lib/igv.rb', line 416

def set_sleep_interval(ms)
  send :setSleepInterval, ms
end

#set_track_height(height, track) ⇒ Object

Note:

IGV Batch command



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

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

#show_preferences_table ⇒ Object

Show “preference.tab” in your browser.



358
359
360
361
 
# File 'lib/igv.rb', line 358

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_path = nil) ⇒ Object

Note:

IGV Batch command (modified)

Note:

In Ruby-IGV, it is possible to pass absolute or relative paths as well as file names; the Snapshot directory is set to Dir.pwd by default.

Saves a snapshot of the IGV window to an image file. 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.

Parameters:

  • file_path (String) (defaults to: nil) —

    The path to the image file.



331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/igv.rb', line 331

def snapshot(file_path = nil)
  return send(:snapshot) if file_path.nil?

  dir_path = File.dirname(file_path)
  filename = File.basename(file_path)
  if dir_path != @snapshot_dir
    snapshot_dir_internal(dir_path)
    r = send :snapshot, filename
    snapshot_dir_internal(@snapshot_dir)
    r
  else
    send :snapshot, filename
  end
end

#snapshot_dir(dir_path = nil) ⇒ Object

Note:

IGV Batch command (modified)

Sets the directory in which to write images. Returns the current snapshot directory if no argument is given.

Parameters:

  • path (String) —

    The path to the directory.



304
305
306
307
308
309
310
311
312
313
 
# File 'lib/igv.rb', line 304

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') ⇒ Object 



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

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) ⇒ Object

Note:

IGV Batch command

Squish a given track.

Parameters:

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

    The track to squish. If not specified, squishes all tracks.



264
265
266
 
# File 'lib/igv.rb', line 264

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

#viewaspairs(track = nil) ⇒ Object

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

Parameters:

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

    The track to set. If not specified, sets all tracks.



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

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