7e0e420517efc8e45962c8f2f78c94f0ddc48264
[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 ### Create and use `lazar` models for small molecules
35
36 #### Create a training dataset
37
38   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).
39
40 #### Create and validate a `lazar` model with default algorithms and parameters
41
42   `validated_model = Model::Validation.create_from_csv_file EPAFHM_log10.csv`
43
44   This command will create a `lazar` model and validate it with three independent 10-fold crossvalidations.
45
46 #### Inspect crossvalidation results
47
48   `validated_model.crossvalidations`
49
50 #### Predict a new compound
51
52   Create a compound
53
54   `compound = Compound.from_smiles "NC(=O)OCCC"`
55
56   Predict Fathead Minnow Acute Toxicity
57
58   `validated_model.predict compound`
59
60 #### Experiment with other algorithms
61
62   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.
63
64 ### Create and use `lazar` nanoparticle models
65
66 #### Create and validate a `nano-lazar` model from eNanoMapper with default algorithms and parameters
67
68   `validated_model = Model::Validation.create_from_enanomapper`
69
70   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.
71
72 #### Inspect crossvalidation results
73
74   `validated_model.crossvalidations`
75
76 #### Predict nanoparticle toxicities
77
78   Choose a random nanoparticle from the "Potein Corona" dataset
79   ```
80   training_dataset = Dataset.where(:name => "Protein Corona Fingerprinting Predicts the Cellular Interaction of Gold and Silver Nanoparticles").first
81   nanoparticle = training_dataset.substances.shuffle.first
82   ```
83
84   Predict the "Net Cell Association" endpoint
85
86   `validated_model.predict nanoparticle`
87
88 #### Experiment with other datasets, endpoints and algorithms
89
90   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.
91
92 Documentation
93 -------------
94 * [API documentation](http://rdoc.info/gems/lazar)
95
96 Copyright
97 ---------
98 Copyright (c) 2009-2017 Christoph Helma, Martin Guetlein, Micha Rautenberg, Andreas Maunz, David Vorgrimmler, Denis Gebele. See LICENSE for details.