Documentation + Orthogonal Matching Pursuit helper method (#16)

* "Adds a .nojekyll file for docs builds"

* Modified the spelling of "Licence" to "License" everywhere.
Adding main page (index.rst) for documentation in docs_rst.

* Added html documentation.

* Added .idea folder to .gitignore.

* Excluding docs_rst for mypy.

* Excluded docs_rst from pydocstyle checks.
Linted docs_rst/conf.py by black.

* Added copyright notice in README.rst and CHANGES.rst.
Added pip install pysisso installation in README.rst.

* Added OMP classmethod to SISSORegressor to automatically set up the Orthogonal Matching Pursuit parameters.
Added example for OMP SISSORegressor.
Added tests for OMP SISSORegressor.

* Added documentation webpage in the README file.

.pre-commit-config.yaml

@@ -35,10 +35,10 @@ repos:
     rev: 5.1.1  # pick a git hash / tag to point to
     hooks:
     - id: pydocstyle
-      exclude: (examples_usage|test_.*py)  # exclude python test files and example usage
+      exclude: (examples_usage|test_.*py|docs_rst)  # exclude some files
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: v0.790
     hooks:
     - id: mypy
-      exclude: (examples_usage|test_.*py)  # exclude python test files and example usage
+      exclude: (examples_usage|test_.*py|docs_rst)  # exclude some files
       args: []

CHANGES.rst

@@ -1,7 +1,22 @@
+..
+   Copyright (c) 2020, Matgenix SRL, All rights reserved.
+   Distributed open source for academic and non-profit users.
+   Contact Matgenix for commercial usage.
+   See LICENSE file for details.
 
-Release 0.3.2 (Mar 11, 2021)
+
+Release 0.3.2 (Mar 18, 2021)
 ============================
 
+Features added
+--------------
+
+* Added OMP class method to set up Orthogonal Matching Pursuit parameters in
+  SISSO regressor.
+
+Miscellanous
+------------
+
 * Started documentation
 * Updated spelling of "licence" to "license" everywhere
 

README.rst

@@ -1,16 +1,24 @@
+..
+   Copyright (c) 2020, Matgenix SRL, All rights reserved.
+   Distributed open source for academic and non-profit users.
+   Contact Matgenix for commercial usage.
+   See LICENSE file for details.
+
 Python interface to the SISSO (Sure Independence Screening and Sparsifying Operator) method.
 ============================================================================================
 
 The pysisso package is a python interface to the SISSO code (https://github.com/rouyang2017/SISSO).
 
 The interface has been developed in accordance with scikit-learn's API so that SISSO can be directly integrated in sklearn's pipelines or cross-validation schemes for example.
 
+The documentation is available here: https://matgenix.github.io/pysisso/.
+
 Installation
 ------------
 
-In order to install pysisso, you must have poetry (https://python-poetry.org/) installed.
+pysisso is available on Pypi and is easily installed with:
 
-Simply run *poetry install* to install pysisso in your environment.
+    pip install pysisso
 
 Usage examples
 --------------

docs/_modules/index.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>Overview: module code &mdash; pysisso 0.3.1 documentation</title>
+  <title>Overview: module code &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/_modules/pysisso/inputs.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso.inputs &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso.inputs &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/_modules/pysisso/jobs.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso.jobs &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso.jobs &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/_modules/pysisso/outputs.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso.outputs &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso.outputs &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/_modules/pysisso/sklearn.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso.sklearn &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso.sklearn &mdash; pysisso 0.3.2 documentation</title>
 
 
 
@@ -449,6 +449,51 @@ <h1>Source code for pysisso.sklearn</h1><div class="highlight"><pre>
         <span class="n">data</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">index</span><span class="o">=</span><span class="n">index</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">columns</span><span class="p">)</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">sisso_out</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">data</span><span class="p">)</span></div>
 
+<div class="viewcode-block" id="SISSORegressor.OMP"><a class="viewcode-back" href="../../api/pysisso.html#pysisso.sklearn.SISSORegressor.OMP">[docs]</a>    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">OMP</span><span class="p">(</span>
+        <span class="bp">cls</span><span class="p">,</span>
+        <span class="n">desc_dim</span><span class="p">,</span>
+        <span class="n">use_custodian</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+        <span class="n">custodian_job_kwargs</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="nb">dict</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+        <span class="n">custodian_kwargs</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="nb">dict</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+        <span class="n">run_dir</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;SISSO_dir&quot;</span><span class="p">,</span>
+        <span class="n">clean_run_dir</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+    <span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Construct SISSORegressor for Orthogonal Matching Pursuit (OMP).</span>
+
+<span class="sd">        OMP is usually the first step to be performed before applying SISSO.</span>
+<span class="sd">        Indeed, one starts with a relatively small set of base input descriptors</span>
+<span class="sd">        (usually less than 20), that are then combined together by SISSO. One way to</span>
+<span class="sd">        obtain this small set is to use the OMP algorithm (which is a particular case</span>
+<span class="sd">        of the SISSO algorithm itself).</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            desc_dim: Number of descriptors to get with OMP.</span>
+<span class="sd">            use_custodian: Whether to use custodian (currently mandatory).</span>
+<span class="sd">            custodian_job_kwargs: Keyword arguments for custodian job.</span>
+<span class="sd">            custodian_kwargs: Keyword arguments for custodian.</span>
+<span class="sd">            run_dir: Name of the directory where SISSO is run. If None, the directory</span>
+<span class="sd">                will be set automatically. It then contains a timestamp and is unique.</span>
+<span class="sd">            clean_run_dir: Whether to clean the run directory after SISSO has run.</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            SISSORegressor: SISSO regressor with OMP parameters.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span>
+            <span class="n">opset</span><span class="o">=</span><span class="s2">&quot;(+)(-)(*)(/)(exp)(exp-)(^-1)(^2)(^3)(sqrt)(cbrt)(log)(|-|)(scd)(^6)&quot;</span><span class="p">,</span>
+            <span class="n">rung</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
+            <span class="n">desc_dim</span><span class="o">=</span><span class="n">desc_dim</span><span class="p">,</span>
+            <span class="n">subs_sis</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
+            <span class="n">method</span><span class="o">=</span><span class="s2">&quot;L0&quot;</span><span class="p">,</span>
+            <span class="n">L1L0_size4L0</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+            <span class="n">features_dimensions</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+            <span class="n">use_custodian</span><span class="o">=</span><span class="n">use_custodian</span><span class="p">,</span>
+            <span class="n">custodian_job_kwargs</span><span class="o">=</span><span class="n">custodian_job_kwargs</span><span class="p">,</span>
+            <span class="n">custodian_kwargs</span><span class="o">=</span><span class="n">custodian_kwargs</span><span class="p">,</span>
+            <span class="n">run_dir</span><span class="o">=</span><span class="n">run_dir</span><span class="p">,</span>
+            <span class="n">clean_run_dir</span><span class="o">=</span><span class="n">clean_run_dir</span><span class="p">,</span>
+        <span class="p">)</span></div>
+
 <div class="viewcode-block" id="SISSORegressor.from_SISSOIn"><a class="viewcode-back" href="../../api/pysisso.html#pysisso.sklearn.SISSORegressor.from_SISSOIn">[docs]</a>    <span class="nd">@classmethod</span>
     <span class="k">def</span> <span class="nf">from_SISSOIn</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">sisso_in</span><span class="p">:</span> <span class="n">SISSOIn</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Construct SISSORegressor from a SISSOIn object.</span>

docs/_modules/pysisso/utils.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso.utils &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso.utils &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/_modules/pysisso/validators.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso.validators &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso.validators &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.3.1',
+    VERSION: '0.3.2',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/api.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>API Reference &mdash; pysisso 0.3.1 documentation</title>
+  <title>API Reference &mdash; pysisso 0.3.2 documentation</title>
 
 
 

docs/api/modules.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>pysisso &mdash; pysisso 0.3.1 documentation</title>
+  <title>pysisso &mdash; pysisso 0.3.2 documentation</title>