ruby-igv 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ca8294136b5eab8a344a40bf1d5ebb6d8ebf08f2794a1c6e1f582f593432049
-  data.tar.gz: c36d4c09a163ade8bfd860519a50519a28ae3f93121a14c482bf1bceb6239cde
+  metadata.gz: ed0319fd387ae14300d7f596b0a0e2a6aa6cd1dab63a67921070e66446b532db
+  data.tar.gz: 7d3e5587f800b76b5f96c9fccb44c210e8b36ee6fb598a368b686bff6c1745e7
 SHA512:
-  metadata.gz: 1a085655336dcd4d06db5b51269f6b72d8d7174767f0b2990796d29cd410fb90adc884b86df3cf97087e75b35d387f655ed557628145c3af9badf17d3b29c50e
-  data.tar.gz: d8e0741301b1504f7714077ef435a987b51c520fcc3788f85acaf42ad3785fcec7bf435e897666a5f9a16050d2f503cfab5daa68525a1fc86a18b5219018a6ed
+  metadata.gz: e85423c90acd6a974e5b29a1890a1177823785043b6bae0736d6f234c9bcdb6b57f2dc22858ccfdc53af270e367b9576f309f6235d6754bce2d71b6ed7fd90dc
+  data.tar.gz: 445d5ce3a05e5d876ac4813cce4fdaad9bee4fe568a706838a97f8958cb247429bad6cf996072e68b246fa5a345e1827b45bf9210b8f12890550d8bd6b00b6d9

data/README.md

@@ -5,6 +5,7 @@
 [![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)
 
+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">
 
@@ -23,42 +24,47 @@ 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:78,016,233-78,016,640'
+igv.load     'http://hgdownload.cse.ucsc.edu/goldenPath/' \
+             'hg19/encodeDCC/wgEncodeUwRepliSeq/' \
+             'wgEncodeUwRepliSeqK562G1AlnRep1.bam'
+igv.go       'chr18:78016233-78016640'
 igv.snapshot 'region.png'
-igv.exit
 ```
 
 ## Usage
 
-### docs
+### commands
 
-See [the list of Batch commands](https://github.com/igvteam/igv/wiki/Batch-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.commands # Show the IGV command reference in your browser
 ```
 
-[docs](https://rubydoc.info/gems/ruby-igv)
+### docs
+
+See [docs](https://rubydoc.info/gems/ruby-igv/IGV). Not all commands are implemented in Ruby.
 
 ### send
 
-Not all commands are implemented in Ruby. Commands that are not implemented can be sent using the send method.
+Commands that are not implemented can be sent using the send method.
 
 ```ruby
 igv.send("maxPanelHeight", 10)
 ```
 
-
 ### Launch IGV
 
-Launch IGV from Ruby scripot.
+Launch IGV from Ruby script.
 
 ```ruby
 igv = IGV.start # launch IGV app using spawn
@@ -77,7 +83,7 @@ The behavior of the following methods is different.
 
 ```ruby
 igv.close       # close the socket connection
-igv.exit        # send exit command to IGV
+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
 ```

data/lib/igv/version.rb

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

data/lib/igv.rb

@@ -11,13 +11,31 @@ class IGV
 
   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 = []
   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
@@ -31,9 +49,24 @@ class IGV
     igv
   end
 
-  # Launch IGV from ruby script
+  def self.port_open?(port)
+    !system("lsof -i:#{port}", out: '/dev/null')
+  end
+  private_class_method :port_open?
 
-  def self.start(port: 60_151, command: 'igv')
+  # 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)
@@ -44,7 +77,7 @@ class IGV
       break if line.include? "Listening on port #{port}"
     end
     puts "\e[0m"
-    igv = open(port: port)
+    igv = open(port: port, snapshot_dir: snapshot_dir)
     igv.instance_variable_set(:@pgid_igv, pgid_igv)
     igv
   end
@@ -88,7 +121,9 @@ class IGV
   end
 
   # Send batch commands to IGV.
-  # @param [String] cmds
+  #
+  # @param *cmds [String, Symbol, Numeric] batch commands
+  # @return [String] response from IGV
 
   def send(*cmds)
     cmd = \
@@ -107,6 +142,19 @@ class IGV
     @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
 
@@ -116,6 +164,7 @@ class IGV
   end
 
   # 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".
@@ -125,6 +174,7 @@ class IGV
   end
 
   # 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
 
@@ -138,6 +188,7 @@ class IGV
   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
@@ -153,6 +204,7 @@ class IGV
   end
 
   # Go to the specified location
+  # @note IGV Batch command
   #
   # @param location [String] The location to go to.
 
@@ -162,6 +214,7 @@ class IGV
   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
@@ -179,6 +232,7 @@ class IGV
   end
 
   # Expands the given track.
+  # @note IGV Batch command
   #
   # @param track [String] The track to expand.
   #                       If not specified, expands all tracks.
@@ -188,6 +242,7 @@ class IGV
   end
 
   # Collapses a given track.
+  # @note IGV Batch command
   #
   # @param track [String] The track to collapse.
   #                       If not specified, collapses all tracks.
@@ -197,6 +252,7 @@ class IGV
   end
 
   # Squish a given track.
+  # @note IGV Batch command
   #
   # @param track [String] The track to squish.
   #                       If not specified, squishes all tracks.
@@ -205,7 +261,7 @@ class IGV
     send :squish, track
   end
 
-  # Set the display mode for an alignment track to "View as pairs". 
+  # 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.
@@ -214,11 +270,14 @@ class IGV
     send :viewaspairs, track
   end
 
+  # @note IGV Batch command
+
   def clear
     send :clear
   end
 
-  # Exit (close) the IGV application.
+  # Exit (close) the IGV application and close the socket.
+  # @note IGV Batch command (modifyed)
 
   def exit
     send :exit
@@ -228,6 +287,7 @@ class IGV
 
   #	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.
 
@@ -252,6 +312,7 @@ class IGV
   # 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.
   #
@@ -273,6 +334,7 @@ class IGV
   end
 
   # 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
@@ -290,6 +352,7 @@ class IGV
 
   # 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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-igv
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - kojix2