Merge pull request #17 from GilesStrong/v0.3.1

V0.3.1

.readthedocs.yml

@@ -0,0 +1,15 @@
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.6
+  install:
+    - requirements: docs/requirements.txt

.vscode/settings.json

@@ -9,5 +9,14 @@
     "python.linting.pydocstyleEnabled": false,
     "python.linting.pylamaEnabled": false,
     "python.linting.flake8Args": ["--ignore=E702 E301 E222 E741 E704 E252 E271 E221 E272 E226 E231 E241 E501 W293 W391 W291 E701 W504"],
-    "markdownlint.config": {"MD025": false, "MD024": false, "MD041": false, "MD007": false, "MD040": false, "MD026":false, "MD034":false},
+    "markdownlint.config": {
+        "MD025": false,
+        "MD024": false,
+        "MD041": false,
+        "MD007": false,
+        "MD040": false,
+        "MD026": false,
+        "MD034": false
+    },
+    "restructuredtext.confPath": "${workspaceFolder}/docs",
 }

CHANGES.md

@@ -1,4 +1,41 @@
-# Targeting V0.3
+# V0.3.1 Tears in Rain - micro update
+
+## Important changes
+
+- Online documentation now available at https://lumin.readthedocs.io
+
+## Breaking
+
+## Additions
+
+- `bin_binary_class_pred`
+    - Ability to only consider classes rather than samples when computing bin edges
+    - Ability to add pure signal bins if normalisation uncertainty would be below some value
+- `plot_bottleneck_weighted_inputs` method for interpretting bottleneck blocks in `MultiBlock`
+- Online documentation: https://lumin.readthedocs.io
+- Default optimiser notice
+- Can now pass arbitary optimisers to the 'opt' value in `opt_args`. Optimisers still interpretable from strings.
+- Expanded advanced model building example to include more interpretation examples and diagrams of network architectures
+
+## Removals
+
+- weak decorators for losses
+
+## Fixes
+
+- `CatEmbedder.from_fy` using features ignored by `FoldYielder`
+- `bottleneck_sz_masks` to `bottleneck_masks` in `MultiBlock`
+- SWA crahsing when evaluating targets of type long, when loss expects a float (model.evaluate now converts to float when objective is not multiclass classification)
+- Doc string fixes
+- Fixed model being moved to device after instantiating optimiser (sometimes leads to an error). Models now moved to device in `ModelBuilder.get_model` rather than in `Model.__init__`
+
+## Changes
+
+## Depreciations
+
+## Comments
+
+# V0.3 Tears in Rain
 
 ## Important changes
 
@@ -202,6 +239,7 @@
 - Correct name of internal embedding dropout layer in `CatEmbHead`: emd_do -> emb_do
 - Adding missing settings for activations and initialisations to body and tail
 - Corrected plot annotation for percentage in `binary_class_cut`
+- loss history plot not being saved correctly
 
 ## Changes
 

CITATION.md

@@ -0,0 +1,13 @@
+### Reference
+
+If you have used LUMIN in your analysis work and wish to cite it, the preferred reference is: *Giles C. Strong, LUMIN, Zenodo (Mar. 2019), https://doi.org/10.5281/zenodo.2601857, Note: Please check https://github.com/GilesStrong/lumin/graphs/contributors for the full list of contributors*
+
+@misc{giles_chatham_strong_2019_2601857,  
+  author       = {Giles Chatham Strong},  
+  title        = {LUMIN},  
+  month        = mar,  
+  year         = 2019,  
+  note         = {{Please check https://github.com/GilesStrong/lumin/graphs/contributors for the full list of contributors}},  
+  doi          = {10.5281/zenodo.2601857},  
+  url          = {https://doi.org/10.5281/zenodo.2601857}  
+}

README.md

@@ -5,6 +5,8 @@
 
 LUMIN aims to become a deep-learning and data-analysis ecosystem for High-Energy Physics, and perhaps other scientific domains in the future. Similar to [Keras](https://keras.io/) and [fastai](https://github.com/fastai/fastai) it is a wrapper framework for a graph computation library (PyTorch), but includes many useful functions to handle domain-specific requirements and problems. It also intends to provide easy access to to state-of-the-art methods, but still be flexible enough for users to inherit from base classes and override methods to meet their own demands.
 
+Online documentation may be found at https://lumin.readthedocs.io
+
 For an introduction and motivation for LUMIN, checkout this talk from IML-2019 at CERN: [video](https://cds.cern.ch/record/2672119), [slides](https://indico.cern.ch/event/766872/timetable/?view=standard#29-lumin-a-deep-learning-and-d).
 
 ## Distinguishing Characteristics

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,19 @@
+sphinx==2.2.0
+-e git+https://github.com/GilesStrong/pytorch_sphinx_theme#egg=pytorch_sphinx_theme
+-e git+https://github.com/hagenw/sphinxcontrib-katex.git#egg=sphinxcontrib.katex
+sphinx_autodoc_typehints==1.7.0
+sphinx_autodoc_annotation==1.0.post1
+-f https://download.pytorch.org/whl/cpu/torch_stable.html
+torch
+seaborn==0.8.1
+matplotlib>=3.0.2
+pandas>=0.23.0
+fastprogress>=0.1.18
+scipy
+numpy>=1.12
+h5py
+scikit-learn>=0.20.0
+statsmodels>=0.9.0
+sympy
+pdpbox>=0.2.0
+rfpimp>=1.3.4

docs/source/conf.py

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import pytorch_sphinx_theme
+import datetime
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'LUMIN'
+author = 'LUMIN Contributors'
+copyright = f'{datetime.datetime.now().year}, {author}'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx_autodoc_typehints',
+    'sphinx_autodoc_annotation',
+    "sphinx_rtd_theme",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+master_doc = 'index'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = "pytorch_sphinx_theme"
+html_favicon = './_static/img/Lumin-logo-tall-dark.png'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Extension configuration -------------------------------------------------

docs/source/index.rst

@@ -0,0 +1,24 @@
+:github_url: https://github.com/GilesStrong/lumin
+
+LUMIN Documentation
+=================================
+
+Lumin Unifies Many Improvements for Networks
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Package Reference
+
+   lumin.data_processing
+   lumin.evaluation
+   lumin.inference
+   lumin.nn
+   lumin.optimisation
+   lumin.plotting
+   lumin.utils
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`

docs/source/lumin.data_processing.rst

@@ -0,0 +1,38 @@
+lumin.data\_processing package
+==============================
+
+Submodules
+----------
+
+lumin.data\_processing.file\_proc module
+----------------------------------------
+
+.. automodule:: lumin.data_processing.file_proc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lumin.data\_processing.hep\_proc module
+---------------------------------------
+
+.. automodule:: lumin.data_processing.hep_proc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lumin.data\_processing.pre\_proc module
+---------------------------------------
+
+.. automodule:: lumin.data_processing.pre_proc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lumin.data_processing
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/lumin.evaluation.rst

@@ -0,0 +1,22 @@
+lumin.evaluation package
+========================
+
+Submodules
+----------
+
+lumin.evaluation.ams module
+---------------------------
+
+.. automodule:: lumin.evaluation.ams
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lumin.evaluation
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/lumin.inference.rst

@@ -0,0 +1,22 @@
+lumin.inference package
+=======================
+
+Submodules
+----------
+
+lumin.inference.summary\_stat module
+------------------------------------
+
+.. automodule:: lumin.inference.summary_stat
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lumin.inference
+   :members:
+   :undoc-members:
+   :show-inheritance: