lazar 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2211d5cf1767b241583acff9a22379b56a5d8f1c
-  data.tar.gz: 923a3d00d5c78fd77a2153c973c5e3935c939eda
+  metadata.gz: c17dc3fb7cae4c75aca1be7c0a6286cfbc3f22ce
+  data.tar.gz: 5b9fb4bae6230e427188e0c8e34153fd5a6efa0a
 SHA512:
-  metadata.gz: 2a366bae505c427a72211df4d59c7f296ead656bfe3f42db0fb6bb2dc3885028c70ba9df0aa7778c0bd78acdbd7b2939417caafd342a535c4954a34fef410c8d
-  data.tar.gz: 04fd93e7ab52517d338e6005223fe22b498d74be324f8dc6ef2e3a4d4a843202abc9224ff55e8ba053ce7a16a6a76301437f4fc061ac2719d65ff3afa392396a
+  metadata.gz: 7cae1ffb410cd9a2d1afd1516ebf99499e2b2447af8707a4381adb652cb59711e1875c11e80cec8fc101f8368224ab21bc378f685b0084ab29c631d798145dca
+  data.tar.gz: d01273022852b6a0b59941a0e881a85ed1400a984912018d97fc137f8ab602cff1fd6f5fb42a65df5d9375cb43ca2809adeefbde7a0e385fd832c189df0da031

data/README.md

@@ -26,10 +26,73 @@ Installation
 
   The output should give you more verbose information that can help in debugging (e.g. to identify missing libraries).
 
