ruby-igv 0.0.8 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed0319fd387ae14300d7f596b0a0e2a6aa6cd1dab63a67921070e66446b532db
-  data.tar.gz: 7d3e5587f800b76b5f96c9fccb44c210e8b36ee6fb598a368b686bff6c1745e7
+  metadata.gz: 19fb874a7ea3fe0edee703b42b481db4c718609287a1ed4c1407a03bec2b1e9a
+  data.tar.gz: 982188fc06b54fc0d772f1b0fb21228c2aa9a0d7c2319c527b03f0b5411cb916
 SHA512:
-  metadata.gz: e85423c90acd6a974e5b29a1890a1177823785043b6bae0736d6f234c9bcdb6b57f2dc22858ccfdc53af270e367b9576f309f6235d6754bce2d71b6ed7fd90dc
-  data.tar.gz: 445d5ce3a05e5d876ac4813cce4fdaad9bee4fe568a706838a97f8958cb247429bad6cf996072e68b246fa5a345e1827b45bf9210b8f12890550d8bd6b00b6d9
+  metadata.gz: 6e6035336e6cf7a1d850dd33bf565a54e8c32283a40992e496f94ec516ba8a1a054ea283b5dfb16d5bf700efc296b37a85cb19827f7154b0b9756b6baa123d53
+  data.tar.gz: 36bac381a140a15803418711682e5b4f82c1442703d467042f0d3a76db311ed2da675846792333582465aff98e4f6647469d03bc11d5dfaf1a9c542ccfd6595e

data/README.md

@@ -1,22 +1,23 @@
 # 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)
 
 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 : 
