ruby-igv 0.0.5 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a162dd0aa5d26fd45b3da87eb9c8e4faec6bc47f6922dc850dc5f5f556405c26
-  data.tar.gz: 6ceb747c0f8b5b697f561c2836c8e021d29fd2bcc0cc5bc91cc7916bc24b0c61
+  metadata.gz: ed0319fd387ae14300d7f596b0a0e2a6aa6cd1dab63a67921070e66446b532db
+  data.tar.gz: 7d3e5587f800b76b5f96c9fccb44c210e8b36ee6fb598a368b686bff6c1745e7
 SHA512:
-  metadata.gz: 0e05cd137522d371629790616283c5f2c31f96f9882979d64f46ab83530ccf14569bc039213ddda103653ad009d9818e50f1e95e5f3738cb985903da6d8c6ed2
-  data.tar.gz: 361d5f9e770f4f78304e4b99672e6e5e2c116bd8994b5d57076b808b40b27ae5fa493c74842923d4165adef2b79827ae85e5d711d9ce279f001afddb0676df95
+  metadata.gz: e85423c90acd6a974e5b29a1890a1177823785043b6bae0736d6f234c9bcdb6b57f2dc22858ccfdc53af270e367b9576f309f6235d6754bce2d71b6ed7fd90dc
+  data.tar.gz: 445d5ce3a05e5d876ac4813cce4fdaad9bee4fe568a706838a97f8958cb247429bad6cf996072e68b246fa5a345e1827b45bf9210b8f12890550d8bd6b00b6d9

data/README.md

