Merge pull request #16 from gitter-lab/matlab-docker

Test running SCINGE inside MATLAB Docker container

.gitignore

@@ -8,3 +8,9 @@ Output/
 
 # Temporary m files
 *.m~
+
+# MATLAB compiler output files
+SCINGE_Example
+mccExcludedFiles.log
+requiredMCRProducts.txt
+

.travis.yml

@@ -2,3 +2,9 @@ sudo: required
 
 services:
   - docker
+
+before_install:
+  - docker pull amarburg/matlab-runtime
+
+script:
+  - docker run -v $(pwd):/SCINGE -w /SCINGE --entrypoint "/bin/bash" amarburg/matlab-runtime -c "source install_run_SCINGE.sh; ls Output/ -l; source ~/.bashrc; conda activate scinge-test; conda list; tests/compare_example_output.sh"

README.md

@@ -48,6 +48,9 @@ The results can be reproduced by providing the same inputs and date from a previ
 `SCINGE_Example.m` demonstrates a simple example with two hyperparameter sets and two replicates.
 It runs SCINGE on `data1/X_SCODE_data` and writes the results to the `Output` directory.
 
+## Testing
+The `tests` directory contains test scripts and reference output files to test SCINGE.
+
 ## Licenses
 SCINGE is available under the MIT License, Copyright © 2019 Atul Deshpande, Anthony Gitter.
 

SCINGE_Example.m

@@ -2,7 +2,9 @@
 clear all;
 close all;
 clc;
-addpath(genpath('.'));
+if ~isdeployed
+    addpath(genpath('.'));
+end
 
 %% Generate list of parameter combinations
 param_list{1}.ID = 541;
@@ -33,4 +35,4 @@
 gene_list = tf;
 
 %% Run SCINGE
-[ranked_edges, gene_influence] = SCINGE(gene_list,Data,outdir,num_replicates,param_list);
+[ranked_edges, gene_influence] = SCINGE(gene_list,Data,outdir,num_replicates,param_list);

code/GLG_Instance.m

@@ -86,9 +86,9 @@ function GLG_Instance(Data,varargin)
     save(fullfile(params.outdir,[filename]), 'Adj_Matrix','varargin','params');
 end
 fprintf('Intermediate file saved.\n')
-if isdeployed
-    quit;
-end
+%if isdeployed
+%    quit;
+%end
 end
 
 function y = isfilecomp(x)
@@ -105,4 +105,4 @@ function GLG_Instance(Data,varargin)
         y = 0;
     end
 end
-end
+end

install_run_SCINGE.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Install the compiled SCINGE_Example executable from a temporary location
+wget --quiet https://www.biostat.wisc.edu/~gitter/tmp/369b3eb57db4fb1fce29c5ae28db3ee7/SCINGE_Example
+chmod u+x SCINGE_Example
+
+apt-get update
+apt-get -y install libxt6 bzip2
+
+# Install Miniconda3 following https://hub.docker.com/r/continuumio/miniconda3/dockerfile
+export PATH="/opt/conda/bin:$PATH"
+wget --quiet https://repo.anaconda.com/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O ~/miniconda.sh
+/bin/bash ~/miniconda.sh -b -p /opt/conda
+rm ~/miniconda.sh
+/opt/conda/bin/conda clean -tipsy
+ln -s /opt/conda/etc/profile.d/conda.sh /etc/profile.d/conda.sh
+echo ". /opt/conda/etc/profile.d/conda.sh" >> ~/.bashrc
+echo "conda activate base" >> ~/.bashrc
+
+# Install conda test environment
+conda env create -f tests/environment.yml
+
+# Run the MATLAB-generated wrapper script
+./run_SCINGE_Example.sh /usr/local/MATLAB/MATLAB_Runtime/v94

readme.txt

