ruby-igv 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0cb49945b7684826529fbdd82ae84de01c45f3b309f1cf41e096dab651ca261
-  data.tar.gz: a345c80a98c564cf7de1cb62768214f8273abf033b1c24ebb8575bb69fe00026
+  metadata.gz: 1ca8294136b5eab8a344a40bf1d5ebb6d8ebf08f2794a1c6e1f582f593432049
+  data.tar.gz: c36d4c09a163ade8bfd860519a50519a28ae3f93121a14c482bf1bceb6239cde
 SHA512:
-  metadata.gz: db09a0dc972eb58b3c90412be2a7503015ca3b32152ea2f4be89065833ed94d674fb4bce97a19a5ba8721b59be14b8c8beb00849db865d6b9ee9cfe3ea0afffc
-  data.tar.gz: b97c8c53963c3a9460a38c06bde171fd5f9494c7bdbc8b575ded5b17a854b0038ac421da45628f42865d9cecef7824485adc80e92af9281541bac6dc96466102
+  metadata.gz: 1a085655336dcd4d06db5b51269f6b72d8d7174767f0b2990796d29cd410fb90adc884b86df3cf97087e75b35d387f655ed557628145c3af9badf17d3b29c50e
+  data.tar.gz: d8e0741301b1504f7714077ef435a987b51c520fcc3788f85acaf42ad3785fcec7bf435e897666a5f9a16050d2f503cfab5daa68525a1fc86a18b5219018a6ed

data/README.md

