How to install

How to install#

Before installing pycif, some libraries and python packages are needed. The list below is not necessary comprehensive and may depend on the OS and machine you use. For easy installation, it is recommended to use conda (see below for details). To help new users testing the CIF, a docker image has been designed, with all requirements properly installed.

Requirements#

Please see here for details on the CIF docker image.

the following libraries and packages must be installed on your server:

  • python >=3.6:

    pycif is designed for python 3.6 or above; compatibility with python 2.7 has been lost and is not maintained anymore;

  • git:

    can be installed following instructions from git-scm.com

  • geographical and binary tools:
    pycif is based on the following geographical and binary libraries:
  • basic libraries and tools (most likely already installed on most systems):

The following python packages must be installed before getting pycif:

Using conda for requirements#

conda enables an easy handling of package installations and virtual environments. If you are using conda, please find below some instructions to install required packages:

# Packages installed in Conda base environment
conda activate base
conda install --yes numpy scipy matplotlib h5py netcdf4 gdal
conda install --yes -c conda-forge pyhdf

# Make a pyCIF environment
conda deactivate
conda create --clone base --name cif
conda activate cif

# Install remaining packages for pyCIF
conda install --yes -c conda-forge openblas pyyaml pandas xarray cython shapely psutil pillow future cfgrib

# Check if the packages are installed
conda list "(gdal|openblas|pyyaml|pandas|xarray|cython|shapely|psutil|pillow|future|cfgrib)"

You can also find here a conda virtual environment file to automatically create a virtual environment. Copy the content of the link in a text file and use the command:

conda create --name <env> --file <the file>

Don’t forget to activate your environment before installing pyCIF below:

conda activate cif

Getting the code#

The main server hosting the CIF is: git.nilu.no/VERIFY/CIF. Anyone can clone sources and start using them. At the top right of the git-page there’s a blue button with the word “Clone”. If you click on that, you’ll see two options, one is “Clone with SSH”, the other “Clone with HTTPS”. Both options give you an address which you can use in a git command:

git clone GIT/ADDRESS /where/you/want/the/sources

Please be aware that the SSH address works only for users registered at the NILU server. Contributors to the CIF can ask for a login by sending a mail at help@community-inversion.eu

For other users, please use the HTTPS address.

To get updates from the master version of the CIF, use the following colomn:

git pull origin master

For further git commands: try.github.io

Installing pycif#

Installation as fixed third-party module#

Installation on the system#

pyCIF is a python module that can be installed to your python environment.

You can install the CIF as a third-party package. It will add it to the list of available packages exactly like when using conda or pip:

cd /where/you/have/the/sources
pip install .

Please be aware that the command will try to modify some system files, hence requiring super-user authorization. If you have admin rights on your server, you may use the sudo prefix.

Installation on the user environment#

Python also offers the possibility of installing thrid-party packages on the user environment only, which do not requires admin rights:

cd /where/you/have/the/sources
pip install --user .

Installation with Anaconda#

If you are using Anaconda to manage your Python environment, the installation of pyCIF works similarly to the installation on the general system,

without the need of super-user permission:

conda activate my_conda_environment
cd /where/you/have/the/sources
python -m pip install .

Installation with debugging features#

Despite all our efforts to have a distributed version of pycif as stable and robust as possible, thus if you plan to do any modification (to fix bugs, implement your own plugins, understand the code better by printing intermediate states, etc.), use the following command (valid for super-users and users with Anaconda environments):

cd /where/you/have/the/sources
pip install -e .

or (as a user stand-alone python installation):

cd /where/you/have/the/sources
pip install --user -e .

Thus, any modification you do on the code will be directly accessible to python scripts using pycif.

Contributing to pycif#

pycif is a research participative project. Any bug-fixes, plugin developments or general contribution to the present documentation are very welcome. Guidelines for some typical developments are given here.

In any case, contributions should follow as closely as possible PEP8 standards.

When doing developments, it is recommended to create a new branch to the git structure. To do so, please follow the steps:

cd /where/you/have/the/sources
git checkout -b [name_of_your_new_branch]

This create a new local branch from the master. You can then commit your modifications to this branch.

Once you are satisfied by your new version, you can push it to the main server:

git push origin [name_of_your_new_branch]

Please note that this last step requires a login to the NILU server. If you don’t have one yet, you can send a mail to help@community-inversion.eu

To propagate your changes to the master branch, you need to submit a merge request to the git server. Please visit this page to merge your branch.

Contents