@@ -0,0 +1,102 @@
+SCINGE_Example Executable
+
+1. Prerequisites for Deployment 
+
+Verify that version 9.4 (R2018a) of the MATLAB Runtime is installed.   
+If not, you can run the MATLAB Runtime installer.
+To find its location, enter
+
+    >>mcrinstaller
+
+at the MATLAB prompt.
+
+Alternatively, download and install the Linux version of the MATLAB Runtime for R2018a 
+from the following link on the MathWorks website:
+
+    http://www.mathworks.com/products/compiler/mcr/index.html
+
+For more information about the MATLAB Runtime and the MATLAB Runtime installer, see 
+Package and Distribute in the MATLAB Compiler documentation  
+in the MathWorks Documentation Center.
+
+2. Files to Deploy and Package
+
+Files to Package for Standalone 
+================================
+-SCINGE_Example 
+-run_SCINGE_Example.sh (shell script for temporarily setting environment variables and 
+                        executing the application)
+   -to run the shell script, type
+
+       ./run_SCINGE_Example.sh <mcr_directory> <argument_list>
+
+    at Linux or Mac command prompt. <mcr_directory> is the directory 
+    where version 9.4 of the MATLAB Runtime is installed or the directory where 
+    MATLAB is installed on the machine. <argument_list> is all the 
+    arguments you want to pass to your application. For example, 
+
+    If you have version 9.4 of the MATLAB Runtime installed in 
+    /mathworks/home/application/v94, run the shell script as:
+
+       ./run_SCINGE_Example.sh /mathworks/home/application/v94
+
+    If you have MATLAB installed in /mathworks/devel/application/matlab, 
+    run the shell script as:
+
+       ./run_SCINGE_Example.sh /mathworks/devel/application/matlab
+-MCRInstaller.zip
+    Note: if end users are unable to download the MATLAB Runtime using the
+    instructions in the previous section, include it when building your 
+    component by clicking the "Runtime included in package" link in the
+    Deployment Tool.
+-This readme file 
+
+
+
+3. Definitions
+
+For information on deployment terminology, go to
+http://www.mathworks.com/help and select MATLAB Compiler >
+Getting Started > About Application Deployment >
+Deployment Product Terms in the MathWorks Documentation
+Center.
+
+4. Appendix 
+
+A. Linux systems:
+In the following directions, replace MR/v94 by the directory on the target machine where 
+   MATLAB is installed, or MR by the directory where the MATLAB Runtime is installed.
+
+(1) Set the environment variable XAPPLRESDIR to this value:
+
+MR/v94/X11/app-defaults
+
+
+(2) If the environment variable LD_LIBRARY_PATH is undefined, set it to the following:
+
+MR/v94/runtime/glnxa64:MR/v94/bin/glnxa64:MR/v94/sys/os/glnxa64:MR/v94/sys/opengl/lib/glnxa64
+
+If it is defined, set it to the following:
+
+${LD_LIBRARY_PATH}:MR/v94/runtime/glnxa64:MR/v94/bin/glnxa64:MR/v94/sys/os/glnxa64:MR/v94/sys/opengl/lib/glnxa64
+
+    For more detailed information about setting the MATLAB Runtime paths, see Package and 
+   Distribute in the MATLAB Compiler documentation in the MathWorks Documentation Center.
+
+
+
+        NOTE: To make these changes persistent after logout on Linux 
+              or Mac machines, modify the .cshrc file to include this  
+              setenv command.
+        NOTE: The environment variable syntax utilizes forward 
+              slashes (/), delimited by colons (:).  
+        NOTE: When deploying standalone applications, you can
+              run the shell script file run_SCINGE_Example.sh 
+              instead of setting environment variables. See 
+              section 2 "Files to Deploy and Package".    
+
+
+
+
+
+