@@ -5,31 +5,82 @@
 [![The MIT License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE.txt)
 [![DOI](https://zenodo.org/badge/281373245.svg)](https://zenodo.org/badge/latestdoi/281373245)
 
+
+<img src="https://user-images.githubusercontent.com/5798442/182540876-c3ca2906-7d05-4c93-9107-ce4135ae9765.png" align="right">
+
 ## Installation
 
-Requirement: [IGV (Integrative Genomics Viewer)](http://software.broadinstitute.org/software/igv/) and [Ruby](https://github.com/ruby/ruby).
+Requirement : 
+
+* [Ruby](https://github.com/ruby/ruby)
+* [IGV (Integrative Genomics Viewer)](http://software.broadinstitute.org/software/igv/)
+  * [Enable IGV to listen on the port](https://software.broadinstitute.org/software/igv/Preferences#Advanced)
+  * View > Preference > Advanced > Enable port ☑
 
 ```ruby
 gem install ruby-igv
 ```
 
+## Quickstart
+
+```ruby
+require 'igv'
+
+igv = IGV.start # This launch IGV
+igv.genome   'hg19'
+igv.load     'http://hgdownload.cse.ucsc.edu/goldenPath/hg19/encodeDCC/' \
+             'wgEncodeUwRepliSeq/wgEncodeUwRepliSeqK562G1AlnRep1.bam'
+igv.go       'chr18:78,016,233-78,016,640'
+igv.snapshot 'region.png'
+igv.exit
+```
+
 ## Usage
 
-[Enable IGV to listen on the port](https://software.broadinstitute.org/software/igv/Preferences#Advanced): Preference > Advanced > Enable port
+### docs
+
+See [the list of Batch commands](https://github.com/igvteam/igv/wiki/Batch-commands).
 
 ```ruby
-igv = IGV.new
-igv.genome 'hg19'
-igv.load   'http://hgdownload.cse.ucsc.edu/goldenPath/hg19/encodeDCC/wgEncodeUwRepliSeq/wgEncodeUwRepliSeqK562G1AlnRep1.bam'
-igv.go     'chr18:78,016,233-78,016,640'
-igv.save   '/tmp/r/region.svg'
-igv.save   '/tmp/r/region.png'
-igv.snapshot_dir = '/tmp/r2/'
-igv.save   'region.jpg'  # save to /tmp/r2/region.png
-igv.send   'echo'        # whatever you want
+igv.commands # Show the IGV command reference in your browser
 ```
 
-See [the list of Batch commands](https://github.com/igvteam/igv/wiki/Batch-commands).
+[docs](https://rubydoc.info/gems/ruby-igv)
+
+### send
+
+Not all commands are implemented in Ruby. Commands that are not implemented can be sent using the send method.
+
+```ruby
+igv.send("maxPanelHeight", 10)
+```
+
+
+### Launch IGV
+
+Launch IGV from Ruby scripot.
+
+```ruby
+igv = IGV.start # launch IGV app using spawn
+```
+
+### Open socket connection to IGV
+
+```ruby
+igv = IGV.new   # create an IGV object. Then you will type `igv.connect`
+igv = IGV.open  # create an IGV object and connect it to an already activated IGV.
+```
+
+### Close IGV
+
+The behavior of the following methods is different.
+
+```ruby
+igv.close       # close the socket connection
+igv.exit        # send exit command to IGV
+igv.quit        # alias method to exit
+igv.kill        # kill group pid created with IGV.start
+```
 
 ## Contributing
 

data/lib/igv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class IGV
-  VERSION = '0.0.6'
+  VERSION = '0.0.7'
 end

data/lib/igv.rb

@@ -9,103 +9,292 @@ require 'fileutils'
 class IGV
   class Error < StandardError; end
 
-  attr_reader :host, :port, :snapshot_dir, :history
+  attr_reader :host, :port, :history
 
   def initialize(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd)
     @host = host
     @port = port
+    @snapshot_dir = File.expand_path(snapshot_dir)
     @history = []
-    connect
-    set_snapshot_dir(snapshot_dir)
   end
 
-  # def self.start
-  # end
+  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?
 
-  def connect
+    begin
+      yield igv
+    ensure
+      @socket&.close
+    end
+    igv
+  end
+
+  # Launch IGV from ruby script
+
+  def self.start(port: 60_151, command: 'igv')
+    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 = open(port: port)
+    igv.instance_variable_set(:@pgid_igv, pgid_igv)
+    igv
+  end
+
+  # Kill IGV process by process group id
+
+  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
+
+  # Connect to IGV server
+
+  def connect(host2 = @host, port2 = @port, connect_timeout: nil)
+    @socket&.close
+    @socket = Socket.tcp(host2, port2, connect_timeout: connect_timeout)
+  end
+
+  # Close the socket.
+  # This method dose not exit IGV.
+
+  def close
     @socket&.close
-    @socket = Socket.new(Socket::AF_INET, Socket::SOCK_STREAM)
-    addr = Socket.sockaddr_in(port, host)
-    @socket.connect(addr)
   end
 
-  def go(position)
-    send "goto #{position}"
+  def closed?
+    return true if @socket.nil?
+
+    @socket.closed?
+  end
+
+  # Send batch commands to IGV.
+  # @param [String] cmds
+
+  def send(*cmds)
+    cmd = \
+      cmds
+      .compact
+      .map do |cmd|
+        case cmd
+        when String, Symbol, Numeric          then cmd.to_s
+        when ->(c) { c.respond_to?(:to_str) } then cmd.to_str
+        else raise ArgumentError, "#{cmd.inspect} is not a string"
+        end.strip.encode(Encoding::UTF_8)
+      end
+      .join(' ')
+    @history << cmd
+    @socket.puts(cmd)
+    @socket.gets&.chomp("\n")
+  end
+
+  # Show IGV batch commands in the browser.
+  # https://github.com/igvteam/igv/wiki/Batch-commands
+
+  def commands
+    require 'launchy'
+    Launchy.open('https://github.com/igvteam/igv/wiki/Batch-commands')
+  end
+
+  # Writes the value of "param" back to the response
+  #
+  # @param param [String] The parameter to echo.
+  # @return [String] The value of "param". If param is not specified, "echo".
+
+  def echo(param = nil)
+    send :echo, param
   end
-  alias goto go
+
+  # Selects a genome by id, or loads a genome (or indexed fasta) from the supplied path.
+  #
+  # @param name_or_path [String] The genome to load
 
   def genome(name_or_path)
     path = File.expand_path(name_or_path)
     if File.exist?(path)
-      send "genome #{path}"
+      send :genome, path
     else
-      send "genome #{name_or_path}"
+      send :genome, name_or_path
     end
   end
 
-  def load(path_or_url)
-    if URI.parse(path_or_url).scheme
-      send "load #{path_or_url}"
-    else
-      send "load #{File.expand_path(path_or_url)}"
-    end
+  # Loads a data or session file by specifying a full path to a local file or a URL.
+  #
+  # @param path_or_url [String] The path to a local file or a URL
+  # @param index [String] The index of the file
+
+  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
+  end
+
+  # Go to the specified location
+  #
+  # @param location [String] The location to go to.
+
+  def goto(position)
+    send :goto, position
   end
+  alias go goto
 
-  def region(contig, start, end_)
-    send ['region', contig, start, end_].join(' ')
+  # Defines a region of interest bounded by the two loci
+  #
+  # @param chr [String] The chromosome of the region
+  # @param start [Integer] The start position of the region
+  # @param end_ [Integer] The end position of the region
+
+  def region(chr, start, end_)
+    send :region, chr, start, end_
   end
 
   def sort(option = 'base')
-    unless %w[base position strand quality sample readGroup].include? option
-      raise 'options is one of: base, position, strand, quality, sample, and readGroup.'
-    end
+    vop = %w[base position strand quality sample readGroup]
+    raise "options is one of: #{vop.join(', ')}" unless vop.include? option
+
+    send :sort, option
+  end
 
-    send "sort #{option}"
+  # Expands the given track.
+  #
+  # @param track [String] The track to expand.
+  #                       If not specified, expands all tracks.
+
+  def expand(track = nil)
+    send :expand, track
+  end
+
+  # Collapses a given track.
+  #
+  # @param track [String] The track to collapse.
+  #                       If not specified, collapses all tracks.
+
+  def collapse(track = nil)
+    send :collapse, track
   end
 
-  def expand(track = '')
-    send "expand #{track}"
+  # Squish a given track.
+  #
+  # @param track [String] The track to squish.
+  #                       If not specified, squishes all tracks.
+
+  def squish(track = nil)
+    send :squish, track
   end
 
-  def collapse(track = '')
-    send "collapse #{track}"
+  # Set the display mode for an alignment track to "View as pairs". 
+  #
+  # @param track [String] The track to set.
+  #                       If not specified, sets all tracks.
+
+  def viewaspairs(track = nil)
+    send :viewaspairs, track
   end
 
   def clear
-    send 'clear'
+    send :clear
   end
 
+  # Exit (close) the IGV application.
+
   def exit
-    send 'exit'
+    send :exit
+    @socket.close
   end
   alias quit exit
 
-  def send(cmd)
-    @history << cmd
-    @socket.puts(cmd.encode(Encoding::UTF_8))
-    @socket.gets&.chomp("\n")
-  end
+  #	Sets the directory in which to write images.
+  # Retruns the current snapshot directory if no argument is given.
+  #
+  # @param path [String] The path to the directory.
+
+  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
 
-  def snapshot_dir=(snapshot_dir)
-    snapshot_dir = File.expand_path(snapshot_dir)
-    return if snapshot_dir == @snaphot_dir
+    r = snapshot_dir_internal(dir_path)
+    @snapshot_dir = dir_path
+    r
+  end
 
-    FileUtils.mkdir_p(snapshot_dir)
-    send "snapshotDirectory #{snapshot_dir}"
-    @snapshot_dir = snapshot_dir
+  private def snapshot_dir_internal(dir_path)
+    dir_path = File.expand_path(dir_path)
+    FileUtils.mkdir_p(dir_path)
+    send :snapshotDirectory, dir_path
   end
-  alias set_snapshot_dir snapshot_dir=
 
-  def save(file_path = nil)
-    if file_path
-      # igv assumes the path is just a single filename, but
-      # we can set the snapshot dir. then just use the filename.
-      dir_path = File.dirname(file_path)
-      set_snapshot_dir(File.expand_path(dir_path)) if dir_path != '.'
-      send "snapshot #{File.basename(file_path)}"
+  # 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.
+  # @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.
+  #
+  # @param file_path [String] The path to the image file.
+
+  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'
+      send :snapshot, filename
     end
   end
-  alias snapshot save
+
+  # Temporarily set the preference named key to the specified value.
+  #
+  # @param key [String] The preference name
+  # @param value [String] The preference value
+
+  def preferences(key, value)
+    send :preferences, key, value
+  end
+
+  # Show "preference.tab" in your browser.
+
+  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
+
+  # Save the current session.
+  # It is recommended that a full path be used for filename. IGV release 2.11.1
+  #
+  # @param filename [String] The path to the session file
+
+  def save_session(file_path)
+    file_path = File.expand_path(file_path)
+    send :saveSession, file_path
+  end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ruby-igv
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - kojix2
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-02 00:00:00.000000000 Z
+date: 2022-08-03 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: launchy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement