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