real datasets for testing, test data cleanup, Daphnia import, upper and lower similar...
[lazar] / README.md
1 lazar
2 =====
3
4 Ruby libraries for the lazar framework
5
6 Dependencies
7 ------------
8
9   lazar depends on a couple of external programs and libraries. All required libraries will be installed with the `gem install lazar` command. 
10   If any of the dependencies fails to install, please check if all required development packages are installed from your operating systems package manager (e.g. `apt`, `rpm`, `pacman`, ...). 
11   You will need a working Java runtime to use descriptor calculation algorithms from CDK and JOELib libraries.
12
13 Installation
14 ------------
15
16   `gem install lazar`
17
18   Please be patient, the compilation of external libraries can be very time consuming. If installation fails you can try to install manually:
19
20   ```
21   git clone https://github.com/opentox/lazar.git
22   cd lazar
23   ruby ext/lazar/extconf.rb
24   bundle install
25   ```
26
27   The output should give you more verbose information that can help in debugging (e.g. to identify missing libraries).
28
29 Tutorial
30 --------
31
32 Execute the following commands either from an interactive Ruby shell or a Ruby script:
33
34   Import `lazar`
35
36   ```
37   require 'lazar'
38   include OpenTox
39   ```
40
41 ### Create and use `lazar` models for small molecules
42
43 #### Create and validate public `lazar` models
44
45   `public_models = Import.public_data`
46
47   This command creates models for all training data in the data folder and validates them with 5 independent crossvalidations. This may take some time (several hours). Retrieve validation results with `public_models.crossvalidations`.
48
49 #### Make predictions
50
51 ##### Single compounds
52
53   Create a compound
54
55   `compound = Compound.from_smiles "NC(=O)OCCC"`
56
57   Select a model
58
59   `model = public_models.first`
60
61   `model.predict compound`
62
63 ##### Batch predictions
64
65   Create a CSV file with one or two columns: An optional Substance ID and SMILES codes for the substances to be predicted. The first line should contain either "ID,SMILES" or just "SMILES" if there is no ID column. 
66
67   Import the dataset
68
69   `dataset = Dataset.from_csv_file batch_file.csv`
70
71   Select a model
72
73   `model = public_models.first`
74
75   Make a batch prediction
76
77   `prediction_dataset model.predict dataset`
78
79   View predictions
80
81   `prediction_dataset.predictions`
82
83 #### Create and validate models from your own datasets
84
85 ##### Create a training dataset
86
87   Create a CSV file with two or three columns: An optional Substance ID, SMILES and toxic activities (qualitative or quantitative). Use -log10 transformed values for quantitative values. The first line should contain "ID" (optional), SMILES and the endpoint name. Add metadata to a JSON file with the same basename containing the fields "species", "endpoint", "source", "qmrf" (optional) and "unit" (regression only). You can find example training data in the data folder of lazar.
88
89 ##### Create and validate a `lazar` model with default algorithms and parameters
90
91   `validated_model = Model::Validation.create_from_csv_file training_data.csv`
92
93   This command will create a `lazar` model and validate it with five independent 10-fold crossvalidations. You can use the model in the same way as the public models.
94
95 #### Create and validate models from PubChem Assay Data
96
97   If you know the PubChem Assay ID (AID), you can create and validate models directly from PubChem.
98
99   Download datasets from PubChem 
100
101   `csv_file = Download.pubchem_classification aid: 1205, species: "Rodents", endpoint: "Carcinogenicity", qmrf: {group: "QMRF 4.12. Carcinogenicity", name: "OECD 451 Carcinogenicity Studies"}`
102
103   or
104
105   `csv_file = Download.pubchem_regression aid: 1195, species: "Human", endpoint: "Maximum Recommended Daily Dose", qmrf: {group: "QMRF 4.14. Repeated dose toxicity", name: "OECD 452 Chronic Toxicity Studies"}`
106
107   This will create new CSV and metadata files in the data folder (or update existing ones). Regression data will use -log10 transformed molar values. Use this file either with `Model::Validation.create_from_csv_file` or create all models in the public folder with `Import.public_models`.
108
109 #### Experiment with other algorithms
110
111   You can pass algorithm specifications as parameters to the `Model::Validation.create_from_csv_file` and `Model::Lazar.create` commands. Algorithms for descriptors, similarity calculations, feature_selection and local models are specified in the `algorithm` parameter. Unspecified algorithms and parameters are substituted by default values. The example below selects 
112
113   - MP2D fingerprint descriptors
114   - Tanimoto similarity with a threshold of 0.1
115   - no feature selection
116   - weighted majority vote predictions
117
118   ```
119 algorithms = {
120   :descriptors => { # descriptor algorithm
121     :method => "fingerprint", # fingerprint descriptors
122     :type => "MP2D" # fingerprint type, e.g. FP4, MACCS
123   },
124   :similarity => { # similarity algorithm
125     :method => "Algorithm::Similarity.tanimoto",
126     :min => [0.5,0.2] # similarity thresholds for neighbors: first value for predictions with high confidence, second value for predictions with medium confidence 
127   },
128   :feature_selection => nil, # no feature selection
129   :prediction => { # local modelling algorithm
130     :method => "Algorithm::Classification.weighted_majority_vote",
131   },
132 }
133
134 training_dataset = Dataset.from_csv_file "hamster_carcinogenicity.csv"
135 model = Model::Lazar.create  training_dataset: training_dataset, algorithms: algorithms
136   ```
137
138   The next example creates a regression model with
139
140   - calculated descriptors from OpenBabel libraries
141   - weighted cosine similarity and a threshold of 0.5
142   - descriptors that are correlated with the endpoint
143   - local partial least squares models from the R caret package
144
145   ```
146 algorithms = {
147   :descriptors => { # descriptor algorithm
148     :method => "calculate_properties",
149     :features => PhysChem.openbabel_descriptors,
150   },
151   :similarity => { # similarity algorithm
152     :method => "Algorithm::Similarity.weighted_cosine",
153     :min => [0.5,0.2]
154   },
155   :feature_selection => { # feature selection algorithm
156     :method => "Algorithm::FeatureSelection.correlation_filter",
157   },
158   :prediction => { # local modelling algorithm
159     :method => "Algorithm::Caret.pls",
160   },
161 }
162 training_dataset = Dataset.from_csv_file "EPAFHM_log10.csv"
163 model = Model::Lazar.create(training_dataset:training_dataset, algorithms:algorithms)
164     ```
165 Please consult the [API documentation](http://rdoc.info/gems/lazar) and [source code](https:://github.com/opentox/lazar) for up to date information about implemented algorithms:
166
167 - Descriptor algorithms
168   - [Compounds](http://www.rubydoc.info/gems/lazar/OpenTox/Compound)
169   - [Nanoparticles](http://www.rubydoc.info/gems/lazar/OpenTox/Nanoparticle)
170 - [Similarity algorithms](http://www.rubydoc.info/gems/lazar/OpenTox/Algorithm/Similarity)
171 - [Feature selection algorithms](http://www.rubydoc.info/gems/lazar/OpenTox/Algorithm/FeatureSelection)
172 - Local models
173   - [Classification](http://www.rubydoc.info/gems/lazar/OpenTox/Algorithm/Classification)
174   - [Regression](http://www.rubydoc.info/gems/lazar/OpenTox/Algorithm/Regression)
175   - [R caret](http://www.rubydoc.info/gems/lazar/OpenTox/Algorithm/Caret)
176
177
178 You can find more working examples in the `lazar`  [tests](https://github.com/opentox/lazar/tree/master/test).
179
180 ### Create and use `lazar` nanoparticle models
181
182 *eNanoMapper import is currently broken, because API and data models change unpredictably and we have no resources to track these changes. Please contact info@in-silico.ch, if you want to fund the further development of nanoparticle models*
183
184 #### Create and validate a `nano-lazar` model from eNanoMapper with default algorithms and parameters
185
186   `validated_model = Model::Validation.create_from_enanomapper`
187
188   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.
189
190 #### Inspect crossvalidation results
191
192   `validated_model.crossvalidations`
193
194 #### Predict nanoparticle toxicities
195
196   Choose a random nanoparticle from the "Potein Corona" dataset
197   ```
198   training_dataset = Dataset.where(:name => "Protein Corona Fingerprinting Predicts the Cellular Interaction of Gold and Silver Nanoparticles").first
199   nanoparticle = training_dataset.substances.shuffle.first
200   ```
201
202   Predict the "Net Cell Association" endpoint
203
204   `validated_model.predict nanoparticle`
205
206 #### Experiment with other datasets, endpoints and algorithms
207
208   You can pass training_dataset, prediction_feature and algorithms parameters to the `Model::Validation.create_from_enanomapper` command. Procedure and options are the same as for compounds. The following commands create and validate a `nano-lazar` model with
209
210   - measured P-CHEM properties as descriptors
211   - descriptors selected with correlation filter
212   - weighted cosine similarity with a threshold of 0.5
213   - Caret random forests
214
215 ```
216 algorithms = {
217   :descriptors => {
218     :method => "properties",
219     :categories => ["P-CHEM"],
220   },
221   :similarity => {
222     :method => "Algorithm::Similarity.weighted_cosine",
223     :min => [0.5,0.2]
224   },
225   :feature_selection => {
226     :method => "Algorithm::FeatureSelection.correlation_filter",
227   },
228   :prediction => {
229     :method => "Algorithm::Caret.rf",
230   },
231 }
232 validation_model = Model::Validation.from_enanomapper algorithms: algorithms
233 ```
234
235
236   Detailed documentation and validation results for nanoparticle models can be found in this [publication](https://github.com/enanomapper/nano-lazar-paper/blob/master/nano-lazar.pdf).
237
238 Documentation
239 -------------
240 * [API documentation](http://rdoc.info/gems/lazar)
241
242 Copyright
243 ---------
244 Copyright (c) 2009-2018 Christoph Helma, Martin Guetlein, Micha Rautenberg, Andreas Maunz, David Vorgrimmler, Denis Gebele. See LICENSE for details.