Class: IGV
- Inherits:
-
Object
- Object
- IGV
- 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
-
#history ⇒ Object
readonly
Returns the value of attribute history.
-
#host ⇒ Object
readonly
Returns the value of attribute host.
-
#port ⇒ Object
readonly
Returns the value of attribute port.
Class Method Summary collapse
-
.open(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd) {|IGV| ... } ⇒ IGV
Create IGV object and connect to IGV server.
-
.start(port: 60_151, command: 'igv', snapshot_dir: Dir.pwd) ⇒ IGV
Launch IGV from Ruby script.
Instance Method Summary collapse
-
#clear ⇒ self
Clear all loaded tracks and data.
-
#clear_access_tokens ⇒ String
Clears all access tokens.
-
#close ⇒ nil
Close the socket.
-
#closed? ⇒ Boolean
Check if the socket is closed.
-
#collapse(track = nil) ⇒ String
Collapse a given track.
-
#color_by(option, tag) ⇒ String
Set the “color by” option for alignment tracks.
-
#commands ⇒ Object
Open IGV batch command documentation in the browser.
-
#connect(host2 = @host, port2 = @port, connect_timeout: nil) ⇒ self
Connect to IGV server.
-
#echo(param = nil) ⇒ String
Write the value of “param” back to the response.
-
#exit ⇒ nil
(also: #quit)
Exit (close) the IGV application and close the socket.
-
#expand(track = nil) ⇒ String
Expand a given track.
-
#genome(name_or_path) ⇒ String
Select a genome by id, or load a genome (or indexed fasta) from the supplied path.
-
#goto(position) ⇒ String
(also: #go)
Go to the specified location or list of loci.
-
#group(option, tag) ⇒ String
Group alignments by the specified option.
-
#initialize(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd) ⇒ IGV
constructor
Create IGV client object.
-
#kill ⇒ nil
Kill IGV process by process group id.
-
#load(path_or_url, index: nil) ⇒ String
Load a data or session file by specifying a full path to a local file or a URL.
-
#max_panel_height(height) ⇒ String
Set the number of vertical pixels (height) of each panel to include in image.
-
#new ⇒ self
Create a new session.
-
#overlay(overlaid_track, *tracks) ⇒ String
Overlay a list of tracks.
-
#preferences(key, value) ⇒ String
Temporarily set the preference named key to the specified value.
-
#region(chr, start, end_) ⇒ String
Define a region of interest bounded by the two loci.
-
#save_session(file_path) ⇒ String
Save the current session.
-
#scroll_to_top ⇒ String
Scroll all panels to the top of the view.
-
#send(*cmds) ⇒ String
Send batch commands to IGV.
-
#separate(overlaid_track_name) ⇒ String
Separate an overlaid track into its constituitive tracks.
-
#set(cmd, *params) ⇒ String
Syntactic sugar for IGV commands that begin with set.
-
#set_access_token(token, host = nil) ⇒ String
Set an access token to be used in an Authorization header for all requests to host.
-
#set_alt_color(color, track) ⇒ String
Set the track “altColor”, used for negative values in a wig track or negative strand features.
-
#set_color(color, track) ⇒ String
Set the track color.
-
#set_data_range(range, track) ⇒ String
Set the data range (scale) for all numeric tracks, or a specific track.
-
#set_log_scale(bool, track) ⇒ String
Set the data scale to log (true) or linear (false).
-
#set_sequence_show_translation(bool) ⇒ String
Show or hide the 3-frame translation rows of the sequence track.
-
#set_sequence_strand(strand) ⇒ String
Set the sequence strand to positive (+) or negative (-).
-
#set_sleep_interval(ms) ⇒ String
Set a delay (sleep) time in milliseconds between successive commands.
-
#set_track_height(height, track) ⇒ String
Set the specified track’s height in integer units.
-
#show_preferences_table ⇒ Object
Show “preference.tab” in your browser.
-
#snapshot(file_name = nil) ⇒ Object
Save a snapshot of the IGV window to an image file.
-
#snapshot_dir(dir_path = nil) ⇒ String
Set or get the directory in which to write images (snapshots).
-
#sort(option = 'base') ⇒ String
Sort alignment or segmented copy number tracks.
-
#squish(track = nil) ⇒ String
Squish a given track.
-
#viewaspairs(track = nil) ⇒ String
Set the display mode for an alignment track to “View as pairs”.
Constructor Details
#initialize(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd) ⇒ IGV
Create IGV client object.
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.(snapshot_dir) @history = [] end |
Instance Attribute Details
#history ⇒ Object (readonly)
Returns the value of attribute history.
15 16 17 |
# File 'lib/igv.rb', line 15 def history @history end |
#host ⇒ Object (readonly)
Returns the value of attribute host.
15 16 17 |
# File 'lib/igv.rb', line 15 def host @host end |
#port ⇒ Object (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.
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
This will spawn a new IGV process and connect to it.
Launch IGV from Ruby script.
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
#clear ⇒ self
IGV Batch command: clear
Clear all loaded tracks and data.
329 330 331 332 |
# File 'lib/igv.rb', line 329 def clear send :clear self end |
#clear_access_tokens ⇒ String
IGV Batch command: clearAccessTokens
Clears all access tokens.
630 631 632 |
# File 'lib/igv.rb', line 630 def clear_access_tokens send :clearAccessTokens end |
#close ⇒ nil
Close the socket. This does not exit IGV.
121 122 123 124 |
# File 'lib/igv.rb', line 121 def close @socket&.close nil end |
#closed? ⇒ Boolean
Check if the socket is closed.
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
IGV Batch command: collapse
Collapse a given track. If not specified, collapses all tracks.
284 285 286 |
# File 'lib/igv.rb', line 284 def collapse(track = nil) send :collapse, track end |
#color_by(option, tag) ⇒ String
IGV Batch command: colorBy
Set the “color by” option for alignment tracks.
562 563 564 |
# File 'lib/igv.rb', line 562 def color_by(option, tag) send :colorBy, option, tag end |
#commands ⇒ Object
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.
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
IGV Batch command: echo
Write the value of “param” back to the response.
183 184 185 |
# File 'lib/igv.rb', line 183 def echo(param = nil) send :echo, param end |
#exit ⇒ nil Also known as: quit
IGV Batch command: exit
Exit (close) the IGV application and close 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
IGV Batch command: expand
Expand a given track. If not specified, expands all tracks.
272 273 274 |
# File 'lib/igv.rb', line 272 def (track = nil) send :expand, track end |
#genome(name_or_path) ⇒ String
IGV Batch command: genome
Select a genome by id, or load a genome (or indexed fasta) from the supplied path.
195 196 197 198 199 200 201 202 |
# File 'lib/igv.rb', line 195 def genome(name_or_path) path = File.(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
IGV Batch command: goto
Go to the specified location or list of loci.
232 233 234 |
# File 'lib/igv.rb', line 232 def goto(position) send :goto, position end |
#group(option, tag) ⇒ String
IGV Batch command: group
Group alignments by the specified option.
575 576 577 |
# File 'lib/igv.rb', line 575 def group(option, tag) send :group, option, tag end |
#kill ⇒ nil
Only works for IGV processes started by IGV.start.
Kill IGV process by process group id.
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
IGV Batch command: load
Load a data or session file by specifying a full path to a local file or a URL.
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.(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
IGV Batch command: maxPanelHeight
Set the number of vertical pixels (height) of each panel to include in image.
549 550 551 |
# File 'lib/igv.rb', line 549 def max_panel_height(height) send :maxPanelHeight, height end |
#new ⇒ self
IGV Batch command: new
Create a new session. Unloads all tracks except the default genome annotations.
318 319 320 321 |
# File 'lib/igv.rb', line 318 def new send :new self end |
#overlay(overlaid_track, *tracks) ⇒ String
IGV Batch command: overlay
Overlay a list of tracks.
587 588 589 |
# File 'lib/igv.rb', line 587 def (overlaid_track, *tracks) send :overlay, overlaid_track, *tracks end |
#preferences(key, value) ⇒ String
IGV Batch command: preference
Temporarily set the preference named key to the specified value.
423 424 425 |
# File 'lib/igv.rb', line 423 def preferences(key, value) send :preferences, key, value end |
#region(chr, start, end_) ⇒ String
IGV Batch command: region
Define a region of interest bounded by the two loci.
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
IGV Batch command: saveSession
Save the current session.
440 441 442 443 |
# File 'lib/igv.rb', line 440 def save_session(file_path) file_path = File.(file_path) send :saveSession, file_path end |
#scroll_to_top ⇒ String
IGV Batch command: scrollToTop
Scroll all panels to the top of the view.
597 598 599 |
# File 'lib/igv.rb', line 597 def scroll_to_top send :scrollToTop end |
#send(*cmds) ⇒ String
Send batch commands to 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
IGV Batch command: separate
Separate an overlaid track into its constituitive tracks.
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.
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
IGV Batch command: setAccessToken
Set an access token to be used in an Authorization header for all requests to host.
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
IGV Batch command: setAltColor
Set the track “altColor”, used for negative values in a wig track or negative strand features.
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
IGV Batch command: setColor
Set the track color.
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
IGV Batch command: setDataRange
Set the data range (scale) for all numeric tracks, or a specific track.
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
IGV Batch command: setLogScale
Set the data scale to log (true) or linear (false).
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
IGV Batch command: setSequenceShowTranslation
Show or hide the 3-frame translation rows of the sequence track.
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
IGV Batch command: setSequenceStrand
Set the sequence strand to positive (+) or negative (-).
502 503 504 |
# File 'lib/igv.rb', line 502 def set_sequence_strand(strand) send :setSequenceStrand, strand end |
#set_sleep_interval(ms) ⇒ String
IGV Batch command: setSleepInterval
Set a delay (sleep) time in milliseconds between successive commands.
526 527 528 |
# File 'lib/igv.rb', line 526 def set_sleep_interval(ms) send :setSleepInterval, ms end |
#set_track_height(height, track) ⇒ String
IGV Batch command: setTrackHeight
Set the specified track’s height in integer units.
538 539 540 |
# File 'lib/igv.rb', line 538 def set_track_height(height, track) send :setTrackHeight, height, track end |
#show_preferences_table ⇒ Object
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
IGV Batch command: snapshot
Save a snapshot of the IGV window to an image file.
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.(dir_path) else dir_path = File.(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
IGV Batch command: snapshotDirectory
Set or get the directory in which to write images (snapshots).
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.(dir_path) return if dir_path == @snapshot_dir r = snapshot_dir_internal(dir_path) @snapshot_dir = dir_path r end |
#sort(option = 'base') ⇒ String
IGV Batch command: sort
Sort alignment or segmented copy number tracks.
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
IGV Batch command: squish
Squish a given track. If not specified, squishes all annotation tracks.
296 297 298 |
# File 'lib/igv.rb', line 296 def squish(track = nil) send :squish, track end |
#viewaspairs(track = nil) ⇒ String
IGV Batch command: viewaspairs
Set the display mode for an alignment track to “View as pairs”.
308 309 310 |
# File 'lib/igv.rb', line 308 def viewaspairs(track = nil) send :viewaspairs, track end |