From 58e33f4a726faabc4f586d3925711b0ed872cc94 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 14:37:37 -0800 Subject: [PATCH 01/28] add sphinx documentation code --- docs/conf.py | 30 ++++++++++++++++++++++++++++++ docs/index.rst | 21 +++++++++++++++++++++ docs/requirements.txt | 1 + 3 files changed, 52 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..223539d --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'sparsecoding' +copyright = '2024, RCTN' +author = 'RCTN' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.napoleon', + 'sphinx.ext.autodoc', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'pydata_sphinx_theme' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f56e6c1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,21 @@ +.. sparsecoding documentation master file, created by + sphinx-quickstart on Fri Nov 15 13:23:58 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +sparsecoding documentation +========================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + sparsecoding + sparsecoding.data + sparsecoding.priors + modules + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b0a77ce --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +pydata-sphinx-theme \ No newline at end of file From 30b3e5814c7659721e4036e882a7f3f562b0d6e8 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 14:44:00 -0800 Subject: [PATCH 02/28] import sphinx and add readthedocs config yaml --- .readthedocs.yaml | 13 +++++++++++++ docs/requirements.txt | 1 + 2 files changed, 14 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..34ad79a --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index b0a77ce..7274d5e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ +sphinx pydata-sphinx-theme \ No newline at end of file From 0fbda9cdcf3705289cd646c7c5f2ebe93257b0b9 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:02:06 -0800 Subject: [PATCH 03/28] run apidoc post build --- .readthedocs.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 34ad79a..71277d9 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,6 +4,9 @@ build: os: ubuntu-24.04 tools: python: "3" + jobs: + post_install: + - sphinx-apidoc -o docs sparsecoding sphinx: configuration: docs/conf.py From ec948cc752496fd7a185aa0969194efd5871769e Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:06:57 -0800 Subject: [PATCH 04/28] require sparse coding repo install for documentation generation --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 7274d5e..b341987 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ +. sphinx pydata-sphinx-theme \ No newline at end of file From 72ac485772c40ab652fa226577485156ecb2d4d2 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:15:05 -0800 Subject: [PATCH 05/28] install package requirements to build docs --- .readthedocs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 71277d9..10b95f8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,6 +7,7 @@ build: jobs: post_install: - sphinx-apidoc -o docs sparsecoding + - pip install -r requirements.txt sphinx: configuration: docs/conf.py From 04414539891926033e4487b7d16bfefb482aab74 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:28:42 -0800 Subject: [PATCH 06/28] autogenerate rst files to import --- docs/api.rst | 7 +++++++ docs/conf.py | 4 ++++ docs/index.rst | 7 +------ 3 files changed, 12 insertions(+), 6 deletions(-) create mode 100644 docs/api.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..8ab30de --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,7 @@ +API +=== + +.. autosummary:: + :toctree: generated + + sparsecoding diff --git a/docs/conf.py b/docs/conf.py index 223539d..fad24b8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,6 +6,8 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import os + project = 'sparsecoding' copyright = '2024, RCTN' author = 'RCTN' @@ -16,6 +18,7 @@ extensions = [ 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', ] templates_path = ['_templates'] @@ -28,3 +31,4 @@ html_theme = 'pydata_sphinx_theme' html_static_path = ['_static'] +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f56e6c1..6af82eb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,10 +12,5 @@ documentation for details. .. toctree:: - :maxdepth: 2 - :caption: Contents: - sparsecoding - sparsecoding.data - sparsecoding.priors - modules + api \ No newline at end of file From ade75a6785d6f489fac9018eefa09b5930f8c21e Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:41:20 -0800 Subject: [PATCH 07/28] make submodules importable --- .readthedocs.yaml | 2 +- sparsecoding/__init__.py | 6 ++++++ sparsecoding/data/__init__.py | 4 ++++ sparsecoding/data/datasets/__init__.py | 0 sparsecoding/data/dictionaries/__init__.py | 0 5 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 sparsecoding/data/datasets/__init__.py create mode 100644 sparsecoding/data/dictionaries/__init__.py diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 10b95f8..6e7b8ca 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,7 @@ build: python: "3" jobs: post_install: - - sphinx-apidoc -o docs sparsecoding + - sphinx-apidoc -M -o docs sparsecoding - pip install -r requirements.txt sphinx: diff --git a/sparsecoding/__init__.py b/sparsecoding/__init__.py index 74847a6..bb7144d 100644 --- a/sparsecoding/__init__.py +++ b/sparsecoding/__init__.py @@ -1 +1,7 @@ "Modules for sparse coding." + +from . import models +from . import inference +from . import visualization +from . import priors +from . import data \ No newline at end of file diff --git a/sparsecoding/data/__init__.py b/sparsecoding/data/__init__.py index 6f39034..8dcf25f 100644 --- a/sparsecoding/data/__init__.py +++ b/sparsecoding/data/__init__.py @@ -1 +1,5 @@ """Module for exposing datasets to users.""" + +from . import transforms +from . import datasets +from . import dictionaries \ No newline at end of file diff --git a/sparsecoding/data/datasets/__init__.py b/sparsecoding/data/datasets/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/sparsecoding/data/dictionaries/__init__.py b/sparsecoding/data/dictionaries/__init__.py new file mode 100644 index 0000000..e69de29 From 33af89f00837f45a3ce0b7d4d8993aa5d07c2dd9 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:43:29 -0800 Subject: [PATCH 08/28] change base from sparsecoding to modules --- docs/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 8ab30de..99e5b5c 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,4 +4,4 @@ API .. autosummary:: :toctree: generated - sparsecoding + modules From aae2b05223ee157d53d129c9604301a079525ca5 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:45:32 -0800 Subject: [PATCH 09/28] apidoc output in generated dir --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6e7b8ca..4cb56eb 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,7 @@ build: python: "3" jobs: post_install: - - sphinx-apidoc -M -o docs sparsecoding + - sphinx-apidoc -M -o docs/generated sparsecoding - pip install -r requirements.txt sphinx: From 4ada2ff0b80aaa6cad63c67b8594a5bb83f09eb4 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 15:51:20 -0800 Subject: [PATCH 10/28] change modules to sparsecoding --- docs/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 99e5b5c..8ab30de 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,4 +4,4 @@ API .. autosummary:: :toctree: generated - modules + sparsecoding From 24615e4c3cdfbc7a880ebf55ce0b01f4d6f81dd3 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 15 Nov 2024 16:12:39 -0800 Subject: [PATCH 11/28] docs are generated, however there are errors and when searching the generated docs, inference and models doesnt show up. Need to investigate this issue further --- docs/api.rst | 1 + docs/index.rst | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 8ab30de..3844893 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -2,6 +2,7 @@ API === .. autosummary:: + :toctree: generated sparsecoding diff --git a/docs/index.rst b/docs/index.rst index 6af82eb..3896321 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,5 +12,4 @@ documentation for details. .. toctree:: - api \ No newline at end of file From 5aa550fd1445dade2873eeb45fa5f927ccfaa1ba Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 19:29:49 -0800 Subject: [PATCH 12/28] change theme to rtd, generate API documentation with autodoc --- docs/api.rst | 69 +++++++++++++++++++++++++++++++++++++++---- docs/conf.py | 4 +-- docs/index.rst | 14 ++++----- docs/requirements.txt | 2 +- 4 files changed, 74 insertions(+), 15 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 3844893..7dc6b94 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,8 +1,67 @@ -API -=== +============= +API Reference +============= -.. autosummary:: +.. py:currentmodule:: sparsecoding - :toctree: generated +Dictionary learning models +-------------------------- - sparsecoding +.. automodule:: sparsecoding.models + :members: + :undoc-members: + :show-inheritance: + + +Inference methods +----------------- + +.. automodule:: sparsecoding.inference + :members: + :undoc-members: + :show-inheritance: + + +Visualization tools +------------------- + +.. automodule:: sparsecoding.visualization + :members: + :undoc-members: + :show-inheritance: + + +Priors +------ + +.. automodule:: sparsecoding.priors + :members: + :undoc-members: + :show-inheritance: + + +Datasets +-------- + +.. automodule:: sparsecoding.data.datasets + :members: + :undoc-members: + :show-inheritance: + + +Whitening and sphering +---------------------- + +.. automodule:: sparsecoding.data.transforms.whiten + :members: + :undoc-members: + :show-inheritance: + + +Extracting image patches +------------------------ + +.. automodule:: sparsecoding.data.transforms.patch + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index fad24b8..2c3cf75 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,7 +8,7 @@ import os -project = 'sparsecoding' +project = 'RCTN sparsecoding' copyright = '2024, RCTN' author = 'RCTN' @@ -29,6 +29,6 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'pydata_sphinx_theme' +html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3896321..213aa61 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,13 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -sparsecoding documentation -========================== - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. +########################################### +Welcome to the RCTN sparsecoding repository +########################################### .. toctree:: - api \ No newline at end of file + :maxdepth: 1 + :numbered: + + api diff --git a/docs/requirements.txt b/docs/requirements.txt index b341987..9ab2504 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ . sphinx -pydata-sphinx-theme \ No newline at end of file +sphinx-rtd-theme \ No newline at end of file From 56c448063d8d61f9d6f02bcda2e57a630acea7bf Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 19:34:13 -0800 Subject: [PATCH 13/28] change python 3 to 3.7 --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4cb56eb..47ace67 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -3,7 +3,7 @@ version: 2 build: os: ubuntu-24.04 tools: - python: "3" + python: "3.7" jobs: post_install: - sphinx-apidoc -M -o docs/generated sparsecoding From e2bb9d433a8731105125ce0e1b4778c0945cc8a8 Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 20:53:44 -0800 Subject: [PATCH 14/28] upload of install, contributing, and quickstart docs. quickstart doc still needs to be completed --- docs/contributing.rst | 37 +++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 +++ docs/install.rst | 30 ++++++++++++++++++++++++++++++ docs/quickstart.rst | 4 ++++ 4 files changed, 74 insertions(+) create mode 100644 docs/contributing.rst create mode 100644 docs/install.rst create mode 100644 docs/quickstart.rst diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..513741b --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,37 @@ +============ +Contributing +============ + +All contributions are welcome! + +Bug Reporting +------------- + +If you find a bug, submit a bug report on GitHub Issues. + +Adding Features/Fixing Bugs +--------------------------- + +If you have identified a new feature or bug that you can fix yourself, please follow the following procedure. + +#. Clone ``main`` branch. +#. Create a new branch to contain your changes. +#. ``add``, ``commit``, and ``push`` your changes to this branch. +#. Create a pull request (PR). See more information on submitting a PR request below. + +Submitting a Pull Request +------------------------- + +#. If necessary, please **write your own unit tests** and add them to `the tests directory `_. +#. Verify that all tests are passed by running `python -m unittest discover tests -vvv`. +#. Be sure that your PR follows formatting guidelines, `PEP8 `_ and `flake8 `_. +#. Make sure the title of your PR summarizes the features/issues resolved in your branch. +#. Submit your pull request and add reviewers. + +Coding Style Guidelines +----------------------- +We adhere to the `NumPy documentation standards `_. + +#. Format code in accordance with `flake8 `_ standard. +#. Use underscores to separate words in non-class names: ``n_samples`` rather than ``nsamples``. +#. Avoid single-character variable names. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 213aa61..bcbf0d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,4 +12,7 @@ Welcome to the RCTN sparsecoding repository :maxdepth: 1 :numbered: + install + quickstart api + contributing diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..031b19e --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,30 @@ +============ +Installation +============ + +Basic +----- + +The fastest way to install is by cloning the code from Github: + +.. code:: bash + + $ git clone https://github.com/rctn/sparsecoding.git + $ cd sparsecoding + $ pip install -e sparsecoding + $ pip install -r requirements.txt + + +The last line of the code above will install the RCTN sparse coding dependencies: + +- ``numpy`` + +- ``scipy`` + +- ``matplotlib`` + +- ``torch`` + +- ``torchvision`` + + diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..bca4f4e --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,4 @@ +========== +Quickstart +========== + From 491bda143c8f4de453fd04d588031b2fdb2bd964 Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 21:18:39 -0800 Subject: [PATCH 15/28] add quick intro to library --- docs/index.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index bcbf0d8..2a42382 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,10 +3,21 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -########################################### -Welcome to the RCTN sparsecoding repository -########################################### +####################################### +RCTN sparsecoding library documentation +####################################### +`sparsecoding`_ is a python library developed by the `Redwood Center for +Theoretical Neuroscience `_ which contains +performant `pytorch `_ implementations of sparse coding dictionary learning, +inference, and data processing. It was written to be a useful research tool +for applying various sparse coding methods to data. + +We believe that sharing code within the scientific community is an important +part of science and we hope that the research community finds this library +useful. + +.. _sparsecoding: https://github.com/rctn/sparsecoding/ .. toctree:: :maxdepth: 1 From c6c201f9931535ba216cb8ef493ffaf1554967ad Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 21:20:28 -0800 Subject: [PATCH 16/28] add RCTN abbreviation --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 2a42382..7292e78 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ RCTN sparsecoding library documentation ####################################### `sparsecoding`_ is a python library developed by the `Redwood Center for -Theoretical Neuroscience `_ which contains +Theoretical Neuroscience (RCTN) `_ which contains performant `pytorch `_ implementations of sparse coding dictionary learning, inference, and data processing. It was written to be a useful research tool for applying various sparse coding methods to data. From cc0cb9a0114dc35b3193a3c6e01dc4ebd1853cbe Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 21:25:49 -0800 Subject: [PATCH 17/28] add license info --- docs/index.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 7292e78..0227015 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,3 +27,9 @@ useful. quickstart api contributing + + +License +------- + +`sparsecoding`_ has a BSD-3-clause license, as found in the `LICENSE `_ file. \ No newline at end of file From 9b5c5774196308a55de0a8e55eca25c499f2056f Mon Sep 17 00:00:00 2001 From: belsten Date: Tue, 19 Nov 2024 21:27:06 -0800 Subject: [PATCH 18/28] remove basic --- docs/install.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 031b19e..deff6eb 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -2,10 +2,7 @@ Installation ============ -Basic ------ - -The fastest way to install is by cloning the code from Github: +The fastest way to install is by cloning the library from Github: .. code:: bash From 573c39e2a0565cd9ed068626f9700b3eb4421174 Mon Sep 17 00:00:00 2001 From: belsten Date: Wed, 20 Nov 2024 09:49:14 -0800 Subject: [PATCH 19/28] minor formating edits to fix sphinx formatting warnings --- sparsecoding/inference.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sparsecoding/inference.py b/sparsecoding/inference.py index b3c3cb2..c244f5a 100644 --- a/sparsecoding/inference.py +++ b/sparsecoding/inference.py @@ -856,8 +856,8 @@ class OMP(InferenceMethod): """ Infer coefficients for each image in data using elements dictionary. Method description can be traced to: - "Orthogonal Matching Pursuit: Recursive Function Approximation with Application to Wavelet Decomposition" - (Y. Pati & R. Rezaiifar & P. Krishnaprasad, 1993) + "Orthogonal Matching Pursuit: Recursive Function Approximation with Application to Wavelet Decomposition" + (Y. Pati & R. Rezaiifar & P. Krishnaprasad, 1993) """ def __init__(self, sparsity, solver=None, return_all_coefficients=False): From 794a21f73a6d5a1bb2dc9598dfacb4be650a7071 Mon Sep 17 00:00:00 2001 From: belsten Date: Wed, 20 Nov 2024 10:36:10 -0800 Subject: [PATCH 20/28] added structure of library. Note its not exacly correct. It reflects restructure proposed in recent issue. --- docs/quickstart.rst | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index bca4f4e..57e170d 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -2,3 +2,47 @@ Quickstart ========== +Overview +-------- + +.. _sparsecoding: https://github.com/rctn/sparsecoding/ + +`sparsecoding`_ is a python package that provides tools for using sparse coding algorithms. +Historically, sparse coding has been largely focused on learning sparse representations +of images and we provide visualization and transformation tools to work with such data. +However, we've tried to structure the dictionary learning methods and inference methods +in a manner that is data-agnostic. + +The `sparsecoding`_ library is largely built using PyTorch which enables it to inheret +many performance benifits. These include: + +- GPU support + +- Batched operations + +- Auto-grad optimizers + + + +Structure of library +-------------------- + +The functionalities of `sparsecoding`_ are broken into differnent modules. + +- ``sparsecoding.models`` contains dictionary learning models (e.g. SparseCoding). + +- ``sparsecoding.inference`` contains algorithms for computing latent coefficients. + +- ``sparsecoding.visualization`` contains tools for visualizing image dictionaries and data. + +- ``sparsecoding.priors`` contains methods for sampling from various sparse coding priors. + +- ``sparsecoding.datasets`` contains methods for loading datasets. + +- ``sparsecoding.transforms`` contains methods working with data, such as whitening and extracting patches from images. + + +Getting started +--------------- + +`See example notebooks `_. \ No newline at end of file From fc67721d948d304d12897312e59e03ccfcf07dc8 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 22 Nov 2024 17:01:32 -0800 Subject: [PATCH 21/28] rename transformations --- docs/api.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 7dc6b94..61f2801 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -43,25 +43,25 @@ Priors Datasets -------- -.. automodule:: sparsecoding.data.datasets +.. automodule:: sparsecoding.datasets :members: :undoc-members: :show-inheritance: -Whitening and sphering ----------------------- +Data transformations +-------------------- -.. automodule:: sparsecoding.data.transforms.whiten +.. automodule:: sparsecoding.transforms.whiten :members: :undoc-members: :show-inheritance: -Extracting image patches ------------------------- +Image transformations +--------------------- -.. automodule:: sparsecoding.data.transforms.patch +.. automodule:: sparsecoding.transforms.patch :members: :undoc-members: :show-inheritance: \ No newline at end of file From 139dea9efc389fe529fe1b36121b59bc57ca986b Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 22 Nov 2024 17:02:00 -0800 Subject: [PATCH 22/28] delete unnecessary utils and init --- sparsecoding/data/__init__.py | 5 ----- sparsecoding/data/utils.py | 37 ----------------------------------- 2 files changed, 42 deletions(-) delete mode 100644 sparsecoding/data/__init__.py delete mode 100644 sparsecoding/data/utils.py diff --git a/sparsecoding/data/__init__.py b/sparsecoding/data/__init__.py deleted file mode 100644 index 8dcf25f..0000000 --- a/sparsecoding/data/__init__.py +++ /dev/null @@ -1,5 +0,0 @@ -"""Module for exposing datasets to users.""" - -from . import transforms -from . import datasets -from . import dictionaries \ No newline at end of file diff --git a/sparsecoding/data/utils.py b/sparsecoding/data/utils.py deleted file mode 100644 index 7eccfc2..0000000 --- a/sparsecoding/data/utils.py +++ /dev/null @@ -1,37 +0,0 @@ -import os -import torch -import numpy as np -import pickle as pkl - -MODULE_PATH = os.path.dirname(__file__) -DATASET_PATH = os.path.join(MODULE_PATH, "datasets") -DICTIONARY_PATH = os.path.join(MODULE_PATH, "dictionaries") - -BARS_DICT_PATH = os.path.join(DICTIONARY_PATH, "bars", "bars-16_by_16.p") -OLSHAUSEN_DICT_PATH = os.path.join(DICTIONARY_PATH, "olshausen", "olshausen-1.5x_overcomplete.p") - - -def load_dictionary_from_pickle(path): - dictionary_file = open(path, 'rb') - numpy_dictionary = pkl.load(dictionary_file) - dictionary_file.close() - dictionary = torch.tensor(numpy_dictionary.astype(np.float32)) - return dictionary - - -def load_bars_dictionary(): - path = BARS_DICT_PATH - dictionary_file = open(path, 'rb') - numpy_dictionary = pkl.load(dictionary_file) - dictionary_file.close() - dictionary = torch.tensor(numpy_dictionary.astype(np.float32)) - return dictionary - - -def load_olshausen_dictionary(): - path = OLSHAUSEN_DICT_PATH - dictionary_file = open(path, 'rb') - numpy_dictionary = pkl.load(dictionary_file) - dictionary_file.close() - dictionary = torch.tensor(numpy_dictionary.astype(np.float32)) - return dictionary From 2426858249490958addc3750caf6f82045d5da04 Mon Sep 17 00:00:00 2001 From: belsten Date: Fri, 22 Nov 2024 17:02:43 -0800 Subject: [PATCH 23/28] remove import from data and add imports of transfrom tools --- sparsecoding/__init__.py | 47 +++++++++++++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/sparsecoding/__init__.py b/sparsecoding/__init__.py index bb7144d..07955ca 100644 --- a/sparsecoding/__init__.py +++ b/sparsecoding/__init__.py @@ -1,7 +1,42 @@ -"Modules for sparse coding." +from .models import SparseCoding +from .inference import LCA, IHT, ISTA, LSM, MP, OMP, Vanilla, PyTorchOptimizer +from .visualization import plot_dictionary, plot_patches +from .priors import SpikeSlabPrior, L0Prior +from .datasets import BarsDataset, FieldDataset +from .dictionaries import ( + load_dictionary_from_pickle, + load_bars_dictionary, + load_olshausen_dictionary, +) -from . import models -from . import inference -from . import visualization -from . import priors -from . import data \ No newline at end of file +__all__ = [ + # Models + "SparseCoding", + + # Inference + "LCA", + "IHT", + "ISTA", + "LSM", + "MP", + "OMP", + "Vanilla", + "PyTorchOptimizer", + + # Visualization + "plot_dictionary", + "plot_patches", + + # Priors + "SpikeSlabPrior", + "L0Prior", + + # Dictionaries + "load_dictionary_from_pickle", + "load_bars_dictionary", + "load_olshausen_dictionary", + + # Datasets + "BarsDataset", + "FieldDataset", +] \ No newline at end of file From 5b004624bf872dc0be95ccedf2e9486c15b5f1db Mon Sep 17 00:00:00 2001 From: belsten Date: Sat, 23 Nov 2024 08:45:54 -0800 Subject: [PATCH 24/28] fixed typos and minor reword --- docs/contributing.rst | 42 ++++++++++++++++++++----------------- docs/install.rst | 21 +++++++------------ docs/quickstart.rst | 48 ++++++++++++++++++------------------------- 3 files changed, 50 insertions(+), 61 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 513741b..16b2981 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -2,36 +2,40 @@ Contributing ============ -All contributions are welcome! +We welcome all contributions! Bug Reporting ------------- -If you find a bug, submit a bug report on GitHub Issues. +If you encounter a bug, please report it by creating an issue on GitHub. -Adding Features/Fixing Bugs ---------------------------- +Adding Features or Fixing Bugs +------------------------------ -If you have identified a new feature or bug that you can fix yourself, please follow the following procedure. +If you’ve identified a new feature to add or a bug you can fix, follow these steps: -#. Clone ``main`` branch. -#. Create a new branch to contain your changes. -#. ``add``, ``commit``, and ``push`` your changes to this branch. -#. Create a pull request (PR). See more information on submitting a PR request below. +#. Clone the ``main`` branch. +#. Create a new branch to work on your changes. +#. Use ``add``, ``commit``, and ``push`` to save your changes to the new branch. +#. Create a pull request (PR). See the "Submitting a Pull Request" section for more details. Submitting a Pull Request ------------------------- -#. If necessary, please **write your own unit tests** and add them to `the tests directory `_. -#. Verify that all tests are passed by running `python -m unittest discover tests -vvv`. -#. Be sure that your PR follows formatting guidelines, `PEP8 `_ and `flake8 `_. -#. Make sure the title of your PR summarizes the features/issues resolved in your branch. -#. Submit your pull request and add reviewers. +#. If applicable, write unit tests for your changes and add them to the + `tests directory `_. +#. Verify that all tests pass by running ``python -m unittest discover tests -vvv``. +#. Ensure your code adheres to the formatting guidelines specified in + `PEP8 `_ and validated by + `flake8 `_. +#. Provide a concise and descriptive title for your PR that summarizes the changes made in your branch. +#. Submit your PR and assign reviewers as necessary. Coding Style Guidelines ------------------------ -We adhere to the `NumPy documentation standards `_. +------------------------ -#. Format code in accordance with `flake8 `_ standard. -#. Use underscores to separate words in non-class names: ``n_samples`` rather than ``nsamples``. -#. Avoid single-character variable names. \ No newline at end of file +We follow the `NumPy documentation standards `_. + +1. Format your code according to the `flake8 `_ standard. +2. Use underscores to separate words in non-class names (e.g., ``n_samples`` instead of ``nsamples``). +3. Avoid single-character variable names. diff --git a/docs/install.rst b/docs/install.rst index deff6eb..e71e79f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -2,26 +2,19 @@ Installation ============ -The fastest way to install is by cloning the library from Github: +The quickest way to install the library is by cloning it directly from GitHub: .. code:: bash - $ git clone https://github.com/rctn/sparsecoding.git - $ cd sparsecoding - $ pip install -e sparsecoding - $ pip install -r requirements.txt + git clone https://github.com/rctn/sparsecoding.git + cd sparsecoding + pip install -e sparsecoding + pip install -r requirements.txt +The last command installs the dependencies required for the RCTN sparse coding library, including: -The last line of the code above will install the RCTN sparse coding dependencies: - -- ``numpy`` - +- ``numpy`` - ``scipy`` - - ``matplotlib`` - - ``torch`` - - ``torchvision`` - - diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 57e170d..bc6ccb1 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -7,42 +7,34 @@ Overview .. _sparsecoding: https://github.com/rctn/sparsecoding/ -`sparsecoding`_ is a python package that provides tools for using sparse coding algorithms. -Historically, sparse coding has been largely focused on learning sparse representations -of images and we provide visualization and transformation tools to work with such data. -However, we've tried to structure the dictionary learning methods and inference methods -in a manner that is data-agnostic. +`sparsecoding`_ is a Python package that provides tools for implementing sparse coding algorithms. +Traditionally, sparse coding has been primarily used for learning sparse representations of images. +To support this, we include tools for visualization and data transformation specific to image data. +However, we have designed the dictionary learning and inference methods to be data-agnostic, +allowing for broader applications. -The `sparsecoding`_ library is largely built using PyTorch which enables it to inheret -many performance benifits. These include: +The `sparsecoding`_ library is built largely on PyTorch, enabling it to inherit several +performance benefits, such as: - GPU support - - Batched operations - - Auto-grad optimizers +Structure of the Library +------------------------- +The functionalities of `sparsecoding`_ are organized into several modules: -Structure of library --------------------- - -The functionalities of `sparsecoding`_ are broken into differnent modules. - -- ``sparsecoding.models`` contains dictionary learning models (e.g. SparseCoding). - -- ``sparsecoding.inference`` contains algorithms for computing latent coefficients. - -- ``sparsecoding.visualization`` contains tools for visualizing image dictionaries and data. - -- ``sparsecoding.priors`` contains methods for sampling from various sparse coding priors. - -- ``sparsecoding.datasets`` contains methods for loading datasets. - -- ``sparsecoding.transforms`` contains methods working with data, such as whitening and extracting patches from images. - +- ``sparsecoding.models``: Contains dictionary learning models (e.g., SparseCoding). +- ``sparsecoding.inference``: Includes algorithms for computing latent coefficients. +- ``sparsecoding.visualization``: Provides tools for visualizing image dictionaries and data. +- ``sparsecoding.priors``: Offers methods for sampling from various sparse coding priors. +- ``sparsecoding.datasets``: Contains utilities for loading datasets. +- ``sparsecoding.transforms``: Includes methods for working with data, such as whitening and + extracting patches from images. -Getting started +Getting Started --------------- -`See example notebooks `_. \ No newline at end of file +Explore our `example notebooks `_ +to get started. From 222e1abe3573d597330f566ce72a037f48193fc6 Mon Sep 17 00:00:00 2001 From: belsten Date: Sat, 23 Nov 2024 09:12:23 -0800 Subject: [PATCH 25/28] update readme to provide pointers to the readthedocs. delete obsolete contributing.md as updated material is now in the readthedocs --- README.md | 51 +++++++++++++++++++------------ docs/contributing.md | 72 -------------------------------------------- 2 files changed, 32 insertions(+), 91 deletions(-) delete mode 100644 docs/contributing.md diff --git a/README.md b/README.md index b89f028..8056fbc 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,38 @@ -# Sparse Coding -Reference sparse coding implementations for efficient learning and inference implemented in PyTorch with GPU support. +# RCTN SparseCoding Library -## Dictionary Learning -* Repo currently includes classic patch-wise sparse coding dictionary learning. +`sparsecoding` is a Python library developed by UC Berkeley's [Redwood Center for Theoretical Neuroscience (RCTN)](https://redwood.berkeley.edu). It provides efficient, batched, and GPU-compatible [PyTorch](https://github.com/pytorch/pytorch) implementations for sparse coding related-algorithms, including dictionary learning, inference, and data processing. -## Implemented Inference Methods -* Locally Competative Algorithm (LCA) -* Gradient Descent with Euler's method on Laplace Prior (Vanilla) -* Laplacian Scale Mixture (LSM) -* Iterative Shrinkage-threshold Algorithm (ISTA) -* Generic PyTorch minimization of arbitrary loss function (PyTorchOptimizer) +Historically, sparse coding has been largely focused on learning sparse representations of images and we provide visualization and transformation tools to work with such data. However, we’ve tried to structure the transformation, dictionary learning methods, and inference methods in a manner that is data-agnostic, making them applicable to a wide range of use cases. + +We believe that sharing code within the scientific community is an important part of science and we hope that the research community finds this library useful. + +--- + +## Features + +- Check out our [Quickstart Guide](https://sparsecoding.readthedocs.io/en/latest/quickstart.html) for an overview and setup instructions. +- Refer to the [API Reference](https://sparsecoding.readthedocs.io/en/latest/api.html) for detailed usage of the library's features. + +--- + +## Setup + +To install the library, follow these steps: + +```bash +git clone https://github.com/rctn/sparsecoding.git +cd sparsecoding +pip install -e . +pip install -r requirements.txt +``` + +For more detailed instructions, see our [Installation Guide](https://sparsecoding.readthedocs.io/en/latest/install.html). + +Note: If you're using a Jupyter notebook and make changes to the source files, you can either: +* Restart the Jupyter kernel, or +* Use the autoreload extension as explained [here](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html#autoreload). -# Setup -1. Clone the repo. -2. Navigate to the directory containing the repo directory. -3. Run `pip install -e sparsecoding` -4. Navigate into the repo and install the requirements using `pip install -r requirements.txt` -5. Install the natural images dataset from this link: https://rctn.org/bruno/sparsenet/IMAGES.mat -6. Try running the demo notebook: `examples/sparse_coding.ipynb` -Note: If you are using a Jupyter notebook and change a source file, you can either: 1) restart the Jupyter kernel, or 2) follow instructions [here](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html#autoreload). # Contributing -See the [contributing](docs/contributing.md) document! +We welcome contributions! Please see our [contributing](https://sparsecoding.readthedocs.io/en/latest/contributing.html) for details on how to get involved. diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 804bdba..0000000 --- a/docs/contributing.md +++ /dev/null @@ -1,72 +0,0 @@ -# Contributing -All contributions are welcome! - -## Bug Reporting -If you find a bug, submit a bug report on GitHub Issues. - -## Adding Features/Fixing Bugs -If you have identified a new feature or bug that you can fix yourself, please follow the following procedure. - -1. Clone `main` branch. -2. Create a new branch to contain your changes. -2. `add`, `commit`, and `push` your changes to this branch. -3. Create a pull request (PR). See more information on submitting a PR request below. - -### Submitting a Pull Request -1. If necessary, please **write your own unit tests** and add them to [the tests directory](https://github.com/rctn/sparsecoding/blob/main/docs/contributing.md). -2. Verify that all tests are passed by running `python -m unittest tests/*`. -3. Be sure that your PR follows formatting guidelines, [PEP8](https://peps.python.org/pep-0008/) and [flake8](https://flake8.pycqa.org/en/latest/). -4. Make sure the title of your PR summarizes the features/issues resolved in your branch. -5. Submit your pull request and add reviewers. - -## Coding Style Guidelines -The following are some guidelines on how new code should be written. Of course, there are special cases, and there will be exceptions to these rules. - -1. Format code in accordance with [flake8](https://flake8.pycqa.org/en/latest/) standard. -2. Use underscores to separate words in non-class names: `n_samples` rather than `nsamples`. -3. Avoid single-character variable names. - -## Docstrings -When writing docstrings, please follow the following example. - -``` -def count_beans(self, baz, use_gpu=False, foo="vector" - bar=None): - """Write a one-line summary for the method. - - Parameters - ---------- - baz : array-like, shape [..., dim] - Write a short description of parameter baz. - use_gpu : bool, default=False - Write a short description of parameter use_gpu. - foo : str, {"vector", "matrix"}, default="vector" - Write a short description of parameter foo. - bar : array-like, shape [...,], optional - Write a short description of parameter bar. - - Returns - ------- - n_beans : array-like, shape [..., dim, dim] - Write a short description of the result returned by the method. - - Notes - ----- - If relevant, provide equations with (:math:) - describing computations performed in the method. - - Example - ------- - Provide code snippets showing how the method is used. - You can link to scripts of the examples/ directory. - - Reference - --------- - If relevant, provide a reference with associated pdf or - wikipedia page. - ex: - [1] Einstein, A., Podolsky, B., & Rosen, N. (1935). Can - quantum-mechanical description of physical reality be - considered complete?. Physical review, 47(10), 777. - """ -``` \ No newline at end of file From cdf20b3ce224e6ae535b5f17ec06eafc62b2383b Mon Sep 17 00:00:00 2001 From: belsten Date: Sat, 23 Nov 2024 09:13:32 -0800 Subject: [PATCH 26/28] remove accidental horizontal lines --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 8056fbc..2741e2c 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,12 @@ Historically, sparse coding has been largely focused on learning sparse represen We believe that sharing code within the scientific community is an important part of science and we hope that the research community finds this library useful. ---- ## Features - Check out our [Quickstart Guide](https://sparsecoding.readthedocs.io/en/latest/quickstart.html) for an overview and setup instructions. - Refer to the [API Reference](https://sparsecoding.readthedocs.io/en/latest/api.html) for detailed usage of the library's features. ---- ## Setup @@ -33,6 +31,5 @@ Note: If you're using a Jupyter notebook and make changes to the source files, y * Use the autoreload extension as explained [here](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html#autoreload). - # Contributing We welcome contributions! Please see our [contributing](https://sparsecoding.readthedocs.io/en/latest/contributing.html) for details on how to get involved. From 4b19a42c0a1b07b76a0915bff20b4f93731c4e11 Mon Sep 17 00:00:00 2001 From: belsten Date: Thu, 28 Nov 2024 08:11:27 -0800 Subject: [PATCH 27/28] add documentation badge to readme --- README.md | 3 +++ sparsecoding/__init__.py | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2741e2c..59617dc 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # RCTN SparseCoding Library +[![Documentation status](https://readthedocs.org/projects/sparsecoding/badge/)]( +https://sparsecoding.readthedocs.io/) + `sparsecoding` is a Python library developed by UC Berkeley's [Redwood Center for Theoretical Neuroscience (RCTN)](https://redwood.berkeley.edu). It provides efficient, batched, and GPU-compatible [PyTorch](https://github.com/pytorch/pytorch) implementations for sparse coding related-algorithms, including dictionary learning, inference, and data processing. Historically, sparse coding has been largely focused on learning sparse representations of images and we provide visualization and transformation tools to work with such data. However, we’ve tried to structure the transformation, dictionary learning methods, and inference methods in a manner that is data-agnostic, making them applicable to a wide range of use cases. diff --git a/sparsecoding/__init__.py b/sparsecoding/__init__.py index 07955ca..d233a2c 100644 --- a/sparsecoding/__init__.py +++ b/sparsecoding/__init__.py @@ -39,4 +39,4 @@ # Datasets "BarsDataset", "FieldDataset", -] \ No newline at end of file +] From a33b1e0657abdda85eacd15175ac10bab7b4296f Mon Sep 17 00:00:00 2001 From: belsten Date: Thu, 28 Nov 2024 08:40:23 -0800 Subject: [PATCH 28/28] flake8 docs --- docs/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2c3cf75..9ab4d69 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,10 +25,9 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] -html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") \ No newline at end of file +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")