ruby-igv 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ca8294136b5eab8a344a40bf1d5ebb6d8ebf08f2794a1c6e1f582f593432049
-  data.tar.gz: c36d4c09a163ade8bfd860519a50519a28ae3f93121a14c482bf1bceb6239cde
+  metadata.gz: 7e4a99096506fa47659b90377b84c90adfdaa05212d158f182c2f5350463f927
+  data.tar.gz: ffa21ca61aa0c54c89082e7b2094b716a9949c3380f00d2ba20a6142a2986940
 SHA512:
-  metadata.gz: 1a085655336dcd4d06db5b51269f6b72d8d7174767f0b2990796d29cd410fb90adc884b86df3cf97087e75b35d387f655ed557628145c3af9badf17d3b29c50e
-  data.tar.gz: d8e0741301b1504f7714077ef435a987b51c520fcc3788f85acaf42ad3785fcec7bf435e897666a5f9a16050d2f503cfab5daa68525a1fc86a18b5219018a6ed
+  metadata.gz: e9f3bf96a5830840591966525f26a43e2c63c1aaf76efc1c6ba48cc76622f56390ef8f2ce82f0f8c28e18b8dc2bc4074047257c72b7ad77bdc26511f1cc27970
+  data.tar.gz: 27542e590daa398caa2fc460b82c05da84195c16e7d220e9a58973979321b776cfcbc2c44473e572d17401d1570a18a8494bdeb66d4bbc16bd531f400f9cb64a

data/README.md

@@ -1,15 +1,17 @@
 # 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)
