fastsom 1.0.2
A PyTorch and Fastai based implementation of Self-Organizing Maps
License: MIT
Keywords: self-organizing-map,fastai,pytorch,python

# Fastsom

A PyTorch and Fastai based implementation of Self-Organizing Maps.

You can find documentation and examples [here](https://kireygroup.github.io/fastsom/).

![PyPI](https://img.shields.io/pypi/v/fastsom?style=flat-square)

## Contents

- [Fastsom](#fastsom)
  - [Contents](#contents)
  - [Getting started](#getting-started)
    - [Install as a dependency](#install-as-a-dependency)
  - [Docker boilerplate](#docker-boilerplate)
    - [Prerequisites](#prerequisites)
    - [Building the image](#building-the-image)
    - [Running the container](#running-the-container)
    - [Developing inside the container](#developing-inside-the-container)
  - [Documentation setup](#documentation-setup)
    - [Documenting the code](#documenting-the-code)
    - [Building the docs](#building-the-docs)
    - [Deploying the docs on GH Pages](#deploying-the-docs-on-gh-pages)

## Getting started

### Install as a dependency

To install Fastsom, you can use `pip` to install the [PyPi package](https://pypi.org/project/fastsom/):

```bash
pip install fastsom
```

or you can install directly from Github:

```bash
pip install git+ssh://github.com/kireygroup/fastsom
# or
pip install git+https://github.com/kireygroup/fastsom
```

Alternatively, you can clone the repository and then install as follows:

```bash
git clone git@github.com:kireygroup/fastsom
cd fastsom
python setup.py install
```

## Docker boilerplate

This project was bootstrapped with the [cookiecutter-dl-docker](https://github.com/rsayn/cookiecutter-dl-docker) template.

### Prerequisites

To run examples for this project you can either use Docker / Nvidia-Docker or recreate the environment on your local machine by using the provided `requirements.txt`.

Steps for Docker are described below.

### Building the image

An utility script can be found in `bin/build.sh`:

```bash
./bin/build.sh
```

### Running the container

A run script is available:

```bash
./bin/run.sh
```

This will mount the directories `/fastsom` and `/nbs` inside the container, allowing for code changes to be automatically replicated.

Note: if you plan on using Nvidia-Docker, you should use one of the images available on the Nvidia Container Repository.

The container will start a new Jupyter Notebook server on port 8888. Jupyter Lab is also available.

Note that the `fastsom` folder will be mounted inside the container, so any change you make to the source files or notebooks will be replicated on both host and container.

### Developing inside the container

With Visual Studio Code and PyCharm, it is possible to use the container Python interpreter for development.

An SSH server has been configured inside the container to allow connection via PyCharm's remote interpreter feature.

In Visual Studio Code, this can be done via the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

## Documentation setup

Fastsom's documentation is built with [Sphinx](https://www.sphinx-doc.org/) and deployed to Gihtub Pages via the [`gh-pages` branch](https://github.com/kireygroup/fastsom/tree/gh-pages).

### Documenting the code

We use a Numpy docstring notation (check out [this link](http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) for more information about the various docstring styles).

### Building the docs

To generate the static HTML documentation, use the following:

```bash
cd docs
make docs
```

### Deploying the docs on GH Pages

Docs are automatically built from the master branch and pushed to the `gh-pages` branch on each version tag.