+Tutorial
+--------
+
+Execute the following commands either from an interactive Ruby shell or a Ruby script:
+
+### Create and use `lazar` models for small molecules
+
+#### Create a training dataset
+
+  Create a CSV file with two columns. The first line should contain either SMILES or InChI (first column) and the endpoint (second column). The first column should contain either the SMILES or InChI of the training compounds, the second column the training compounds toxic activities (qualitative or quantitative). Use -log10 transformed values for regression datasets. Add metadata to a JSON file with the same basename containing the fields "species", "endpoint", "source" and "unit" (regression only). You can find example training data at [Github](https://github.com/opentox/lazar-public-data).
+
+#### Create and validate a `lazar` model with default algorithms and parameters
+
+  `validated_model = Model::Validation.create_from_csv_file EPAFHM_log10.csv`
+
+  This command will create a `lazar` model and validate it with three independent 10-fold crossvalidations.
+
+#### Inspect crossvalidation results
+
+  `validated_model.crossvalidations`
+
+#### Predict a new compound
+
+  Create a compound
+
+  `compound = Compound.from_smiles "NC(=O)OCCC"`
+
+  Predict Fathead Minnow Acute Toxicity
+
+  `validated_model.predict compound`
+
+#### Experiment with other algorithms
+
+  You can pass algorithms parameters to the `Model::Validation.create_from_csv_file` command. The [API documentation](http://rdoc.info/gems/lazar) provides detailed instructions.
+
+### Create and use `lazar` nanoparticle models
+
+#### Create and validate a `nano-lazar` model from eNanoMapper with default algorithms and parameters
+
+  `validated_model = Model::Validation.create_from_enanomapper`
+
+  This command will mirror the eNanoMapper database in the local database, create a `nano-lazar` model and validate it with five independent 10-fold crossvalidations.
+
+#### Inspect crossvalidation results
+
+  `validated_model.crossvalidations`
+
+#### Predict nanoparticle toxicities
+
+  Choose a random nanoparticle from the "Potein Corona" dataset
+  ```
+  training_dataset = Dataset.where(:name => "Protein Corona Fingerprinting Predicts the Cellular Interaction of Gold and Silver Nanoparticles").first
+  nanoparticle = training_dataset.substances.shuffle.first
+  ```
+
+  Predict the "Net Cell Association" endpoint
+
+  `validated_model.predict nanoparticle`
+
+#### Experiment with other datasets, endpoints and algorithms
+
+  You can pass training_dataset, prediction_feature and algorithms parameters to the `Model::Validation.create_from_enanomapper` command. The [API documentation](http://rdoc.info/gems/lazar) provides detailed instructions. Detailed documentation and validation results can be found in this [publication](https://github.com/enanomapper/nano-lazar-paper/blob/master/nano-lazar.pdf).
+
 Documentation
 -------------
 * [API documentation](http://rdoc.info/gems/lazar)
 
 Copyright
 ---------
-Copyright (c) 2009-2016 Christoph Helma, Martin Guetlein, Micha Rautenberg, Andreas Maunz, David Vorgrimmler, Denis Gebele. See LICENSE for details.
+Copyright (c) 2009-2017 Christoph Helma, Martin Guetlein, Micha Rautenberg, Andreas Maunz, David Vorgrimmler, Denis Gebele. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

data/lib/algorithm.rb

@@ -2,6 +2,7 @@ module OpenTox
 
   module Algorithm 
 
+    # Execute an algorithm with parameters
     def self.run algorithm, parameters=nil
       klass,method = algorithm.split('.')
       Object.const_get(klass).send(method,parameters) 

data/lib/caret.rb

@@ -1,9 +1,17 @@
 module OpenTox
   module Algorithm
     
+    # Ruby interface for the R caret package
+    # Caret model list: https://topepo.github.io/caret/modelList.html
     class Caret
-      # model list: https://topepo.github.io/caret/modelList.html
 
+      # Create a local R caret model and make a prediction
+      # @param [Array<Float,Bool>] dependent_variables
+      # @param [Array<Array<Float,Bool>>] independent_variables
+      # @param [Array<Float>] weights
+      # @param [String] Caret method
+      # @param [Array<Float,Bool>] query_variables
+      # @return [Hash]
       def self.create_model_and_predict dependent_variables:, independent_variables:, weights:, method:, query_variables:
         remove = []
         # remove independent_variables with single values
@@ -77,12 +85,13 @@ module OpenTox
 
       end
 
-      # call caret methods dynamically, e.g. Caret.pls
+      # Call caret methods dynamically, e.g. Caret.pls
       def self.method_missing(sym, *args, &block)
         args.first[:method] = sym.to_s
         self.create_model_and_predict args.first
       end
 
+      # Convert Ruby values to R values
       def self.to_r v
         return "F" if v == false
         return "T" if v == true

data/lib/classification.rb

@@ -1,9 +1,14 @@
 module OpenTox
   module Algorithm
     
+    # Classification algorithms
     class Classification
 
-      def self.weighted_majority_vote dependent_variables:, independent_variables:nil, weights:, query_variables:
+      # Weighted majority vote
+      # @param [Array<TrueClass,FalseClass>] dependent_variables
+      # @param [Array<Float>] weights
+      # @return [Hash]
+      def self.weighted_majority_vote dependent_variables:, independent_variables:nil, weights:, query_variables:nil
         class_weights = {}
         dependent_variables.each_with_index do |v,i|
           class_weights[v] ||= []

data/lib/compound.rb

@@ -2,6 +2,7 @@ CACTUS_URI="https://cactus.nci.nih.gov/chemical/structure/"
 
 module OpenTox
 
+  # Small molecules with defined chemical structures
   class Compound < Substance
     require_relative "unique_descriptors.rb"
     DEFAULT_FINGERPRINT = "MP2D"
@@ -28,6 +29,9 @@ module OpenTox
       compound
     end
 
+    # Create chemical fingerprint
+    # @param [String] fingerprint type
+    # @return [Array<String>] 
     def fingerprint type=DEFAULT_FINGERPRINT
       unless fingerprints[type]
         return [] unless self.smiles
@@ -75,6 +79,9 @@ module OpenTox
       fingerprints[type]
     end
 
+    # Calculate physchem properties
+    # @param [Array<Hash>] list of descriptors
+    # @return [Array<Float>]
     def calculate_properties descriptors=PhysChem::OPENBABEL
       calculated_ids = properties.keys
       # BSON::ObjectId instances are not allowed as keys in a BSON document.
@@ -96,6 +103,10 @@ module OpenTox
       descriptors.collect{|d| properties[d.id.to_s]}
     end
 
+    # Match a SMARTS substructure
+    # @param [String] smarts
+    # @param [TrueClass,FalseClass] count matches or return true/false
+    # @return [TrueClass,FalseClass,Fixnum] 
     def smarts_match smarts, count=false
       obconversion = OpenBabel::OBConversion.new
       obmol = OpenBabel::OBMol.new
@@ -116,8 +127,8 @@ module OpenTox
     # Create a compound from smiles string
     # @example
     #   compound = OpenTox::Compound.from_smiles("c1ccccc1")
-    # @param [String] smiles Smiles string
-    # @return [OpenTox::Compound] Compound
+    # @param [String] smiles 
+    # @return [OpenTox::Compound]
     def self.from_smiles smiles
       if smiles.match(/\s/) # spaces seem to confuse obconversion and may lead to invalid smiles
         $logger.warn "SMILES parsing failed for '#{smiles}'', SMILES string contains whitespaces."
@@ -132,9 +143,9 @@ module OpenTox
       end
     end
 
-    # Create a compound from inchi string
-    # @param inchi [String] smiles InChI string
-    # @return [OpenTox::Compound] Compound
+    # Create a compound from InChI string
+    # @param [String] InChI 
+    # @return [OpenTox::Compound] 
     def self.from_inchi inchi
       #smiles = `echo "#{inchi}" | "#{File.join(File.dirname(__FILE__),"..","openbabel","bin","babel")}" -iinchi - -ocan`.chomp.strip
       smiles = obconversion(inchi,"inchi","can")
@@ -145,9 +156,9 @@ module OpenTox
       end
     end
 
-    # Create a compound from sdf string
-    # @param sdf [String] smiles SDF string
-    # @return [OpenTox::Compound] Compound
+    # Create a compound from SDF 
+    # @param [String] SDF 
+    # @return [OpenTox::Compound] 
     def self.from_sdf sdf
       # do not store sdf because it might be 2D
       Compound.from_smiles obconversion(sdf,"sdf","can")
@@ -156,40 +167,38 @@ module OpenTox
     # Create a compound from name. Relies on an external service for name lookups.
     # @example
     #   compound = OpenTox::Compound.from_name("Benzene")
-    # @param name [String] can be also an InChI/InChiKey, CAS number, etc
-    # @return [OpenTox::Compound] Compound
+    # @param [String] name, can be also an InChI/InChiKey, CAS number, etc
+    # @return [OpenTox::Compound]
     def self.from_name name
       Compound.from_smiles RestClientWrapper.get(File.join(CACTUS_URI,URI.escape(name),"smiles"))
     end
 
     # Get InChI
-    # @return [String] InChI string
+    # @return [String] 
     def inchi
       unless self["inchi"]
-
         result = obconversion(smiles,"smi","inchi")
-        #result = `echo "#{self.smiles}" | "#{File.join(File.dirname(__FILE__),"..","openbabel","bin","babel")}" -ismi - -oinchi`.chomp
         update(:inchi => result.chomp) if result and !result.empty?
       end
       self["inchi"]
     end
 
     # Get InChIKey
-    # @return [String] InChIKey string
+    # @return [String]
     def inchikey
       update(:inchikey => obconversion(smiles,"smi","inchikey")) unless self["inchikey"]
       self["inchikey"]
     end
 
     # Get (canonical) smiles
-    # @return [String] Smiles string
+    # @return [String]
     def smiles
       update(:smiles => obconversion(self["smiles"],"smi","can")) unless self["smiles"] 
       self["smiles"]
     end
 
-    # Get sdf
-    # @return [String] SDF string
+    # Get SDF
+    # @return [String]
     def sdf
       if self.sdf_id.nil? 
         sdf = obconversion(smiles,"smi","sdf")
@@ -209,7 +218,6 @@ module OpenTox
        update(:svg_id => $gridfs.insert_one(file))
       end
       $gridfs.find_one(_id: self.svg_id).data
-
     end
 
     # Get png image
@@ -223,26 +231,27 @@ module OpenTox
        update(:png_id => $gridfs.insert_one(file))
       end
       Base64.decode64($gridfs.find_one(_id: self.png_id).data)
-
     end
 
     # Get all known compound names. Relies on an external service for name lookups.
     # @example
     #   names = compound.names
-    # @return [String] Compound names
+    # @return [Array<String>] 
     def names
       update(:names => RestClientWrapper.get("#{CACTUS_URI}#{inchi}/names").split("\n")) unless self["names"] 
       self["names"]
     end
 
-    # @return [String] PubChem Compound Identifier (CID), derieved via restcall to pubchem
+    # Get PubChem Compound Identifier (CID), obtained via REST call to PubChem
+    # @return [String] 
     def cid
       pug_uri = "https://pubchem.ncbi.nlm.nih.gov/rest/pug/"
       update(:cid => RestClientWrapper.post(File.join(pug_uri, "compound", "inchi", "cids", "TXT"),{:inchi => inchi}).strip) unless self["cid"] 
       self["cid"]
     end
 
-    # @return [String] ChEMBL database compound id, derieved via restcall to chembl
+    # Get ChEMBL database compound id, obtained via REST call to ChEMBL
+    # @return [String] 
     def chemblid
       # https://www.ebi.ac.uk/chembldb/ws#individualCompoundByInChiKey
       uri = "https://www.ebi.ac.uk/chemblws/compounds/smiles/#{smiles}.json"
@@ -292,7 +301,7 @@ module OpenTox
       mg.to_f/molecular_weight
     end
     
-    # Calculate molecular weight of Compound with OB and store it in object
+    # Calculate molecular weight of Compound with OB and store it in compound object
     # @return [Float] molecular weight
     def molecular_weight
       mw_feature = PhysChem.find_or_create_by(:name => "Openbabel.MW")

data/lib/crossvalidation.rb

@@ -1,10 +1,16 @@
 module OpenTox
 
   module Validation
+
+    # Crossvalidation
     class CrossValidation < Validation
       field :validation_ids, type: Array, default: []
       field :folds, type: Integer, default: 10
 
+      # Create a crossvalidation
+      # @param [OpenTox::Model::Lazar]
+      # @param [Fixnum] number of folds
+      # @return [OpenTox::Validation::CrossValidation]
       def self.create model, n=10
         $logger.debug model.algorithms
         klass = ClassificationCrossValidation if model.is_a? Model::LazarClassification
@@ -41,14 +47,20 @@ module OpenTox
         cv
       end
 
+      # Get execution time
+      # @return [Fixnum]
       def time
         finished_at - created_at
       end
 
+      # Get individual validations
+      # @return [Array<OpenTox::Validation>]
       def validations
         validation_ids.collect{|vid| TrainTest.find vid}
       end
 
+      # Get predictions for all compounds
+      # @return [Array<Hash>]
       def predictions
         predictions = {}
         validations.each{|v| predictions.merge!(v.predictions)}
@@ -56,6 +68,7 @@ module OpenTox
       end
     end
 
+    # Crossvalidation of classification models
     class ClassificationCrossValidation < CrossValidation
       include ClassificationStatistics
       field :accept_values, type: Array
@@ -68,6 +81,7 @@ module OpenTox
       field :probability_plot_id, type: BSON::ObjectId
     end
 
+    # Crossvalidation of regression models
     class RegressionCrossValidation < CrossValidation
       include RegressionStatistics
       field :rmse, type: Float, default:0
@@ -78,10 +92,16 @@ module OpenTox
       field :correlation_plot_id, type: BSON::ObjectId
     end
 
+    # Independent repeated crossvalidations
     class RepeatedCrossValidation < Validation
       field :crossvalidation_ids, type: Array, default: []
       field :correlation_plot_id, type: BSON::ObjectId
 
+      # Create repeated crossvalidations
+      # @param [OpenTox::Model::Lazar]
+      # @param [Fixnum] number of folds
+      # @param [Fixnum] number of repeats
+      # @return [OpenTox::Validation::RepeatedCrossValidation]
       def self.create model, folds=10, repeats=3
         repeated_cross_validation = self.new
         repeats.times do |n|
@@ -92,6 +112,8 @@ module OpenTox
         repeated_cross_validation
       end
 
+      # Get crossvalidations
+      # @return [OpenTox::Validation::CrossValidation]
       def crossvalidations
         crossvalidation_ids.collect{|id| CrossValidation.find(id)}
       end

data/lib/dataset.rb

@@ -3,32 +3,43 @@ require 'tempfile'
 
 module OpenTox
 
+  # Collection of substances and features
   class Dataset
 
     field :data_entries, type: Hash, default: {}
 
     # Readers
 
+    # Get all compounds
+    # @return [Array<OpenTox::Compound>]
     def compounds
       substances.select{|s| s.is_a? Compound}
     end
 
+    # Get all nanoparticles
+    # @return [Array<OpenTox::Nanoparticle>]
     def nanoparticles
       substances.select{|s| s.is_a? Nanoparticle}
     end
 
     # Get all substances
+    # @return [Array<OpenTox::Substance>]
     def substances
       @substances ||= data_entries.keys.collect{|id| OpenTox::Substance.find id}.uniq
       @substances
     end
 
     # Get all features
+    # @return [Array<OpenTox::Feature>]
     def features
       @features ||= data_entries.collect{|sid,data| data.keys.collect{|id| OpenTox::Feature.find(id)}}.flatten.uniq
       @features
     end
 
+    # Get all values for a given substance and feature
+    # @param [OpenTox::Substance,BSON::ObjectId,String] substance or substance id
+    # @param [OpenTox::Feature,BSON::ObjectId,String] feature or feature id
+    # @return [TrueClass,FalseClass,Float]
     def values substance,feature
       substance = substance.id if substance.is_a? Substance
       feature = feature.id if feature.is_a? Feature
@@ -41,6 +52,10 @@ module OpenTox
 
     # Writers
 
+    # Add a value for a given substance and feature
+    # @param [OpenTox::Substance,BSON::ObjectId,String] substance or substance id
+    # @param [OpenTox::Feature,BSON::ObjectId,String] feature or feature id
+    # @param [TrueClass,FalseClass,Float]
     def add(substance,feature,value)
       substance = substance.id if substance.is_a? Substance
       feature = feature.id if feature.is_a? Feature
@@ -87,7 +102,7 @@ module OpenTox
 
     # Serialisation
     
-    # converts dataset to csv format including compound smiles as first column, other column headers are feature names
+    # Convert dataset to csv format including compound smiles as first column, other column headers are feature names
     # @return [String]
     def to_csv(inchi=false)
       CSV.generate() do |csv| 
@@ -130,6 +145,9 @@ module OpenTox
     #end
     
     # Create a dataset from CSV file
+    # @param [File] 
+    # @param [TrueClass,FalseClass] accept or reject empty values
+    # @return [OpenTox::Dataset]
     def self.from_csv_file file, accept_empty_values=false
       source = file
       name = File.basename(file,".*")
@@ -145,8 +163,10 @@ module OpenTox
       dataset
     end
 
-    # parse data in tabular format (e.g. from csv)
-    # does a lot of guesswork in order to determine feature types
+    # Parse data in tabular format (e.g. from csv)
+    #   does a lot of guesswork in order to determine feature types
+    # @param [Array<Array>] 
+    # @param [TrueClass,FalseClass] accept or reject empty values
     def parse_table table, accept_empty_values
 
       # features
@@ -225,6 +245,7 @@ module OpenTox
       save
     end
 
+    # Delete dataset
     def delete
       compounds.each{|c| c.dataset_ids.delete id.to_s}
       super
@@ -238,14 +259,20 @@ module OpenTox
     field :prediction_feature_id, type: BSON::ObjectId
     field :predictions, type: Hash, default: {}
 
+    # Get prediction feature
+    # @return [OpenTox::Feature]
     def prediction_feature
       Feature.find prediction_feature_id
     end
 
+    # Get all compounds
+    # @return [Array<OpenTox::Compound>]
     def compounds
       substances.select{|s| s.is_a? Compound}
     end
 
+    # Get all substances
+    # @return [Array<OpenTox::Substance>]
     def substances
       predictions.keys.collect{|id| Substance.find id}
     end

data/lib/feature.rb

@@ -8,10 +8,14 @@ module OpenTox
     field :unit, type: String
     field :conditions, type: Hash
 
+    # Is it a nominal feature
+    # @return [TrueClass,FalseClass]
     def nominal?
       self.class == NominalFeature
     end
 
+    # Is it a numeric feature
+    # @return [TrueClass,FalseClass]
     def numeric?
       self.class == NumericFeature
     end
@@ -30,6 +34,9 @@ module OpenTox
   class Smarts < NominalFeature
     field :smarts, type: String 
     index "smarts" => 1
+    # Create feature from SMARTS string
+    # @param [String]
+    # @return [OpenTox::Feature]
     def self.from_smarts smarts
       self.find_or_create_by :smarts => smarts
     end

data/lib/feature_selection.rb

@@ -1,13 +1,16 @@
 module OpenTox
   module Algorithm
     
+    # Feature selection algorithms
     class FeatureSelection
 
+      # Select features correlated to the models prediction feature
+      # @param [OpenTox::Model::Lazar]
       def self.correlation_filter model
         relevant_features = {}
         R.assign "dependent", model.dependent_variables.collect{|v| to_r(v)}
         model.descriptor_weights = []
-        selected_variables = []
+        selected_variables = [] 
         selected_descriptor_ids = []
         model.independent_variables.each_with_index do |v,i|
           v.collect!{|n| to_r(n)}

data/lib/import.rb

@@ -1,12 +1,14 @@
 module OpenTox
 
+  # Import data from external databases
   module Import
 
     class Enanomapper
       include OpenTox
 
-      # time critical step: JSON parsing (>99%), Oj brings only minor speed gains (~1%)
+      # Import from eNanoMapper
       def self.import
+        # time critical step: JSON parsing (>99%), Oj brings only minor speed gains (~1%)
         datasets = {}
         bundles = JSON.parse(RestClientWrapper.get('https://data.enanomapper.net/bundle?media=application%2Fjson'))["dataset"]
         bundles.each do |bundle|
@@ -20,6 +22,7 @@ module OpenTox
               uri = c["component"]["compound"]["URI"]
               uri = CGI.escape File.join(uri,"&media=application/json")
               data = JSON.parse(RestClientWrapper.get "https://data.enanomapper.net/query/compound/url/all?media=application/json&search=#{uri}")
+              source = data["dataEntry"][0]["compound"]["URI"]
               smiles = data["dataEntry"][0]["values"]["https://data.enanomapper.net/feature/http%3A%2F%2Fwww.opentox.org%2Fapi%2F1.1%23SMILESDefault"]
               names = []
               names << data["dataEntry"][0]["values"]["https://data.enanomapper.net/feature/http%3A%2F%2Fwww.opentox.org%2Fapi%2F1.1%23ChemicalNameDefault"]
@@ -31,6 +34,7 @@ module OpenTox
               else
                 compound = Compound.find_or_create_by(:name => names.first,:names => names.compact)
               end
+              compound.source = source
               compound.save
               if c["relation"] == "HAS_CORE"
                 core_id = compound.id.to_s

data/lib/leave-one-out-validation.rb

@@ -2,8 +2,12 @@ module OpenTox
 
   module Validation
 
+    # Leave one out validation
     class LeaveOneOut < Validation
 
+      # Create a leave one out validation
+      # @param [OpenTox::Model::Lazar]
+      # @return [OpenTox::Validation::LeaveOneOut]
       def self.create model
         bad_request_error "Cannot create leave one out validation for models with supervised feature selection. Please use crossvalidation instead." if model.algorithms[:feature_selection]
         $logger.debug "#{model.name}: LOO validation started"
@@ -32,6 +36,7 @@ module OpenTox
 
     end
 
+    # Leave one out validation for classification models
     class ClassificationLeaveOneOut < LeaveOneOut
       include ClassificationStatistics
       field :accept_values, type: Array
@@ -44,6 +49,7 @@ module OpenTox
       field :confidence_plot_id, type: BSON::ObjectId
     end
     
+    # Leave one out validation for regression models
     class RegressionLeaveOneOut  < LeaveOneOut
       include RegressionStatistics
       field :rmse, type: Float, default: 0