+[![Docs Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://rubydoc.info/gems/ruby-igv)
+[![Docs Latest](https://img.shields.io/badge/docs-latest-blue.svg)](https://kojix2.github.io/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)
 
-
-<img src="https://user-images.githubusercontent.com/5798442/182540876-c3ca2906-7d05-4c93-9107-ce4135ae9765.png" align="right">
+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.
 
 ## Installation
 
+<img src="https://user-images.githubusercontent.com/5798442/182540876-c3ca2906-7d05-4c93-9107-ce4135ae9765.png" width="300" align="right">
+
 Requirement : 
 
 * [Ruby](https://github.com/ruby/ruby)
@@ -23,52 +25,87 @@ gem install ruby-igv
 
 ## Quickstart
 
+<img src="https://user-images.githubusercontent.com/5798442/182623864-a9fa59aa-abb9-4cb1-8311-2b3479b7414e.png" width="300" align="right">
+
 ```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
+### IGV batch 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 [yard docs](https://rubydoc.info/gems/ruby-igv/IGV). Commonly used IGV batch commands can be called from Ruby methods of the same name. However, not all IGV batch commands are implemented in Ruby. Use the `send` method described below.
 
 ### 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)
 ```
 
+To avoid unexpected behavior, ruby-igv does not use the `method_missing` mechanism.
 
 ### Launch IGV
 
-Launch IGV from Ruby scripot.
+Launch IGV from Ruby script.
 
 ```ruby
 igv = IGV.start # launch IGV app using spawn
 ```
 
+You can specify the port.
+
+```ruby
+igv = IGV.start(port: 60152)
+```
+
+If you start IGV in this way, you can force IGV to terminate by calling the kill method.
+
+```ruby
+igv.kill
+```
+
 ### Open socket connection to IGV
 
+If IGV is already running, use `new` or `open`.
+
+new
+
 ```ruby
 igv = IGV.new   # create an IGV object. Then you will type `igv.connect`
+igv = IGV.new(host: "127.0.0.1", port: 60151, snapshot_dir: "~/igv_snapshot")
+igv.connect # To start a connection, call connect explicitly.
+igv.close
+```
+
+open
+
+```ruby
 igv = IGV.open  # create an IGV object and connect it to an already activated IGV.
+igv.close
+IGV.open(host: "127.0.0.1", port: 60151, snapshot_dir: "~/igv_snapshot") do |igv|
+  # do something
+end # The socket is automatically closed.
 ```
 
 ### Close IGV
@@ -77,7 +114,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
 ```
@@ -90,7 +127,7 @@ igv.kill        # kill group pid created with IGV.start
 * Suggest or add new features
 
 ```
-Do you need commit rights to my repository?
+Do you need commit rights to this repository?
 Do you want to get admin rights and take over the project?
 If so, please feel free to contact me @kojix2.
 ```

data/lib/igv/version.rb

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

data/lib/igv.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'igv/version'
+require 'uri'
 require 'socket'
 require 'fileutils'
 
@@ -11,13 +12,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, 'IGV#initialize does not accept 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 +50,25 @@ 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 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)
@@ -44,7 +79,7 @@ class IGV
       break if line.include? "Listening on port #{port}"
     end
     puts "\e[0m"
-    igv = open(port: port)
+    igv = self.open(port: port, snapshot_dir: snapshot_dir)
     igv.instance_variable_set(:@pgid_igv, pgid_igv)
     igv
   end
@@ -88,17 +123,19 @@ 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 = \
       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"
+      .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(' ')
@@ -107,6 +144,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 +166,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 +176,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 +190,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
@@ -150,18 +203,22 @@ class IGV
                   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
 
   # Go to the specified location
+  # @note IGV Batch command
   #
   # @param location [String] The location to go to.
 
-  def goto(position)
-    send :goto, position
+  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
@@ -179,6 +236,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 +246,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 +256,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 +265,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 +274,20 @@ class IGV
     send :viewaspairs, track
   end
 
+  # @note IGV Batch command
+
+  def new
+    send :new
+  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 (modified)
 
   def exit
     send :exit
@@ -227,7 +296,8 @@ class IGV
   alias quit exit
 
   #	Sets the directory in which to write images.
-  # Retruns the current snapshot directory if no argument is given.
+  # Returns the current snapshot directory if no argument is given.
+  # @note IGV Batch command (modified)
   #
   # @param path [String] The path to the directory.
 
@@ -252,6 +322,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 +344,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 +362,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
 
@@ -297,4 +370,80 @@ class IGV
     file_path = File.expand_path(file_path)
     send :saveSession, file_path
   end
+
+  # @note IGV Batch command
+
+  def set_alt_color(color, track)
+    send :setAltColor, color, track
+  end
+
+  # @note IGV Batch command
+
+  def set_color(color, track)
+    send :setColor, color, track
+  end
+
+  # @note IGV Batch command
+
+  def set_data_range(range, track)
+    send :setDataRange, range, track
+  end
+
+  # @note IGV Batch command
+
+  def set_log_scale(bool, track)
+    bool = 'true' if bool == true
+    bool = 'false' if bool == false
+    send :setLogScale, bool, track
+  end
+
+  # @note IGV Batch command
+
+  def set_sequence_strand(strand)
+    send :setSequenceStrand, strand
+  end
+
+  # @note IGV Batch command
+
+  def set_sequence_show_translation(bool)
+    bool = 'true' if bool == true
+    bool = 'false' if bool == false
+    send :setSequenceShowTranslation, bool
+  end
+
+  # @note IGV Batch command
+
+  def set_sleep_interval(ms)
+    send :setSleepInterval, ms
+  end
+
+  # @note IGV Batch command
+
+  def set_track_height(height, track)
+    send :setTrackHeight, height, track
+  end
+
+  # @note IGV Batch command
+
+  def max_panel_height(height)
+    send :maxPanelHeight, height
+  end
+
+  # @note IGV Batch command
+
+  def color_by(option, tag)
+    send :colorBy, option, tag
+  end
+
+  # @note IGV Batch command
+
+  def group(option, tag)
+    send :group, option, tag
+  end
+
+  # @note IGV Batch command
+
+  def overlay(overlaid_track, *tracks)
+    send :overlay, overlaid_track, *tracks
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-igv
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.9
 platform: ruby
 authors:
 - kojix2
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-03 00:00:00.000000000 Z
+date: 2024-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: launchy
@@ -95,7 +95,7 @@ homepage: https://github.com/kojix2/ruby-igv
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -103,15 +103,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.5.5
+signing_key:
 specification_version: 4
 summary: Control IGV (Integrative Genomics Viewer) with Ruby.
 test_files: []