
--------------


REQUIRED PACKAGES


The following packages should be installed:

NumPy http://sourceforge.net/projects/numpy/files/NumPy
scipy http://sourceforge.net/projects/scipy/files/
scikit-image (http://scikit-image.org/download.html)
shapely http://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely
pp (http://www.parallelpython.com/downloads/pp/pp-1.6.4.zip)
pandas (to generate the parallel coordinate plots for the logs)
colormath (http://python-colormath.readthedocs.org/en/latest/installation.html)


PyOpenGL - required until Dec 2015
vtk python - required until Dec 2015

vtk python is a full python environment (Python 2.7.*) that you download and install on your Mac/Windows/Linux machine:
	http://www.vtk.org/download/
	==> Standalone Python Interface (Installer)


--------------

INSTALLING THE NECESSARY PYTHON PACKAGES & RUNNING THE SCRIPTS (ON MAC OS)



1. Install homebrew (http://brew.sh) by typing the following in terminal 

	ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
	
   NB: do NOT use sudo!!!
   
   

2. In terminal type in 

	brew doctor
	
    to know whether there is something wrong with homebrew and whether it was install successfully.
    Do NOT ignore any of warnings or errors given by brew doctor. For instance, brew doctor 
    might complain that some applications (e.g., xcode) are outdated; if some, go to the App Store 
    and update all applications. Do NOT proceed to any of the following steps until the udpates 
    are completed.
    
    If there are not issues with homebrew, brew doctor will return such a message: 
    ‘Your system is ready to brew.’
    
    
    
3. Make sure that homebrew installs ALL of the packages in /usr/local/bin (or similar) and NOT in 
	/Library/Python/2.7/site-packages (or similar). Check this by typing the following in terminal:
	
	echo $PATH
	
	This should return something like /usr/local/bin



4. Install the python in homebrew by typing the following in terminal

	brew install python

	This will install pip too.
	
	The system python provided with the mac is not as flexible (for installing additional packages etc), 
	thus the reason why we need to install this python environment despite that a python environment 
	is available when we type python in terminal.

	
PyOpenGL IS NOT NEEDED AS FROM JAN 2016
[5. Install PyOpenGL by typing the following in terminal

	pip install PyOpenGL
]


6. Install scikit-image, scipy, shapely, pp by typing the following in terminal

	pip install scikit-image
	pip install scipy
	pip install shapely
	pip install http://www.parallelpython.com/downloads/pp/pp-1.6.4.zip


7. Install pandas to generate the parallel coordinates plots to analyse the log data from the optimization 

	pip install pandas
	

VTK IS NOT NEEDED AS FROM JAN 2016
[8. Install vtk python by typing the following in terminal

	brew install homebrew/science/vtk --with-python
	
	If installed successfully, the final message outputted should be something like 
	
	==> Summary
	🍺  /usr/local/Cellar/vtk/6.3.0: 3067 files, 126M 
]
	
	

9. You can now run the scripts. In terminal type in 

	cd path_to_scripts_dir 
	
	(e.g., cd /Users/luana/Documents/OptimizingScatterplots/scripts) 
	
	Then 
	
	python main_batch.py
	
	
	
	


N.B.: When installing new packages, always try to use homebrew first using 

		 brew install name_of_package
	
       If the package is not available in homebrew, use pip:
    	
    	 pip install name_of_package
       	   
       NEVER use sudo (no matter if brew or pip, as it could easily mess up file permissions etc)
       
       To update a package use the following 
       
         pip install name_of_package --upgrade
       
       e.g., pip install numpy --upgrade
       (for instance, the option skiprows in numpy.genfromtxt() has recently been replaced with skip_header)



--------------


DESCRIPTION OF THE SCRIPT FILES 


The main scripts are: 
- scatterplotimage_sp.py: with all of Gregorio’s scatterplot image generation code and over/underplotting index computations, that is run as a subprocess to avoid getting a memory leak when running test batches; all results saved to a file
- scatterplotimage.py: starts a subprocess to run scatterplotimage_sp.py and retrieves the results of the subprocess from a file 
- clustering.py: with the k-means clustering functions to identify the clusters in the data points
- model_sp.py: with Luana's measures on the actual and perceived (i.e., edge detected) data points, that is run as a subprocess to avoid getting a memory leak when running test batches; all results saved to a file
- model.py: starts a subprocess to run model_sp.py and retrieves the results of the subprocess from a file 
- main_batch.py: the script that combines all of the above and which should be invoked to start the system; in this case, the system can run the optimization of a batch of scatterplots (and not just one)
- utilities.py: contains a number of general utilities like writing to or reading from a file
- randomdatapoints.py: was used by Luana to generate the different types of scatterplot data points that are available as csv files in the ‘../data’ directory (corresponding scatterplot images with x and y axis visible are available in the '../other/suboutputegs/0_imageplotEgsForData' dir).


--------------