+<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)
-* [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](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
@@ -24,7 +25,7 @@ gem install ruby-igv
 
 ## Quickstart
 
-<img src="https://user-images.githubusercontent.com/5798442/182623864-a9fa59aa-abb9-4cb1-8311-2b3479b7414e.png" width="300" align="left">
+<img src="https://user-images.githubusercontent.com/5798442/182623864-a9fa59aa-abb9-4cb1-8311-2b3479b7414e.png" width="300" align="right">
 
 ```ruby
 require 'igv'
@@ -42,9 +43,9 @@ igv.snapshot 'region.png'
 
 ## Usage
 
-### commands
+### IGV 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.
+The commonly used commands in IGV are summarized in the official [list of batch commands](https://igv.org/doc/desktop/#UserGuide/tools/batch/#script-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
@@ -52,16 +53,35 @@ igv.commands # Show the IGV command reference in your browser
 
 ### docs
 
-See [docs](https://rubydoc.info/gems/ruby-igv/IGV). Not all commands are implemented in Ruby.
+See [yard docs](https://kojix2.github.io/ruby-igv/).  
+Most IGV batch commands are available as Ruby methods of the same name.  
+If you need to use a command not directly wrapped, you can use the `send` method as shown below.
 
 ### send
 
-Commands that are not implemented can be sent using the send method.
+You can send any IGV batch command using the `send` method.
 
 ```ruby
 igv.send("maxPanelHeight", 10)
+igv.send("scrollToTop")
+igv.send("setAccessToken", "token", "host")
 ```
 
+To avoid unexpected behavior, ruby-igv does not use the `method_missing` mechanism.
+
+### Supported IGV batch commands
+
+Most official IGV batch commands are available as Ruby methods, including:
+
+- collapse, color_by, echo, exit, expand, genome, goto, group, load, max_panel_height, new, overlay, preference, region, save_session, scroll_to_top, separate, set_alt_color, set_color, set_data_range, set_log_scale, set_sequence_strand, set_sequence_show_translation, set_sleep_interval, set_track_height, snapshot_dir, snapshot, sort, squish, viewaspairs, set_access_token, clear_access_tokens
+
+See the [official IGV batch command list](https://igv.org/doc/desktop/#UserGuide/tools/batch/#script-commands) for details.
+
+### Return values and error handling
+
+Most methods return the IGV response string (e.g. "OK" or an error message).  
+You can check the return value to handle errors or confirm success.
+
 ### Launch IGV
 
 Launch IGV from Ruby script.
@@ -70,11 +90,39 @@ Launch IGV from Ruby script.
 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
@@ -90,20 +138,22 @@ igv.kill        # kill group pid created with IGV.start
 
 ## Contributing
 
-* [Report bugs](https://github.com/kojix2/ruby-igv/issues)
-* Fix bugs and submit [pull requests](https://github.com/kojix2/ruby-igv/pulls)
-* Write, clarify, or fix documentation
-* Suggest or add new features
+- [Report bugs](https://github.com/kojix2/ruby-igv/issues)
+- Fix bugs and submit [pull requests](https://github.com/kojix2/ruby-igv/pulls)
+- Write, clarify, or fix documentation
+- 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.
 ```
 
 ## Acknowledgement
+
 This gem is strongly inspired by a Python script developed by Brent Pedersen.
-* [brentp/bio-playground/igv](https://github.com/brentp/bio-playground).
+
+- [brentp/bio-playground/igv](https://github.com/brentp/bio-playground).
 
 ## License
 

data/lib/igv/version.rb

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

data/lib/igv.rb

@@ -1,25 +1,27 @@
 # frozen_string_literal: true
 
 require 'igv/version'
+require 'uri'
 require 'socket'
 require 'fileutils'
 
-# The Integrative Genomics Viewer (IGV)
-# https://software.broadinstitute.org/software/igv/
+# The Integrative Genomics Viewer (IGV) Ruby client.
+# Provides a Ruby interface to control IGV via its batch command protocol.
+#
+# @see https://igv.org/doc/desktop/#UserGuide/tools/batch/#script-commands IGV Batch Script Documentation
 class IGV
   class Error < StandardError; end
 
   attr_reader :host, :port, :history
 
-  # Create IGV client object
+  # 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
-
+  # @param host [String] Hostname or IP address of IGV server.
+  # @param port [Integer] Port number of IGV server.
+  # @param snapshot_dir [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?
+    raise ArgumentError, 'IGV#initialize does not accept a block.' if block_given?
 
     @host = host
     @port = port
@@ -27,15 +29,14 @@ class IGV
     @history = []
   end
 
-  # Create IGV object and connect to IGV server
+  # 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
-
+  # @param host [String] Hostname or IP address of IGV server.
+  # @param port [Integer] Port number of IGV server.
+  # @param snapshot_dir [String] Directory path to save snapshots.
+  # @yield [IGV] IGV client object.
+  # @return [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
@@ -49,23 +50,27 @@ class IGV
     igv
   end
 
+  # Check if a port is open.
+  # @param port [Integer] Port number.
+  # @return [Boolean, nil] true if open, false if closed, nil if unknown.
   def self.port_open?(port)
-    !system("lsof -i:#{port}", out: '/dev/null')
+    system("lsof -i:#{port}", out: '/dev/null')
   end
   private_class_method :port_open?
 
-  # Launch IGV from ruby script
+  # 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
-
+  # @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.
+  # @note This will spawn a new IGV process and connect to it.
   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"
+    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)
@@ -77,43 +82,49 @@ class IGV
       break if line.include? "Listening on port #{port}"
     end
     puts "\e[0m"
-    igv = open(port: port, snapshot_dir: snapshot_dir)
+    igv = self.open(port: port, snapshot_dir: snapshot_dir)
     igv.instance_variable_set(:@pgid_igv, pgid_igv)
     igv
   end
 
-  # Kill IGV process by process group id
-
+  # Kill IGV process by process group id.
+  #
+  # @note Only works for IGV processes started by IGV.start.
+  # @return [nil] Kills the IGV process if started by this client, otherwise does nothing.
   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.'
+      warn '[ruby-igv] 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
+      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
 
-  # Connect to IGV server
-
+  # Connect to IGV server.
+  #
+  # @param host2 [String] Hostname or IP address.
+  # @param port2 [Integer] Port number.
+  # @param connect_timeout [Integer, nil] Timeout in seconds.
+  # @return [self] Returns self for method chaining.
   def connect(host2 = @host, port2 = @port, connect_timeout: nil)
     @socket&.close
     @socket = Socket.tcp(host2, port2, connect_timeout: connect_timeout)
+    self
   end
 
-  # Close the socket.
-  # This method dose not exit IGV.
-
+  # Close the socket. This does not exit IGV.
+  # @return [nil] Closes the socket and returns nil.
   def close
     @socket&.close
+    nil
   end
 
+  # Check if the socket is closed.
+  # @return [Boolean]
   def closed?
     return true if @socket.nil?
 
@@ -122,18 +133,19 @@ class IGV
 
   # Send batch commands to IGV.
   #
-  # @param *cmds [String, Symbol, Numeric] batch commands
-  # @return [String] response from IGV
-
+  # @param cmds [Array<String, Symbol, Numeric>] Batch commands.
+  # @return [String] Response from IGV.
+  # @example
+  #   igv.send("goto", "chr1:1000-2000")
   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(' ')
@@ -144,40 +156,42 @@ class IGV
 
   # Syntactic sugar for IGV commands that begin with set.
   #
+  # @param cmd [String, Symbol] Batch command name (without "set" prefix).
+  # @param params [Array<String, Symbol, Numeric>] Parameters for the command.
+  # @return [String] Response from IGV.
   # @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
-
+  # Open IGV batch command documentation in the browser.
   def commands
     require 'launchy'
-    Launchy.open('https://github.com/igvteam/igv/wiki/Batch-commands')
+    Launchy.open('https://igv.org/doc/desktop/#UserGuide/tools/batch/#script-commands')
   end
 
-  # Writes the value of "param" back to the response
-  # @note IGV Batch command
+  # Write the value of "param" back to the response.
   #
-  # @param param [String] The parameter to echo.
+  # @note IGV Batch command: echo
+  # @param param [String, nil] The parameter to echo.
   # @return [String] The value of "param". If param is not specified, "echo".
-
+  # @example
+  #   igv.echo("Hello!") #=> "Hello!"
   def echo(param = nil)
     send :echo, param
   end
 
-  # Selects a genome by id, or loads a genome (or indexed fasta) from the supplied path.
-  # @note IGV Batch command
+  # Select a genome by id, or load a genome (or indexed fasta) from the supplied path.
   #
-  # @param name_or_path [String] The genome to load
-
+  # @note IGV Batch command: genome
+  # @param name_or_path [String] Genome id (e.g. "hg19") or path to fasta/indexed genome.
+  # @return [String] IGV response.
+  # @example
+  #   igv.genome("hg19")
+  #   igv.genome("/path/to/genome.fa")
   def genome(name_or_path)
     path = File.expand_path(name_or_path)
     if File.exist?(path)
@@ -187,12 +201,15 @@ class IGV
     end
   end
 
-  # Loads a data or session file by specifying a full path to a local file or a URL.
-  # @note IGV Batch command
+  # Load 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
-
+  # @note IGV Batch command: load
+  # @param path_or_url [String] Path to a local file or a URL.
+  # @param index [String, nil] Optional index file path.
+  # @return [String] IGV response.
+  # @example
+  #   igv.load("http://example.com/data.bam")
+  #   igv.load("/path/to/data.bam", index: "/path/to/data.bai")
   def load(path_or_url, index: nil)
     path_or_url = if URI.parse(path_or_url).scheme
                     path_or_url
@@ -201,29 +218,42 @@ 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
+  # Go to the specified location or list of loci.
   #
-  # @param location [String] The location to go to.
-
+  # @note IGV Batch command: goto
+  # @param position [String] Locus or list of loci (e.g. "chr1:1000-2000").
+  # @return [String] IGV response.
+  # @example
+  #   igv.goto("chr1:1000-2000")
   def goto(position)
     send :goto, position
   end
   alias go goto
 
-  # Defines a region of interest bounded by the two loci
-  # @note IGV Batch command
+  # Define 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
-
+  # @note IGV Batch command: region
+  # @param chr [String] Chromosome name.
+  # @param start [Integer] Start position.
+  # @param end_ [Integer] End position.
+  # @return [String] IGV response.
+  # @example
+  #   igv.region("chr1", 100, 200)
   def region(chr, start, end_)
     send :region, chr, start, end_
   end
 
+  # Sort alignment or segmented copy number tracks.
+  #
+  # @note IGV Batch command: sort
+  # @param option [String] Sort option (e.g. "base", "position", "strand", "quality", "sample", "readGroup").
+  # @return [String] IGV response.
+  # @example
+  #   igv.sort("position")
   def sort(option = 'base')
     vop = %w[base position strand quality sample readGroup]
     raise "options is one of: #{vop.join(', ')}" unless vop.include? option
@@ -231,66 +261,97 @@ class IGV
     send :sort, option
   end
 
-  # Expands the given track.
-  # @note IGV Batch command
+  # Expand a given track. If not specified, expands all tracks.
   #
-  # @param track [String] The track to expand.
-  #                       If not specified, expands all tracks.
-
+  # @note IGV Batch command: expand
+  # @param track [String, nil] Track name (optional).
+  # @return [String] IGV response.
+  # @example
+  #   igv.expand
+  #   igv.expand("track1")
   def expand(track = nil)
     send :expand, track
   end
 
-  # Collapses a given track.
-  # @note IGV Batch command
+  # Collapse a given track. If not specified, collapses all tracks.
   #
-  # @param track [String] The track to collapse.
-  #                       If not specified, collapses all tracks.
-
+  # @note IGV Batch command: collapse
+  # @param track [String, nil] Track name (optional).
+  # @return [String] IGV response.
+  # @example
+  #   igv.collapse
+  #   igv.collapse("track1")
   def collapse(track = nil)
     send :collapse, track
   end
 
-  # Squish a given track.
-  # @note IGV Batch command
+  # Squish a given track. If not specified, squishes all annotation tracks.
   #
-  # @param track [String] The track to squish.
-  #                       If not specified, squishes all tracks.
-
+  # @note IGV Batch command: squish
+  # @param track [String, nil] Track name (optional).
+  # @return [String] IGV response.
+  # @example
+  #   igv.squish
+  #   igv.squish("track1")
   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.
-
+  # @note IGV Batch command: viewaspairs
+  # @param track [String, nil] Track name (optional).
+  # @return [String] IGV response.
+  # @example
+  #   igv.viewaspairs
+  #   igv.viewaspairs("track1")
   def viewaspairs(track = nil)
     send :viewaspairs, track
   end
 
-  # @note IGV Batch command
+  # Create a new session. Unloads all tracks except the default genome annotations.
+  #
+  # @note IGV Batch command: new
+  # @return [self] Returns self for method chaining.
+  # @example
+  #   igv.new
+  def new
+    send :new
+    self
+  end
 
+  # Clear all loaded tracks and data.
+  #
+  # @note IGV Batch command: clear
+  # @return [self] Returns self for method chaining.
+  # @example
+  #   igv.clear
   def clear
     send :clear
+    self
   end
 
   # Exit (close) the IGV application and close the socket.
-  # @note IGV Batch command (modifyed)
-
+  #
+  # @note IGV Batch command: exit
+  # @return [nil] Exits IGV and closes the socket.
+  # @example
+  #   igv.exit
   def exit
     send :exit
     @socket.close
+    nil
   end
   alias quit exit
 
-  #	Sets the directory in which to write images.
-  # Retruns the current snapshot directory if no argument is given.
-  # @note IGV Batch command (modified)
+  # Set or get the directory in which to write images (snapshots).
   #
-  # @param path [String] The path to the directory.
-
+  # @note IGV Batch command: snapshotDirectory
+  # @param dir_path [String, nil] Directory path. If nil, returns current snapshot directory.
+  # @return [String] IGV response or current directory.
+  # @example
+  #   igv.snapshot_dir("/tmp/snapshots")
+  #   igv.snapshot_dir #=> "/tmp/snapshots"
   def snapshot_dir(dir_path = nil)
     return @snapshot_dir if dir_path.nil?
 
@@ -304,60 +365,269 @@ class IGV
 
   private def snapshot_dir_internal(dir_path)
     dir_path = File.expand_path(dir_path)
+    warn "[ruby-igv] Directory #{dir_path} does not exist. Creating it." unless File.exist?(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.
+  # Save a snapshot of the IGV window to an image file.
   #
-  # @param file_path [String] The path to the image file.
+  # @note IGV Batch command: snapshot
+  # @param file_name [String, nil] Name of the image file. If nil, uses the current locus.
+  #   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.
+  #   Passing a path might work, but is not recommended.
+  # @example
+  #   igv.snapshot("region.png")
+  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 == "."
 
-  def snapshot(file_path = nil)
-    return send(:snapshot) if file_path.nil?
+    # 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.expand_path(dir_path)
+    else
+      dir_path = File.expand_path(File.join(@snapshot_dir, dir_path))
+    end
 
-    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
+    
+    # Only change directory if needed
+    if dir_path == @snapshot_dir
+      send(:snapshot, filename)
     else
-      send :snapshot, filename
+      # 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
 
   # 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
-
+  # @note IGV Batch command: preference
+  # @param key [String] Preference key.
+  # @param value [String] Preference value.
+  # @return [String] IGV response.
+  # @see https://raw.githubusercontent.com/igvteam/igv/master/src/main/resources/org/broad/igv/prefs/preferences.tab
+  # @example
+  #   igv.preferences("SAM.READ_GROUP_COLOR", "sample")
   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
-
+  # @note IGV Batch command: saveSession
+  # @param file_path [String] Path to the session file.
+  # @return [String] IGV response.
+  # @example
+  #   igv.save_session("session.xml")
   def save_session(file_path)
     file_path = File.expand_path(file_path)
     send :saveSession, file_path
   end
+
+  # Set the track "altColor", used for negative values in a wig track or negative strand features.
+  #
+  # @note IGV Batch command: setAltColor
+  # @param color [String] Color string (e.g. "255,0,0" or "FF0000").
+  # @param track [String] Track name.
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_alt_color("255,0,0", "track1")
+  def set_alt_color(color, track)
+    send :setAltColor, color, track
+  end
+
+  # Set the track color.
+  #
+  # @note IGV Batch command: setColor
+  # @param color [String] Color string (e.g. "255,0,0" or "FF0000").
+  # @param track [String] Track name.
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_color("FF0000", "track1")
+  def set_color(color, track)
+    send :setColor, color, track
+  end
+
+  # Set the data range (scale) for all numeric tracks, or a specific track.
+  #
+  # @note IGV Batch command: setDataRange
+  # @param range [String] Range string (e.g. "0,100" or "auto").
+  # @param track [String] Track name.
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_data_range("0,100", "track1")
+  def set_data_range(range, track)
+    send :setDataRange, range, track
+  end
+
+  # Set the data scale to log (true) or linear (false).
+  #
+  # @note IGV Batch command: setLogScale
+  # @param bool [Boolean] true for log scale, false for linear.
+  # @param track [String] Track name (optional).
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_log_scale(true, "track1")
+  def set_log_scale(bool, track)
+    bool = 'true' if bool == true
+    bool = 'false' if bool == false
+    send :setLogScale, bool, track
+  end
+
+  # Set the sequence strand to positive (+) or negative (-).
+  #
+  # @note IGV Batch command: setSequenceStrand
+  # @param strand [String] "+" or "-".
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_sequence_strand("+")
+  def set_sequence_strand(strand)
+    send :setSequenceStrand, strand
+  end
+
+  # Show or hide the 3-frame translation rows of the sequence track.
+  #
+  # @note IGV Batch command: setSequenceShowTranslation
+  # @param bool [Boolean] true to show, false to hide.
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_sequence_show_translation(true)
+  def set_sequence_show_translation(bool)
+    bool = 'true' if bool == true
+    bool = 'false' if bool == false
+    send :setSequenceShowTranslation, bool
+  end
+
+  # Set a delay (sleep) time in milliseconds between successive commands.
+  #
+  # @note IGV Batch command: setSleepInterval
+  # @param ms [Integer] Milliseconds to sleep.
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_sleep_interval(200)
+  def set_sleep_interval(ms)
+    send :setSleepInterval, ms
+  end
+
+  # Set the specified track's height in integer units.
+  #
+  # @note IGV Batch command: setTrackHeight
+  # @param height [Integer] Height in pixels.
+  # @param track [String] Track name.
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_track_height(50, "track1")
+  def set_track_height(height, track)
+    send :setTrackHeight, height, track
+  end
+
+  # Set the number of vertical pixels (height) of each panel to include in image.
+  #
+  # @note IGV Batch command: maxPanelHeight
+  # @param height [Integer] Height in pixels.
+  # @return [String] IGV response.
+  # @example
+  #   igv.max_panel_height(2000)
+  def max_panel_height(height)
+    send :maxPanelHeight, height
+  end
+
+  # Set the "color by" option for alignment tracks.
+  #
+  # @note IGV Batch command: colorBy
+  # @param option [String] Color by option (e.g. "SAMPLE", "READ_GROUP", "TAG", ...).
+  # @param tag [String, nil] Tag name (required for option "TAG").
+  # @return [String] IGV response.
+  # @example
+  #   igv.color_by("SAMPLE")
+  #   igv.color_by("TAG", "NM")
+  def color_by(option, tag)
+    send :colorBy, option, tag
+  end
+
+  # Group alignments by the specified option.
+  #
+  # @note IGV Batch command: group
+  # @param option [String] Group option (e.g. "SAMPLE", "READ_GROUP", "TAG", ...).
+  # @param tag [String, nil] Tag name or position (required for option "TAG").
+  # @return [String] IGV response.
+  # @example
+  #   igv.group("SAMPLE")
+  #   igv.group("TAG", "NM")
+  def group(option, tag)
+    send :group, option, tag
+  end
+
+  # Overlay a list of tracks.
+  #
+  # @note IGV Batch command: overlay
+  # @param overlaid_track [String] The track to overlay.
+  # @param tracks [Array<String>] List of tracks to overlay.
+  # @return [String] IGV response.
+  # @example
+  #   igv.overlay("track1", "track2", "track3")
+  def overlay(overlaid_track, *tracks)
+    send :overlay, overlaid_track, *tracks
+  end
+
+  # Scroll all panels to the top of the view.
+  #
+  # @note IGV Batch command: scrollToTop
+  # @return [String] IGV response.
+  # @example
+  #   igv.scroll_to_top
+  def scroll_to_top
+    send :scrollToTop
+  end
+
+  # Separate an overlaid track into its constituitive tracks.
+  #
+  # @note IGV Batch command: separate
+  # @param overlaid_track_name [String] The name of the overlaid track to separate.
+  # @return [String] IGV response.
+  # @example
+  #   igv.separate("track1")
+  def separate(overlaid_track_name)
+    send :separate, overlaid_track_name
+  end
+
+  # Set an access token to be used in an Authorization header for all requests to host.
+  #
+  # @note IGV Batch command: setAccessToken
+  # @param token [String] The access token.
+  # @param host [String, nil] The host to use the token for (optional).
+  # @return [String] IGV response.
+  # @example
+  #   igv.set_access_token("mytoken", "example.com")
+  def set_access_token(token, host = nil)
+    send :setAccessToken, token, host
+  end
+
+  # Clears all access tokens.
+  #
+  # @note IGV Batch command: clearAccessTokens
+  # @return [String] IGV response.
+  # @example
+  #   igv.clear_access_tokens
+  def clear_access_tokens
+    send :clearAccessTokens
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby-igv
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.10
 platform: ruby
 authors:
 - kojix2
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: launchy
@@ -95,7 +94,6 @@ homepage: https://github.com/kojix2/ruby-igv
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -103,15 +101,14 @@ 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.6.7
 specification_version: 4
 summary: Control IGV (Integrative Genomics Viewer) with Ruby.
 test_files: []