@@ -1,32 +1,92 @@
-# Ruby-IGV
+# ruby-igv
 
 [![Gem Version](https://badge.fury.io/rb/ruby-igv.svg)](https://badge.fury.io/rb/ruby-igv)
 [![Docs Latest](https://img.shields.io/badge/docs-latest-blue.svg)](https://rubydoc.info/gems/ruby-igv)
 [![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)
 
-Controlling [Integrative Genomics Viewer (IGV)](http://software.broadinstitute.org/software/igv/) with the [Ruby](https://github.com/ruby/ruby) language.
+Ruby-IGV is a simple tool for controlling the Integrated Genomics Viewer (IGV) from the Ruby language. It provides an automated way to load files, specify genome locations, and take and save screenshots using IGV.
+
+<img src="https://user-images.githubusercontent.com/5798442/182540876-c3ca2906-7d05-4c93-9107-ce4135ae9765.png" align="right">
 
 ## Installation
 
+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
+
+<img src="https://user-images.githubusercontent.com/5798442/182623864-a9fa59aa-abb9-4cb1-8311-2b3479b7414e.png" width="300" align="left">
+
+```ruby
+require 'igv'
+
+igv = IGV.start # This launch IGV
+
+igv.set      :SleepInterval, 200 # give a time interval
+igv.genome   'hg19'
+igv.load     'http://hgdownload.cse.ucsc.edu/goldenPath/' \
+             'hg19/encodeDCC/wgEncodeUwRepliSeq/' \
+             'wgEncodeUwRepliSeqK562G1AlnRep1.bam'
+igv.go       'chr18:78016233-78016640'
+igv.snapshot 'region.png'
+```
+
 ## Usage
 
+### commands
+
+The commonly used commands in IGV are summarized in the official [list of Batch commands](https://github.com/igvteam/igv/wiki/Batch-commands). (but even this does not seem to be all of them). You can also call the `commands` method from Ruby to open a browser and view the list.
+
 ```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
 ```
 
-* [Controlling IGV through a Port](https://software.broadinstitute.org/software/igv/PortCommands)
+### docs
+
+See [docs](https://rubydoc.info/gems/ruby-igv/IGV). Not all commands are implemented in Ruby.
+
+### send
+
+Commands that are not implemented can be sent using the send method.
+
+```ruby
+igv.send("maxPanelHeight", 10)
+```
+
+### Launch IGV
+
+Launch IGV from Ruby script.
+
+```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 then close the socket connection
+igv.quit        # alias method to exit
+igv.kill        # kill group pid created with IGV.start
+```
 
 ## Contributing
 
@@ -35,7 +95,13 @@ igv.send   'echo'        # whatever you want
 * Write, clarify, or fix documentation
 * Suggest or add new features
 
-# Acknowledgement
+```
+Do you need commit rights to my repository?
+Do you want to get admin rights and take over the project?
+If so, please feel free to contact me @kojix2.
+```
+
+## Acknowledgement
 This gem is strongly inspired by a Python script developed by Brent Pedersen.
 * [brentp/bio-playground/igv](https://github.com/brentp/bio-playground).
 

data/lib/igv/version.rb

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

data/lib/igv.rb

@@ -9,103 +9,355 @@ require 'fileutils'
 class IGV
   class Error < StandardError; end
 
-  attr_reader :host, :port, :snapshot_dir, :history
+  attr_reader :host, :port, :history
+
+  # Create IGV client object
+  #
+  # @param host [String] hostname or IP address of IGV server
+  # @param port [Integer] port number of IGV server
+  # @param path [String] directory path to save snapshots
+  # @return [IGV] IGV client object
 
   def initialize(host: '127.0.0.1', port: 60_151, snapshot_dir: Dir.pwd)
+    raise ArgumentError, 'new dose not take a block' if block_given?
+
     @host = host
     @port = port
+    @snapshot_dir = File.expand_path(snapshot_dir)
     @history = []
-    connect
-    set_snapshot_dir(snapshot_dir)
   end
 
-  # def self.start
-  # end
+  # Create IGV object and connect to IGV server
+  # This method accepts a block.
+  #
+  # @param host [String] hostname or IP address of IGV server
+  # @param port [Integer] port number of IGV server
+  # @param path [String] directory path to save snapshots
+  # @return [IGV] IGV client object
+  # @yield [IGV] IGV client object
+
+  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
+
+  def self.port_open?(port)
+    !system("lsof -i:#{port}", out: '/dev/null')
+  end
+  private_class_method :port_open?
+
+  # Launch IGV from ruby script
+  #
+  # @param port [Integer] port number
+  # @param command [String] command to launch IGV
+  # @param snapshot_dir [String] directory path to save snapshots
+  # @return [IGV] IGV client object
+
+  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 false then raise("Port #{port} is already in use")
+    when true  then warn "Port #{port} is available"
+    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 = open(port: port, snapshot_dir: snapshot_dir)
+    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
+  def connect(host2 = @host, port2 = @port, connect_timeout: nil)
     @socket&.close
-    @socket = Socket.new(Socket::AF_INET, Socket::SOCK_STREAM)
-    addr = Socket.sockaddr_in(port, host)
-    @socket.connect(addr)
+    @socket = Socket.tcp(host2, port2, connect_timeout: connect_timeout)
+  end
+
+  # Close the socket.
+  # This method dose not exit IGV.
+
+  def close
+    @socket&.close
+  end
+
+  def closed?
+    return true if @socket.nil?
+
+    @socket.closed?
+  end
+
+  # Send batch commands to IGV.
+  #
+  # @param *cmds [String, Symbol, Numeric] batch commands
+  # @return [String] response from IGV
+
+  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
+
+  # Syntactic sugar for IGV commands that begin with set.
+  #
+  # @example
+  #   igv.set :SleepInterval, 100
+  #   igv.send "setSleepInterval", 100 # same as above
+  # @param cmd [String, Symbol] batch commands
+  # @param *params [String, Symbol, Numeric] batch commands
+
+  def set(cmd, *params)
+    cmd = "set#{cmd}"
+    send(cmd, *params)
+  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
 
-  def go(position)
-    send "goto #{position}"
+  # Writes the value of "param" back to the response
+  # @note IGV Batch command
+  #
+  # @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.
+  # @note IGV Batch command
+  #
+  # @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.
+  # @note IGV Batch command
+  #
+  # @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
 
-  def region(contig, start, end_)
-    send ['region', contig, start, end_].join(' ')
+  # Go to the specified location
+  # @note IGV Batch command
+  #
+  # @param location [String] The location to go to.
+
+  def goto(position)
+    send :goto, position
+  end
+  alias go goto
+
+  # Defines a region of interest bounded by the two loci
+  # @note IGV Batch command
+  #
+  # @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}"
+    send :sort, option
   end
 
-  def expand(_track = '')
-    send "expand #{track}"
+  # Expands the given track.
+  # @note IGV Batch command
+  #
+  # @param track [String] The track to expand.
+  #                       If not specified, expands all tracks.
+
+  def expand(track = nil)
+    send :expand, track
   end
 
-  def collapse(_track = '')
-    send "collapse #{track}"
+  # Collapses a given track.
+  # @note IGV Batch command
+  #
+  # @param track [String] The track to collapse.
+  #                       If not specified, collapses all tracks.
+
+  def collapse(track = nil)
+    send :collapse, track
+  end
+
+  # Squish a given track.
+  # @note IGV Batch command
+  #
+  # @param track [String] The track to squish.
+  #                       If not specified, squishes all tracks.
+
+  def squish(track = nil)
+    send :squish, track
   end
 
+  # 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
+
+  # @note IGV Batch command
+
   def clear
-    send 'clear'
+    send :clear
   end
 
+  # Exit (close) the IGV application and close the socket.
+  # @note IGV Batch command (modifyed)
+
   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.
+  # @note IGV Batch command (modified)
+  #
+  # @param path [String] The path to the directory.
+
+  def snapshot_dir(dir_path = nil)
+    return @snapshot_dir if dir_path.nil?
 
-  def snapshot_dir=(snapshot_dir)
-    snapshot_dir = File.expand_path(snapshot_dir)
-    return if snapshot_dir == @snaphot_dir
+    dir_path = File.expand_path(dir_path)
+    return if dir_path == @snapshot_dir
 
-    FileUtils.mkdir_p(snapshot_dir)
-    send "snapshotDirectory #{snapshot_dir}"
-    @snapshot_dir = snapshot_dir
+    r = snapshot_dir_internal(dir_path)
+    @snapshot_dir = dir_path
+    r
   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)}"
+  private def snapshot_dir_internal(dir_path)
+    dir_path = File.expand_path(dir_path)
+    FileUtils.mkdir_p(dir_path)
+    send :snapshotDirectory, dir_path
+  end
+
+  # 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 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.
+  #
+  # @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.
+  # @note IGV Batch command
+  #
+  # @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
+  # @note IGV Batch command
+  #
+  # @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.5
+  version: 0.0.8
 platform: ruby
 authors:
 - kojix2
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-10 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
@@ -96,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Control IGV (Integrative Genomics Viewer) with Ruby.