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.
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;
can be installed following instructions from git-scm.com
The following python packages must be installed before getting pycif:
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
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 email@example.com
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
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
cd /where/you/have/the/sources python setup.py 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
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 python setup.py install --user
- 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 setup.py install
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 python setup.py develop
or (as a user stand-alone python installation):
cd /where/you/have/the/sources python setup.py develop --user
Thus, any modification you do on the code will be directly accessible to python scripts using 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 firstname.lastname@example.org
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.