17. Installation

17.1. Dependencies

  • numpy, scipy -> Mandatory, automatically installed by pip
  • Pillow -> Mandatory, for reading of SAXS images, automatic install by pip
  • matplotlib -> Mandatory, for 3D plots and on Windows
  • Ipython -> Optional, for convenience as a powerful python shell
  • gfortran -> Optional, without some functions dont work or use a slower python version
  • xmgrace -> Optional, preferred plotting on Unix like (use matplotlib on Windows)

Installation of gfortran/xmgrace may need root privileges. Use “sudo” on Linux and MacOS if needed.

17.2. Pip installation/upgrade

(use pip2 or pip3 if NOT your default Python should be used)

sudo pip install jscatter

As user in home directory (pip default installation directory is in ~/.local/). No sudo needed, only user privileges, you don’t need the admin to install/update:

pip install jscatter --user

from a local repository (development versions):

pip install jscatter --user --upgrade --pre --find-links /where/the/file/is/saved

options
--user       : Install in user directory (folder defined by PYTHONUSERBASE or the default ~/.local)
--find-links : look in the given path for package links e.g development releases
--upgrade    : to install upgrades also for dependencies
--pre        : to install also development versions

17.3. Linux

  • Ubuntu, all Debian related

    sudo apt-get install gfortran grace python-matplotlib  # or python3-matplotlib
    sudo pip install ipython
    sudo pip install jscatter
    
  • CentOs, Suse, Fedora … do same as above but with yum/zypper…

  • Manjaro Linux (yaourt asks for permission as root or prepend sudo as above)

    # install gfortran
    yaourt gcc-fortran
    # install xmgrace (only found in AUR), fonts are needed for the interface, fonts are loaded after restart
    yaourt xorg-fonts-75 xorg-fonts-100 grace-openmotif python-matplotlib
    # tk might be missing for tkinter as matplotlib backend
    sudo pacman -S tk
    pip install ipython
    pip install jscatter
    
  • CONTIN in DLS module (Only if needed).

    See DLS module documentation for details how to get and compile the original fortran code.

17.4. MacOs

Install Homebrew first as given on their web page (see Homebrew)

# install XQuartz from homebrew or from the AppStore
sudo brew cask install xquartz
# install xmgrace and gfortran
sudo brew install grace gfortran matplotlib
# then use pip
sudo pip install ipython
sudo pip install jscatter

17.5. Windows

17.5.1. Windows Subsystem for Linux with Ubuntu way

A new way is based on Windows Subsystem for Linux (WSL), which “lets developers run GNU/Linux environment – including most command-line tools, utilities, and applications – directly on Windows, unmodified, without the overhead of a virtual machine.” (See WSL)

This allows to use any Linux application including XmGrace or Linux editors. You work on the same filesystem as your Windows user account without the need of syncing folders or using a shared folder from a virtual machine. Up to now i didnt test gfortran.

The basic procedure is to activate WSL, install Linux and Xserver, add your needed Linux software in the usual way.

  • Install WSL

    See https://docs.microsoft.com/de-de/windows/wsl/install-win10

    or in Powershell as administrator

    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
    
  • Then install a linux distribution of choice from Windows store (tested with Ubuntu 18.04). (The install is per user, so do it under your user account, not as administrator)

    Open a terminal, start bash and set user and password for Linux. (See https://docs.microsoft.com/en-us/windows/wsl/initialize-distro )

  • For graphical applications: Install Xserver VcXsrv (or an other Xserver).

    See e.g. https://seanthegeek.net/234/graphical-linux-applications-bash-ubuntu-windows/ . Download from https://sourceforge.net/projects/vcxsrv/ . Install (start always manually or add to Windows autostart).

  • Configure bash to use the local X server

    Add this to .bashrc

    export DISPLAY=localhost:0.0
    

    or run this inside bash

    echo "export DISPLAY=localhost:0.0" >> ~/.bashrc
    

    Restart bash or load again .bashrc source ~/.bashrc

  • Install xmgrace, python3 and Jscatter in Linux subsystem

    open terminal, start bash

    sudo apt-get update && upgrade                        # upgrade linux
    sudo apt-get install python3 python3-pip ipython3     # python, ipython and pip3
    sudo apt-get install numpy python3-matplotlib xmgrace
    pip3 install jscatter                                 # jscatter, scipy, Pillow...
    
Run test and example.

17.5.2. Anaconda way

Anaconda is a python distribution as alternative with numpy, scipy, matplotlib, Ipython preinstalled. Need of sudo depends on how Anaconda was installed (root or user). Maybe the matplotlib backend needs to be configured on Windows to work properly.

And there was more to adjust, when i stopped waisting my time. In my testcase it was a pain, but test and examples work (no Xmgrace, no fortran).

I strongly advise to use Linux in a VirtualMachine as it is easier to install and use.

# install jscatter on working anaconda environment
pip install jscatter

17.6. Jupyter Notebook

Jscatter works on Jupyter Notebooks.

To install jscatter on a server Jupyter installation (Jscatter not preinstalled) prepend this on your script

import sys,site
# install jscatter as user in the current Jupyter kernel
!{sys.executable} -m pip install jscatter --user
# append user install dir to path
sys.path.append(site.USER_BASE)

There is some trouble with inline plots (which are not interactive and cannot be updated) dependent on the installed backend. This is related to the used matplotlib backend.

Use this (before importing anything else) to get interactive plots inline.

%matplotlib notebook

Then import Jscatter.

import jscatter as js

js.usempl(True)  # use matplotlib
js.usempl(False) # default, use grace on your computer with xmgrace in external window.

If you work over http on a server (usual no display of Xwindows applications) use the same to switch to matplotlib.

17.7. Testing

You can test basic functionality of jscatter after installation:

import jscatter as js
js.test.doTest()
#basic graphics and fitting
js.examples.runExample('example_SinusoidalFitting.py')
The Example shows :
  • 3 sine fit plots with one sine
  • a fit plot with 5 sine curves fitted simultaneous
  • a simple plot with 5 points ( phase against Amplitude of the 5 sines)

During development:

python setup.py test

17.8. Troubleshooting and tips

If xmgrace is not found by jscatter the path to the executable may be not on your PATH variable. Check this by calling xmgrace in a shell. Change your PATH in your .bashrc by adding:

export PATH=/path/to/xmgrace:$(PATH) )
To open .agr files by klicking add a new file association e.g. to KDE.

In SystemSettings/FileAssociations add a new type xmgrace. Inside this add FilenamePatterns ‘*.agr’ and similar.

In ‘ApplicationPreferenceOrder’ add xmgrace and edit this new application :
In General : edit name to “xmgrace” (keep it). In Application : edit name to “xmgracefree” and command to “xmgrace -free”. This will open files in free floating size format.

In ‘ApplicationPreferenceOrder’ add again application xmgrace (no changes) The second opens files in fixed size format (no ‘-free’).