Installation

Installation with conda

This is the recommended way for all systems.

This approach is independent of the OS used.

If you have conda package manager, you can install lbsntransform dependencies with the environment.yml that is available in the lbsntransform repository:

name: lbsntransform
channels:
  - conda-forge
  - defaults
dependencies:
  - python>=3.5
  - pip
  - emoji>=0.5.1
  - numpy
  - protobuf
  - shapely
  - requests
  - nltk
  - psycopg2
  - regex
  - pip:
    - lbsnstructure>=0.5.1
    - ppygis3>=0.4
    - geos

  1. Create a conda env using environment.yml
git clone https://github.com/Sieboldianus/lbsntransform.git
cd lbsntransform
# not necessary, but recommended:
conda config --env --set channel_priority strict
conda env create -f environment.yml
  1. Install lbsntransform without dependencies
conda activate lbsntransform

Either, use the release version from pypi. This will create a static installation that needs to be manually upgraded when new package versions appear.

pip install lbsntransform --no-deps --upgrade

Or use pip --editable, linking the lbsntransform folder:

pip install --no-deps --editable .

This is the recommended way if you want to edit files, or use the latest commits from the repository.

The lbsntransform package will be directly linked to the folder.

Why isn't the package available on conda-forge?

This is planned to happen in one of the next versions..

Docker

If you have Docker, and if you do not want to develop or make changes to lbsntransform, using our Dockerimage may be an option.

Note

The Docker Image is in an early stage. Providing input data is only possible through URL, from another database, or through local bind mounting data (e.g. CSVs) into the container (see note at end).

You can use the latest Dockerimage to directly run lbsntransform in a container:

First, pull the image.

docker pull registry.gitlab.vgiscience.org/lbsn/lbsntransform:latest
docker tag registry.gitlab.vgiscience.org/lbsn/lbsntransform:latest lbsntransform

Then run it.

docker run \
    --rm \
    lbsntransform \
    --version

Note

Replace --version with the CLI commands for your use case.

Or, use the Dockerfile in docker/Dockerfile to build the image yourself.

FROM python:slim

COPY lbsntransform/ ./lbsntransform/
COPY resources/ ./resources/
COPY setup.py README.md ./

RUN set -ex; \
    \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        libpq-dev \
        build-essential \
    ; \
    pip install --upgrade pip; \
    pip install psycopg2-binary; \
    pip install --ignore-installed --editable . \
    ; \
    apt-get purge -y \
        build-essential \
    ; \
    apt-get autoremove -y \
    ; \
    rm -rf /var/lib/apt/lists/*;

ENTRYPOINT ["lbsntransform"]

Example:

docker build -t lbsntransform -f docker/Dockerfile .
docker run \
    --rm \
    lbsntransform \
    --version

Mounting data

If you want to use custom mappings, or read data from CSV (etc.), mount these external files on runtime into the container.

Example:

docker run \
    --rm \
    --volume $(pwd)/data.csv:/data/data.csv \
    --volume $(pwd)/resources/mappings:/mappings \
    lbsntransform \
    --mappings_path /mappings/ \
    ...

Alternatives: Windows and Linux

Windows

There are many ways to install python tools, in Windows this can become particularly frustrating.

Note

The recommended way to run lbsntransform in Windows is either through Docker or in conda, ideally run from Windows Subsystem for Linux (WSL 1 or 2).

  1. It is possible to install install lbsntransform with conda package manager in Windows directly. In this case, unlike conda in Linux and in our environment.yml, it is recommended to install geos from conda, not from pypi.
  2. If you need to install with pip in Windows, a possible approach is to install all dependencies first (use Gohlke wheels if necessary) and then install lbsntransform with
pip install lbsntransform --no-deps

Linux

Note

Use of pip can be problematic, even on Linux. Some sub-dependencies outside python cannot be managed by pip, such as libpq-dev, which is required by psycopg2. Use conda if you're new to python package managers. You've been warned.

For most Linux users, it is recommended to first create some type of virtual environment, and then install lbsntransform in the virtual env, e.g.:

apt-get install -y libpq-dev # required for psycopg2
apt-get install python3-venv # required for virtual env
python3 -m venv lbsntransform_env
source ./lbsntransform_env/bin/activate
pip install lbsntransform

You can also directly install the latest release of lbsntransform with pip:

pip install lbsntransform

..or, clone the repository and install lbsntransform directly:

git clone https://github.com/Sieboldianus/lbsntransform.git
cd lbsntransform
python setup.py install