dcd 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a042ccc8e4a657dec774f8aef387bca1e6d9bb91
+  data.tar.gz: 2f9be85b8c3ac648567f6313308a89e369b85e35
+SHA512:
+  metadata.gz: c281f10fbbeb7ed570212f4accb0775766fb98dff1479273b50771554ad68c9404b0e9a7c440d783e3bb5686ee989873f71803978ff221c3d4e1482fe12c778b
+  data.tar.gz: 37a27f524072ed45e048a254ba0d531d74e1709fb5a7380499a7a355fc1be4d7d59fea63e8837e20454b2c28b3bf6df1b6565557abb58642b5f3ca4c10d693d8

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1 @@
+source 'https://rubygems.org'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Joshua Smock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+# DCD
+
+DCD is a Ruby library for processing CHARMM and X-PLOR style binary trajectory files, aka DCD files. Based on the [`matdcd`](http://www.ks.uiuc.edu/Development/MDTools/matdcd/) and [VMD DCD plugin](http://www.ks.uiuc.edu/Research/vmd/plugins/doxygen/dcdplugin_8c-source.html), DCD parses and allows access to various metadata and atom information for use in scripts and automated environments where the numeric positions of the atoms is useful. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'dcd'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dcd
+
+
+## Usage
+
+DCD requires an io pointer to a binary DCD file upon initialization, and can be used in two ways: instant loading and lazy loading. The difference between instant and lazy loading is passing in an optional second argument upon initialization.
+
+```ruby
+> require('dcd')
+=> true
+> dcd_pointer = File.read('1407.dcd')
+=> #<File:./1407.dcd>
+> lazy_load = false
+=> false
+> my_dcd = DCD.new(dcd_pointer, lazy_load)
+=> ... 
+```
+
+Once loaded, you have access to the metadata, including the `nstep`, `nset`, and `step`, the title, and the frames with atom coordinates in `x`, `y`, `z`, and `w` if using a 4th dimensional DCD.
+
+## TODO
+
+1. Currently test coverage on this library is limited, especially around fixed atoms and CHARMM 4th dimensional parameters. If you DCDs, especially those with the aforementioned features, please make a pull request or an issue with the necessary files attached.
+2. Examples.
+
+## License
+
+MIT. See LICENSE for more information.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/dcd.gemspec

@@ -0,0 +1,20 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "dcd"
+  spec.version       = "0.0.1"
+  spec.authors       = ["Joshua Smock"]
+  spec.email         = ["joshuasmock@gmail.com"]
+
+  spec.summary       = %q{DCD is a simple parser for CHARMM and X-PLOR binary trajectory files}
+  spec.homepage      = "https://github.com/jo-sm/dcd"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.12.a"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/dcd.rb

@@ -0,0 +1,225 @@
+class DCD
+  attr_reader :metadata, :title, :frames
+
+	def initialize(io, lazy=false)
+		@io_pointer = io
+    @read_length = 0
+    @type = ''
+    @endian = ''
+    @title = ''
+    @metadata = {}
+    @frames = {}
+    @valid = true
+
+		if !lazy
+			read_header
+      read_atoms
+		end
+	end
+
+  # Loads the header, which determines endianness
+  # and the initial metadata about the DCD file
+	def read_header
+    determine_endianness
+    gather_metadata
+    read_title
+    read_atoms_metadata
+	end
+
+  def read_atoms
+    @frames[:x], @frames[:y], @frames[:z], @frames[:w] = [], [], [], []
+
+    @metadata[:nset].times do |i|
+      if @metadata[:extrablock]
+        # Unit cell info
+        i = @io_pointer.read(@read_length + 48 + @read_length).unpack("L#{endian}*")[0]
+        warn "Incorrect frame size in unit cell for step #{i}" if i[0] != i[-1]
+        # TODO: Process this data
+      end
+
+      # Treat first frame and fixed atoms DCD files differently
+      if i == 0 or @metadata[:num_fixed] == 0
+        # Read each frame
+        read_coord(:x)
+        read_coord(:y)
+        read_coord(:z)
+        read_coord(:w) if @metadata[:w_coords]
+      else
+        read_fixed_coord(:x)
+        read_fixed_coord(:y)
+        read_fixed_coord(:z)
+        read_coord(:w) if @metadata[:w_coords]
+      end
+    end
+  end
+
+  def print
+    if @title == '' or !@frames[:x]
+      warn "DCD has not been processed" 
+      return nil
+    end
+
+    puts "#{@metadata[:is_charmm] ? 'CHARMM' : 'X-PLOR'} #{@type == 'l' ? '32' : '64'}-bit Trajectory File #{@endian == '>' ? 'Big' : 'Little'} Endian"
+    puts "#{@title}"
+    puts "Nset: #{@metadata[:nset]}"
+    puts "Istart: #{@metadata[:istart]}"
+    puts "Nsavc: #{@metadata[:nsavc]}"
+    puts "Nstep: #{@metadata[:nstep]}"
+    puts "Step size: #{@metadata[:step]} picoseconds"
+    puts "Number of atoms per frame: #{@metadata[:num_atoms]}"
+    @frames[:x].each_with_index do |coords, i|
+      puts "Frame #{i}  coordinates"
+      coords.each_with_index do |coord, j|
+        puts "(#{j})\t\t\t#{@frames[:x][i][j]}\t\t#{@frames[:y][i][j]}\t\t#{@frames[:z][i][j]}"
+      end
+    end
+  end
+
+  private
+
+  def read_coord(coord)
+    coord_block_size = @io_pointer.read(@read_length).unpack("#{@type}#{@endian}")[0]
+    @frames[coord].push(@io_pointer.read(coord_block_size).unpack('f*'))
+    coord_check = @io_pointer.read(@read_length).unpack("#{@type}#{@endian}")[0]
+
+    warn "Invalid block size for #{coord} coords" if coord_block_size != coord_check
+  end
+
+  def read_fixed_coord(coord)
+    num_free = @metadata[:num_atoms] - @metadata[:num_fixed]
+
+    # Fixed atom coordinates are 4 bytes in length,
+    # and there are `num_free` amount of coordinates per block
+    fixed_coord_block_size = @io_pointer.read(@read_length).unpack("#{@type}#{@endian}")[0]
+    free_atom_coords = @io_pointer.read(4 * num_free).unpack('f*')
+    fixed_coord_check = @io_pointer.read(@read_length).unpack("#{@type}#{@endian}")[0]
+
+    raise StandardError, "Invalid DCD, fixed coordinate check did not match" if fixed_coord_block_size != fixed_coord_check
+
+    # Now, a copy of the first frame is made and the trajectory changes are overwritten
+    # with the free atom coordinates
+    new_coords = @coord[coord][0].clone
+
+    num_free.times do |i|
+      new_coords[@metadata[:free_indexes][i]] = free_atom_coords[i]
+    end
+
+    @coord[coord].push(new_coords)
+  end
+
+  # Determines endianness of DCD file
+  def determine_endianness
+    # Ensure that the pointer is as position 0
+    @io_pointer.seek(0)
+    initial_data = @io_pointer.read(4)
+
+    # Default to 32 bit for these values
+    @read_length = 4
+    @type = 'l'
+    
+    # Determine if DCD file is 32 bit or 64 bit
+    puts initial_data.unpack('L>'), initial_data.unpack('L<')
+    if initial_data.unpack('L>')[0] == 84
+      # Big endian
+      @endian = '>'
+    elsif initial_data.unpack('L<')[0] == 84
+      # Little endian
+      @endian = '<'
+    end
+
+    puts @endian, @type
+
+    # If the endianness is not set, then the DCD file is 64 bit
+    if @endian == ''
+      @type = 'q'
+
+      second_byte = @io_pointer.read(4)
+      initial_data = initial_data + second_byte
+
+      @read_length = 8
+
+      if initial_data.unpack('q>')[0] == 84
+        @endian = '>'
+      elsif initial_data.unpack('q<')[0] == 84
+        @endian = '<'
+      end
+    end
+
+    if @endian == ''
+      @valid = false
+      raise StandardError, "Invalid DCD file"
+    end
+
+    if @io_pointer.read(4) != 'CORD'
+      @valid = false
+      raise StandardError, "Invalid DCD file"
+    end
+  end
+
+  # Gathers metadata, including if file is CHARMM format,
+  def gather_metadata
+    @io_pointer.seek(@read_length + 4)
+    metadata_raw = @io_pointer.read(80)
+
+    # The next @read_length amount of data when unpacked should equal 84
+    check = @io_pointer.read(@read_length).unpack("#{@type}#{@endian}")[0]
+    raise StandardError, "Invalid DCD format, expected 84 but saw #{check}" if check != 84
+
+    unpacked_meta = metadata_raw.unpack("L#{@endian}9a4L#{@endian}*")
+
+    @metadata[:is_charmm] = unpacked_meta[-1] != 0 # 76 - 79
+    @metadata[:nset] = unpacked_meta[0] # 0-3
+    @metadata[:istart] = unpacked_meta[1] # 4-7
+    @metadata[:nsavc] = unpacked_meta[2] # 8-11
+    @metadata[:nstep] = unpacked_meta[3] # 12-15 # not present in XPLOR files - is 0
+    # unpacked_meta[4] - unpacked_meta[7] are zeros
+    @metadata[:num_fixed] = unpacked_meta[8] # 32 - 35
+    @metadata[:step_size] = unpacked_meta[9].unpack(@metadata[:is_charmm] ? (@endian == '>' ? 'g' : 'e') : (@endian == '>' ? 'G' : 'E'))[0] # 36 - 39
+    @metadata[:charmm_extrablock] = unpacked_meta[10] != 0 # 40 - 43
+    @metadata[:w_coords] = unpacked_meta[11] == 1 # 44 - 47
+  end
+
+  def read_title
+    @io_pointer.seek(@read_length + 80 + 4 + @read_length)
+    title_metadata = @io_pointer.read(@read_length*2).unpack("#{@type}#{@endian}2")
+
+    size = title_metadata[0]
+    num_lines = title_metadata[1]
+
+    puts size, num_lines
+
+    # VMD's plugin notes: There are certain programs such as Vega ZZ that write an incorrect DCD file header. Check for these
+    if num_lines < 0
+      raise StandardError, "Invalid DCD file, negative title length"
+    elsif num_lines > 1000
+      num_lines = 0
+      num_lines = 2 if num_lines == 1095062083 # Vega ZZ
+      warn "Invalid title length, setting to #{num_lines}. May result in invalid subsequent IO reads"
+    end
+
+    title_data = @io_pointer.read(num_lines*80 + @read_length*3).unpack("a#{num_lines*80}#{@type}#{@endian}2l#{@endian}")
+    @title = title_data[0]
+    size_check = title_data[1]
+
+    raise StandardError, "Invalid DCD format, size mismatch" if size != size_check
+    raise StandardError, "Invalid DCD format, invalid check" if title_data[2] != 4
+  end
+
+  # This method does not know where to read, since the title can be variable length
+  # So this must be called after .read_title
+  def read_atoms_metadata
+    @metadata[:num_atoms] = @io_pointer.read(@read_length).unpack("#{@type}#{@endian}")[0]
+
+    if @metadata[:num_fixed] != 0
+      num_free_data = @io_pointer.read(@read_length + @metadata[:num_atoms] - @metadata[:num_fixed]).unpack("L#{@endian}*")
+
+      num_free = num_free_data[0]
+      @metadata[:free_indexes] = num_free_data[1..-2]
+      num_free_check = num_free_data[-1]
+
+      raise StandardError, "Invalid DCD format, fixed atoms check failed" if num_free != num_free_check
+    end
+
+    @metadata[:body_start] = @io_pointer.pos
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: dcd
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Joshua Smock
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.12.a
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.12.a
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: 
+email:
+- joshuasmock@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- dcd.gemspec
+- lib/dcd.rb
+homepage: https://github.com/jo-sm/dcd
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.5
+signing_key: 
+specification_version: 4
+summary: DCD is a simple parser for CHARMM and X-PLOR binary trajectory files
+test_files: []