Code/programs for replicating `Improving Overnight Loan Identification in Payment Systems' (demonstrated on dummy data) - Last Updated Oct. 2015.

-------------------------------------------------------
Usage Notes:
-------------------------------------------------------

On a POSIX-compliant shell (e.g. Unix/Linux) copy the following commands sequentially (each script will take at least a few minutes to run):
	-Ensure that each script is executable on that the directory is on the path (e.g. chmod +x master_command_file,  set path=($path $PWD), set path=$path $PWD/bin )

Example: (starting in the Replication working directory)

set path=($path $PWD)

master_command_file

kNN_replication_master_file

other_refinements_command_file

Then run the Sweave file ReplicatingOutput.Rnw to obtain the tables/figures given in Rempel (2016) but computed on simulated dummy data

To apply to external payments data, must replace Inputs/payments.csv and Inputs/alternative_payments.csv with the relevant payments data (see format for ) and can comment out the first set of commands in master_command_file and kNN_replication_master_file

The default scripts are written in serial for ease of portability. If an intel-based Linux cluster with LSF is available, may comment out the serial calls and uncomment the bsub_* commands (e.g. in master_command_file remove Rmatlab_call and use bsub_RMPI+Matlab ..). The bsub commands however depend substantially on the system settings and permissions on the cluster.

A complete run of all three scripts and compilation of the Sweave file takes 2+ hours to run using the simulated data. For use on multiple years of actual payments data, computational feasibility requires parallel variants.

Note, a convenience wrapper implementing all three serial is provided via `full_replication_wrapper'.


--------------------------------------------------------
Contents:
--------------------------------------------------------

This folder contains the code necessary to apply the testing/overnight loan identification procedures provided in Rempel, (2016) Improving Overnight Loan Identification in Payment Systems.

This directory requires the sub-directories as titled: 
	`Inputs' - Payments data in csv / RData / .mat format
	`FurfineOutput' - Resulting output from Furfine-variant algorithm on payments data
	`BootData' - Bootstrapped payments data
	`TrainingData' - Contains the trained models from 
	`Results' - Contains the Output from the reapplication of the Furfine-variant algorithms to the bootstrapped payments data
	`KNN' - Supplemental code for the application of the Furfine algorithm and refinements
	`bin' - supporting bash/sh utility scripts 
	`PaperReplicationSubmissionScripts' - contains the actual submission scripts used to produce the paper (using code as given in Replication with Simulated Data)

Command Scripts:

	master_command_file 
		- implements the original loan identification and resampling procedure via the Basleline Furfine algorithm	

	kNN_replication_master_file 
		- implements the kNN refinement of the algorithm and testing procedure
	
	other_refinements_file 
		-generates the results for the other refinements compared in the paper.

	full_replication_wrapper
		-combines the above three scripts for a convenience wrapper

Code Overview:

 Output from Replication:
 	ReplicatingOutput.Rnw (yields ReplicatingOutput.pdf)
		-requires R-Sweave capability

 Overnight Loan Identification
	FurfineControlScript.m - implements the Furfine algorithm and all refinements discussed in Rempel (2016) 
 	 *Parameters.txt - supply the parameters that must be loaded when running the FurfineControlScript 
		e.g. kNNvariantParameters.txt gives the parameters used to run the kNN refinement


 Testing Implementation
	BootstrapModelTrainingScript.R - Training Model for kNN-variant testing
	RempelModelTraining_SlaveFunctions.R 
	BootstrapSampling.R	
	RempelBootstrapTest.R
	RempelBootstrapTest_SlaveFunction.R

 Summarizing Test Results and Generating Figures/Tables
	SummarizeTestResults_Wrapper.R
	typeIerrorfunctions_pfdrincluded.R
	OutputBaselineTestingResults.R
	OutputKNNTestingResults.R
	FurfineAndKNNanalysis.R
	FXexposure.R
	AggregateSimulatedResults.R - Generates Table 3 (given list of the Furfine Data for the 5 refinements and the associated spurious match files)   
	

 Simulating Payments Data	
	SimulatePaymentsData.R - Simulates payments data 
	SimulatePaymentsFunctions.R - support functions for simulation
	
	
		
R-Matlab interface dependencies:

 R.matlab files
	MatlabServer.m
	InputStreamByteWrapper.java
	InputStreamByteWrapper.class

 R-matlab open connection from R
	InitRmatlabFunctions.R


Important Remarks:

The parallel variants of these command scripts can be used through LSF submissions in a Linux-based cluster via  calls to `bsub' wrapper scripts (e.g. bsub_RMPI-3.0 / bsub_RMPI+Matlab). The settings within the bsub wrappers will have to be adjusted according to the specifications of the local cluster. 


-----------------------------------------------------------
Dependencies:
----------------------------------------------------------

System information (cluster):

LSB Version:    :core-4.0-amd64:core-4.0-noarch:graphics-4.0-amd64:graphics-4.0-noarch:printing-4.0-amd64:printing-4.0-noarch
Distributor ID: RedHatEnterpriseServer
Description:    Red Hat Enterprise Linux Server release 5.8 (Tikanga)
Release:        5.8
Codename:       Tikanga

Linux version 2.6.18-371.9.1.el5 (mockbuild@x86-028.build.eng.bos.redhat.com) (gcc version 4.1.2 20080704 (Red Hat 4.1.2-54)) #1 SMP Tue May 13 06:52:49 EDT 2014


System Information (Server - used for serial variants):

Distributor ID: RedHatEnterpriseServer
Description:    Red Hat Enterprise Linux Server release 6.4 (Santiago)
Release:        6.4
Codename:       Santiago


Matlab (version 8.3): (requires version 7+ for Rmatlab interaction)

 - Statistics and Machine Learning Toolbox
  	 (type `which ClassificationKNN.fit' in Matlab to confirm that the relevant script from the toolbox is available)

-  Econometrics Toolbox
	(depends on the lagmatrix.m function)

R (version R.3.0):

 Packages:
	-R.matlab
	-plyr
	-zoo
	-xtable

For parallel processing:
	-intel MPI
	-LSF
	-Linux-based operating system

-----------------------------------------------------
Common Errors / Debugging:
-----------------------------------------------------

Any errors pertaining to java will be connected to the R.matlab connection. For instance,  if you receive error in Rmatlab_call RempelBootstrapTest.R pertaining to a java exception and the message contains `Address in use' then change the port number or see documentation for R.matlab and the R.matlab utility scripts listed above. 

If attempting to use in parallel:
	-if you receive an error using RempelBootstrapTest.R indicating `error in save(MatlabServer_tmp_tmpname, '-V6')' or `Warning: ServerSocket[addr=0.0.0.0/0.0.0.0,port=0,localport=xxxx] is not serializable' then check that permissions for socket connections are set properly (see R.matlab documentation / support for more details and/or talk to system administrator). Also, recommend calling the scripts using the scratch drive as the working directory when applying on a cluster. 


If `command not found' then simply add: set path=($path $PWD), set path=($path $PWD/bin) on command line

Check log-files given in output.[script].txt for log of output if using serial versions
	- the logs concatenate with multiple jobs using the same script so recommend removing the log-file and re-running the offending script and then inspect the log-file to isolate where the error occurred.




-----------------------------------------------------
Contact Information:
-----------------------------------------------------

Questions may be directed to: Mark Rempel, a.mark.rempel@gmail.com.

Current versions / any possible updates to the scripts will be available at www.markrempel.org, however, code is largely provided as is.

