Installation¶

Info

We recommend installation in Linux (or Windows Subsystem for Linux). Native Windows installations are not heavily tested.

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>=2.0.0
  - numpy
  - protobuf>=4.21.9,<5
  - shapely<2.0.0
  - requests
  - nltk
  - psycopg2
  - regex
  - pip:
    - lbsnstructure>=1.2.0
    - ppygis3>=0.4
    - geos

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

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 src/ ./src/
COPY resources/ ./resources/
COPY pyproject.toml README.md ./

RUN set -ex; \
    \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        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).

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.
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 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
pip install .

Optional feature: NLTK stopwords filter¶

If you want to filter list of terms based on NLTK stopwords, install nltk and download the stopwords once.

You can activate this optional feature during installation of lbsntransform using extras:

pip install 'lbsntransform[nltk_stopwords]'
python -c 'import nltk;nltk.download("stopwords")'

.. or afterwards:

pip install nltk
python -c 'import nltk;nltk.download("stopwords")'