run_SCINGE_Example.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# script for execution of deployed applications
+#
+# Sets up the MATLAB Runtime environment for the current $ARCH and executes 
+# the specified command.
+#
+exe_name=$0
+exe_dir=`dirname "$0"`
+echo "------------------------------------------"
+if [ "x$1" = "x" ]; then
+  echo Usage:
+  echo    $0 \<deployedMCRroot\> args
+else
+  echo Setting up environment variables
+  MCRROOT="$1"
+  echo ---
+  LD_LIBRARY_PATH=.:${MCRROOT}/runtime/glnxa64 ;
+  LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${MCRROOT}/bin/glnxa64 ;
+  LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${MCRROOT}/sys/os/glnxa64;
+  LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${MCRROOT}/sys/opengl/lib/glnxa64;
+  export LD_LIBRARY_PATH;
+  echo LD_LIBRARY_PATH is ${LD_LIBRARY_PATH};
+  shift 1
+  args=
+  while [ $# -gt 0 ]; do
+      token=$1
+      args="${args} \"${token}\"" 
+      shift
+  done
+  eval "\"${exe_dir}/SCINGE_Example\"" $args
+fi
+exit
+

tests/README.md

@@ -0,0 +1,24 @@
+# SCINGE tests
+
+This directory contains scripts and reference files used to test SCINGE.
+It uses Python to compare the output files SCINGE generates to reference files that represent the expected output.
+
+- `reference`: A directory containing the expected outputs from `SCINGE_Example.m`
+- `environment.yml`: A conda environment with the Python packages required for the test scripts
+- `compare_example_output.sh`: A script to compare the generated and reference output files
+- `compare_adj_matrices.py`: A Python script to compare the sparse adjacency matrices in two `.mat` files
+
+#### `compare_adj_matrices.py` usage
+
+```
+usage: compare_adj_matrices.py [-h] mat_file mat_file
+
+Compare the Adj_Matrix sparse matrices in two .mat files. Return with exit
+code 1 if they are not equal.
+
+positional arguments:
+  mat_file    The .mat files to compare. Exactly two required.
+
+optional arguments:
+  -h, --help  show this help message and exit
+```

tests/compare_adj_matrices.py

@@ -0,0 +1,46 @@
+import argparse
+import numpy as np
+import scipy.io as io
+import sys
+
+
+def main(args):
+    '''
+    Compare two sparse matrices stored in .mat files.
+    Each .mat file is expected to have the sparse matrix stored in Adj_Matrix.
+    Uses numpy.allclose to compare the data values using the default tolerance.
+    Return with exit code 1 if the spare matrices are not equal.
+    '''
+    mat_contents1 = io.loadmat(args.mat_file[0])
+    matrix1 = mat_contents1['Adj_Matrix']
+
+    mat_contents2 = io.loadmat(args.mat_file[1])
+    matrix2 = mat_contents2['Adj_Matrix']
+
+    # Inspired by PyPardisoProject
+    # https://github.com/haasad/PyPardisoProject/blob/f666ea4718b32fa1359e5ca94bedac710b09a428/pypardiso/pardiso_wrapper.py#L173
+    if not (np.array_equal(matrix1.indptr, matrix2.indptr) and 
+            np.array_equal(matrix1.indices, matrix2.indices)):
+        print('Spare matrices in {} and {} have different nonzero elements'.format(args.mat_file[0],
+              args.mat_file[1]))
+        sys.exit(1)
+
+    if not np.allclose(matrix1.data, matrix2.data):
+        print('Spare matrices in {} and {} have different values'.format(args.mat_file[0],
+              args.mat_file[1]))
+        max_diff = max(np.abs(matrix1.data - matrix2.data))
+        print('Maximum absolute difference: {}'.format(max_diff))
+        sys.exit(1)
+
+    print('Spare matrices in {} and {} are equal'.format(args.mat_file[0],
+          args.mat_file[1]))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='Compare the Adj_Matrix '
+        'sparse matrices in two .mat files. '
+        'Return with exit code 1 if they are not equal.')
+    parser.add_argument('mat_file', type=str, nargs=2,
+                        help='The .mat files to compare. Exactly two required.')
+
+    main(parser.parse_args())

tests/compare_example_output.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Compare the SCINGE_Example.m output with the reference output
+# This script must be called from the directory that contains SCINGE_Example.m
+# Must have already run SCINGE_Example.m using the default output directory
+# Must run inside the conda environment specified by environment.yml or have
+# those Python packages available
+
+outdir=Output
+refdir=tests/reference
+
+# Return 0 unless any individual test fails
+# Continue running all tests even if one fails
+exit_status=0
+
+echo Comparing SCINGE_Gene_Influence.txt
+csvdiff --style=summary --sep='	' --significance=5 --output=csvdiff.out Gene_Name $outdir/SCINGE_Gene_Influence.txt $refdir/SCINGE_Gene_Influence.txt
+cat csvdiff.out
+comparison=$(cat csvdiff.out)
+rm csvdiff.out
+if [[ "$comparison" != 'files are identical' ]] ; then
+  exit_status=1
+fi
+
+# csvdiff requires a unique key in each row
+# Provide the Regulator and Target columns together as the index
+echo Comparing SCINGE_Ranked_Edge_List.txt
+csvdiff --style=summary --sep='	' --significance=5 --output=csvdiff.out Regulator,Target $outdir/SCINGE_Ranked_Edge_List.txt $refdir/SCINGE_Ranked_Edge_List.txt
+cat csvdiff.out
+comparison=$(cat csvdiff.out)
+rm csvdiff.out
+if [[ "$comparison" != 'files are identical' ]] ; then
+  exit_status=1
+fi
+
+echo Comparing sparse adjacency matrices
+for id in 541 542
+do
+  for rep in 1 2
+  do
+    filename=AdjMatrix_data1_X_SCODE_datapmat_ID_${id}_replicate_${rep}.mat
+    python tests/compare_adj_matrices.py $outdir/$filename $refdir/$filename
+    return_code=$?
+    if [[ $return_code -ne 0 ]] ; then
+      exit_status=1
+    fi
+  done
+done
+
+exit $exit_status

tests/environment.yml

@@ -0,0 +1,7 @@
+name: scinge-test
+dependencies:
+  - numpy=1.16.3
+  - pip=19.1
+  - scipy=1.2.1
+  - pip:
+    - csvdiff==0.3.3