User Manual of CAM-Java - Computational Bioinformatics and Bio
Contents
1. in Windows 7 64 bit C Program Files R R 2 15 3 bin x64 Rscript exe in Ubuntu Linux lusr bin Rscript Cancel Figure 1 Input Dialog for receiving file path of Rscript in CAM Java After successfully entering the correct file path the main frame of the software will appear as Fig 2 Then we can implement the analytic tasks by simply clicking several buttons Option Help Data Input Contrast Concentration Results Load Data File Load Image File File Path D projectipaper writing YMLR CAM Java_v04022013 Load Algorithm Settings cam cm Descriptions lK Number of organs tissues or co mpartments to be extracted maximally 10 l denoise Use multivariate clustering t o denoise I vis Draw a figure of the convexity visu alization I del_t Time interval min l drawCC Draw contrast concentration results in a figure CM Estimated Kinetic Parameters K_in min K_out min Application Status Please load the data Figure 2 The main frame of CAM software 3 2 Parameter Setting Model Selection How to decide the number of sources K is an essential problem in blind source separation In this software the users can decide the number of sources by themselves or they can use the function MDL R to calculate2. 0 17313 0 03634 9 28728 0 36291 0 19866 0 36701 0 03258 0 08979 0 00377 0 14265 0 35309 0 19168 0 02202 0 03249 0 22743 0 13850 0 09313 0 04094 0 15815 Load Data File Load Image File CM Estimated Kinetic Parameters K_in gmin K_out min Application Status Please load the data Load data successfull Now please select algorithms set parameters and then run Loading required package Runiversal Performing Factor Analysis to decompose data Loading required package MASS Done Run Factor Analysis successfull The results are also saved in the directory results Please load another data Figure 9 the deconvolution results from factor analysis 19 Reference 1 Chen L et al Tissue specific compartmental analysis for dynamic contrast enhanced MR imaging of complex tumors IEFE Trans Med Imaging 2011 30 p 2044 2058 2 Chen L et al CAM CM a signal deconvolution tool for in vivo dynamic contrast enhanced imaging of complex tissues Bioinformatics 2011 27 p 2607 2609 3 Rissanen J Modeling by shortest data description Automatica 14 465 471 1978 4 Child D 2006 The Essentials of Factor Analysis Continuum International 20 Appendix 1 Background Blind sou
3. cat Performing Factor Analysis to decompose data n FAresult lt factanal X_mask K scores regression A_est lt matrix FAresultSloadings ncol K S_est lt FAresultSscores cat Done n 16 pass results to Java environment final result lt list Aest A_est save data source Java saveData R saveData A_est S_est detach This R script implements the function of factor analysis and will be called Java GUI Then the next step is to write an XML configuration document whose purpose is to register the new algorithm factor analysis in this software It is named as FA xml The content of this document is shown as below lt xml version 1 0 encoding UTF 8 gt lt DOCTYPE configuration SYSTEM config dtd gt lt configuration gt lt algorithm name Factor Analysis script Java runFA R gt lt parameter name K type IntegerSet range 2 3 4 5 6 7 8 9 10 default 0 info Number of sources to be extracted gt lt parameter gt lt algorithm gt lt configuration gt After putting the XML document into the config folder the Factor Analysis will appear in the Algorithm Settings on the software as shown in Fig 8 b Algorithm Settings Algorithm Settings 17 b Figure 8 a Algorithm Settings before adding FA xml into config folder b Algorithm Settings after adding FA xml into config folder A simple demo can be written for
4. in the directory results Please load another data a ojx L l RCaller 2 0 Genera ted Plot Estimated Contrast Tracer Concentration Normalized TC 2 8 R b c 11 Figure 4 Results of applying CAM CM algorithm to data of a typical DCE MRI case a Tables displaying contrast tracer concentration results and CM estimated kinetic parameter b Figure showing convexity visualization c Figure showing tracer concentration results Running time may be slightly different based on different computer configuration 12 4 2 Decomposing high correlation data by CAM nICA Another example is running the CAM nICA algorithm on a high correlation dataset Similar to the procedure we detailed above we first select the data file data data correlation mix_correlation_data_2dim txt then select CAM ICA algorithm set the number of sources to 2 After about half a minute we can get results as well as a scatter plot of the final demixed signals Fig 5 S CAM Based Algorithms Suite lala Option Help Contrast Concentration Results Data Input Load DataFile Load File Column 1 Column 2 Anatase ake 0 406132538816897 0 593867461183103 0 750034224686115 0 249965775313885 File Path v04092013 dataldata_correlation mix_correlation_data_2dim bd Load Algorithm Settings CAM ICA D
5. the convenience use of future users although this step is not necessary for the plugin mechanism The demo is as following load matrix rm list ls X_ mask lt read table data data_test testdata1_uniform txt X_ mask lt as matrix X_ mask set source number K lt 5 source Java runFA R After finishing all the previous steps we use a small dataset to test whether this algorithm can work well The procedure of using this algorithm is the same as the procedure we described in previous case study The deconvolution result is shown in Fig 9 and also saved in results folder 18 Data Input rContrast Concentration Results Column 1 Column 2 0 00652 0 09547 0 04369 0 21011 0 07068 0 12509 File Path Yang CAM Java_v0409201 3idata data_testitestdata1_uniform te es 0 11154 0 43041 0 00924 0 04816 0 50309 0 24989 Load 0 16295 0 16861 0 51308 0 0 01784 0 01364 0 03153 5 gt 0 15576 0 42058 0 23077 igor sotings 0 04038 0 07031 10 18582 Factor Analysis ba 0 22088 10 02048 0 04544 10 0 01023 0 12797 0 02703 0 Descriptions 0 49260 0 12861 0 30360 0 a5 l K Number of sources to be extracted 0 10186 10 27321 0 10625 0 20154 0 01948 0 02194 0 0 14765 0 07899 0 08842 0 0 07321 0 05620 0 01349 0 0 00963 0 03160 0 11526 0 06209
6. 116058910716192 110 111838381639859 0 10270686392071 0 0988741372683852 0 116833874486536 0 109465292724888 0 111917840639847 0 105689892417972 0 382308561392028 0 356153680767767 0 362799295725021 0 331287639761181 0 103742537938037 0 118993508346958 0 322239470638929 0 0976930584435934 0 116237847622106 0 307690843559397 0 101403720891961 0 12276848729424 0 313670659820998 1 0 101425774096293 11 0 105922162397732 1 0 0898219012334749 0 105649833301922 0 122559309214442 0 14136085831904 0 120720147745399 0 144424630408432 0 311919680574215 0 395073774844712 0 296595406013456 0 34150124449399 1 0 0919296893011606 0 125230683155191 0 276199931961022 1 10 0953501417842815 0 133362086081999 0 299833464002027 0 0868237222038683 0 127796131838165 0 280405990558092 110 0968147586258717 0 144965302305146 0 347953644995838 CM Estimated Kinetic Parameters K_in min K_out min Flow 1 10 125407293267119 1 14382394235838 Flow 2 0 0661046947000298 0 375322359212187 Application Status CAM SLEP 3 4 EXPECIAUUI MaXITTNZAUOUI EM CAM Step 4 4 Convex Analysis of Mixtures CAM CM Step 1 1 Optimization Compartmenti Compartment2 K_in min 0 1254073 0 06610469 K_out min 1 1438239 0 37532236 BEST 501 warnings RET TES Run CAM CM successful The results are also saved
7. 17543775005 0 2935250352278 0 588931189766 File Path UMLRICAM Java_v04092013 dataldata_image miximage33 mat un 0 343142758317 0 0984051056497 10 558452136032 Load Algorithm Settings CAM nWCA k FI Descriptions l K Number of Sources to be extracted CM Estimated Kinetic Parameters K_in min K_out min Run Application Status Performing kmeans to cluster data Output completed Verifying that all points are below outer planes of all facets Will make 504 distance computations Estimating A and S Run CAM nWCA successful The results are also saved in the directory results Please load another data Figure 6 The dissection result from CAM nWCA By multiplying the inversion of the estimated mixing matrix with the input data matrix we can recover the three images which are very close to the original images 14 dissected source images original source images Triplet mixed images vv a b o Figure 7 Application of CAM nWCA to dissect natural image mixtures a Three original images b Three mixing images c The recovered images 15 5 Plug in Mechanism In this software we provide a plug in mechanism to ease other researcher to add their algorithms into it so that they can use this software to compare the results from different BSS algorithms To find the detailed description for how to add a plugin into this software please refer to the docum
8. User Manual of CAM Java Authors Fan Meng mengfan vt edu Niya Wang wangny vt edu Last Modified Apr 10 2013 This software is under the license BSD 3 Table of Contents LMOUCHON co sau cos ee RER ete D tentes 3 2 Software Installation and Preparation 4 Se Soitware Sacs UCL OM ESS r sodden vy Sake was acess Gg Meare ee 6 3 1 How to use the software sise 6 3 2 Parameter Setting Model Selection 7 LL ASE SUR SR ei la TT AR ner HN mt ae 10 4 1 Dissecting DCE MRI by CAM CM eee 10 4 2 Decomposing high correlation data by CAM nICA 13 4 3 Dissecting natural images by CAM nWCA ss 14 SAP Ma Mechanisii hh oy aS ess atc PR ne mt nn ape 16 Frequent Asked Question Siss nininini nien ean tecushaa cs E iSS 23 1 Introduction This software is an algorithm suite of Blind Source Separation BSS algorithms It includes three Convex Analysis of Mixtures CAM based algorithms CAM compartment modeling CAM CM CAM non negative independent component analysis CAM nICA and CAM non negative well grounded component analysis CAM nWCA algorithms which are developed by researchers in Computational Bioinformatics amp Bio imaging Laboratory CBIL http www cbil ece vt edu and are intended to address real world blind source separation BSS problems You may find detailed explanations and examples of usages of the algorithms through papers 1 2 Also it provides several classic BSS algorithm
9. ans to 3 time interval to 0 5 min Check the box Use multivariate clustering to denoise Do visualization of the convexity and Show concentration results in a figure Click Run Then after about 2 to 3 minutes the results will be shown in the table areas Figure 3 a together with two figures Fig 4 b and c displayed in separated windows In this case the number of compartments 3 is decided by Minimum Descriptive Length principle Calculated by using MDL R function MDL value obtains minimum when the number of compartments is 3 10 Load Data File Load Image File File Path ILRICAM Java_v04022013 data data_DCE_MRI typical_case rda Descriptions Number of organs tissues or c ompartments to be extracted maxim ally 10 denoise Use multivariate clusterin ig to denoise is Draw a figure of the convexity vis alization del_t Time interval min drawCC Draw contrast concentrati on results in a figure Contrast Concentration Results Flow 1 Flow2 Input Function 0 0688845125023934 0 0718484716510941 0 426418037621488 1 10 129023788119434 0 115126164586454 0 724972152756237 0 127349642660803 0 105653153269453 0 56884162005394 1 0 127103211188832 0 109444187712734 0 452204508430537 0 111093329807423 0 100121278354618 0 417002740175997 0
10. e readily used under R platform Users can also use the plug in mechanism to add those functions into the Java GUI so that they can use them directly through the GUI 22 Frequent Asked Questions 1 When I double click CAM Java jar why is there no dialog show up Answer Make sure you followed all the steps in Software installation and Preparation You need to install R and Java environment correctly beforehand If you use Ubuntu operation system you may not open it by double clicking without modification of the system properties However you can open it by typing java jar CAM Java jar in the terminal after entering the folder where the software is in the terminal 2 I loaded the data successfully Then when I clicked the run button an error information dialog is shown as below Error A rcaller exception RCallerExecutionException Can not handle R results due to rcaller exception RCallerParseException Can not parse the R output org xml sax SAXParseException systemld file C Users Niya AppData Local Temp Routput593189617387308868 lineNumber 1 columnNumber 1 Premature end of file Answer The most possible reason of this error information occurring is that you did not install Runiversal or R matlab correctly You need to install these two packages manually beforehand Another possible reason is that when you use the test dataset you did not select the right corresponding algorithm for
11. ent Software Plugin Adding Guide Basically the users only need to write two files one is the R function file and the other is XML configuration file to plug their algorithm into this software and this is easy to realize by modifying the examples for existing algorithms in this software Below we will use an example to show how to add a new R function into the software by following every step in Software Plugin Adding Guide Factor analysis describes variability among observed correlated variables in terms of a potentially lower number of unobserved variables called factors which has been used as an efficient blind source separation algorithm 4 There is an existing R package stats that includes a function called factanal performing maximum likelihood factor analysis on a covariance or data matrix which can be freely downloaded We will show how to combine the function factanal into our software In terms of the Software Plugin Adding Guide first we need to write an R script to connect the R function and Java GUI and put it into r_func folder Following the guide the content of the R script file named as Java runFA R is shown as below load the library stats for the function factanal packageExist lt require stats if IpackageExist install packages stats library stats packageExist lt require MASS if IpackageExist install packages MASS library MASS
12. escriptions S RCaller 2 0 Generated Plot EE FK Number l drawSP D mixing signal Scatter Plot of Final Demixing Signal Application Status 256 Convergence 320 Convergence 384 Convergence done null device 1 RRRRRERERER ERIE ERE RERIRER IERIE EERIE ERIE III IIR Run CAM ICA successful The results are also saved in tht Please load another data Figure 5 Dissecting results and a scatter plot of final demixing signals Finally all results will be saved automatically in the subdirectory results you can check them later 13 4 3 Dissecting natural images by CAM nWCA In this case we use CAM nWCA to dissect several mixing natural images We have three natural images Fig 7 a and each of them contains 103 103 pixels By transferring the pixel matrix into a vector and combining all three vectors into one matrix we can obtain a data matrix whose size is 3 10609 as the input of CAM nWCA algorithm Set source number K equal to 3 and run CAM nWCA we can get the estimated mixing matrix in the upper left table CAM Based Algorithms Suite Option Help Data Input Contrast Concentration Results Load Data File Load im File Column 1 Column 2 Column 3 z a 0 167991898085 0 1388569212385 10 69315118067637 0 1
13. f sources N is the number of data points L is the number of observations samples oO is the standard deviation of Gaussian noise We provide an R script called MDL R to realize the function In the later version of this software this function will be combined on the Java GUI Following is the content of this function MDL lt function X S A K cat Calculating MDL L lt dim X 1 data_size lt dim X 2 likelihood lt L data_size 2 log var as vector X A S sigma lt var as vector X A S penalty lt K L 2 log data_size K data_size 2 log L MDL lt likelihood penalty return list MDL likelihood penalty sigma The input parameters of this function are observed data matrix X estimated sources S estimated mixing matrix A and the corresponding source number Both S and A are from the calculation results of this software After obtaining the MDL values of all the candidate source numbers the one with the minimum value is the optimal model 4 Case Study 4 1 Dissecting DCE MRI by CAM CM We can apply CAM CM algorithm to a real DCE MRI dataset Here is the procedure Select Load Data file Click button In the file selection dialog first select R Matlab Data rda mat in Files of Type then select one dataset data data DCE _MRI typical_case rda Click Open Click Load Select CAM CM Set number of org
14. kages R matlab If you want to use NMF or fastICA algorithms you may also need to install the two packages first The install commands for the two packages are install packages fastICA install packages NMF repos c http web cbio uct ac za renaud CRAN getOption repos 3 Software Usage Instruction 3 1 How to use the software After accomplishing the installation and all preparation if you use Windows Mac operating system you can run the CAM Java by double clicking the CAM Java jar file Or in system shell first go to the folder containing the whole software and type the command java jar CAM Java jar If you use Ubuntu system since it treats jar file as a package you cannot open the file by double clicking without modifying the system properties please go to the folder where the software is and then type the above command in the terminal When the user runs the software for the first time a dialog will show up Fig 1 allowing the user to enter the file path of the binary executable file Rscript exe This is an important tool provided by R torun R scripts and one can easily find it in the installation folder of R Enter filepath of Rscript ax This application uses R to run the algorithm Before using the application make sure you have installed R and required packages properly Also please enter the absolute filepath of the binary file Rscript below Example location of Rscript
15. onments e User Manual doc user manual of the software e Software Plugin Adding Guide doc describes how to add a new R function into the Java GUI e Readme txt a brief introduction for how to use the software e Subdirectory data contains some sample input data with different file formats e Subdirectory r func contains R module demo files and configuration files of the software e Subdirectory results contains calculation results Each time one use the software and run a specific algorithm the results in comma separated values CSV format will be saved automatically into this subdirectory Software Environment Requirement 1 Before you run the software make sure you have properly installed Java and R on your computer The current CAM Java software is implemented by using Java SE 6 Update 31 and R 2 15 3 so make sure the versions of your Java and R are compatible with them NOTICE that if you want to use NMF algorithm you have to install R 2 15 3 or newer version since current version of NMF is created based on R 2 15 3 2 Please also install Runiversal and R matlab packages in your R environment Runiversal package is used for the communication between R and Java and R matlab package is used to read MAT files Just run the following commands in your R environment and they will automatically download and install the packages install packages Runiversal install pac
16. rce separation BSS has proven to be a powerful and widely applicable tool for the analysis and interpretation of composite patterns in engineering and science where both source patterns and mixing proportions are of interest but unknown BSS is often described by a linear latent variable model X AS where X is the observation data matrix A is the unknown mixing matrix and S is the unknown source data matrix The fundamental objective of BSS is to estimate both the unknown mixing proportions and source signals based on only the observed mixtures Convex analysis of mixtures CAM method has been recently developed and implemented via various algorithms for different real world applications CAM CM algorithm has been developed for deconvolving intra tumor vascular heterogeneity and identifying pharmacokinetics changes in many biological contexts This method works by exploiting convex analysis of mixtures that enables geometrically principled delineation of distinct vascular structures from DCE MRI data Dynamic contrast enhanced magnetic resonance imaging DCE MRI provides a noninvasive method for evaluating tumor vasculature patterns based on contrast accumulation and washout Because there are often significant numbers of partial volume pixels CAM CM instead estimates pharmacokinetics parameters flux rate constants via the time activity curves of pure volume pixels pixels whose signal is highly enriched in a particular vascular compartment Con
17. s such as Principal Component Analysis PCA Nonnegative Matrix Factorization NMP Independent Component Analysis ICA and Factor Analysis FA that have been widely used in different areas As open source software it also provides a plug in mechanism so that later researchers or users can add their algorithms into it readily by following the instructions to increase its usability in the community The software is implemented in R and Java Both of them are free software environment that researchers and developers can develop their algorithms or tools on the platforms freely The two environments can be freely downloaded from the following website links http cran r project org http www oracle com technetwork java javase downloads index html In this software R module implements core algorithms and Java module implements GUI Users can simply use GUI to run the whole software while they can also run the R module alone in R environment Please refer to the readme file in R module for more instructions 2 Software Installation and Preparation When you download the CAM Java software as a single compressed file zip file for example CAM Java_v04092013 zip first unzip it to any directory Then you can find files and sub directories as below e CAM Java jar main executable file of the software e RCaller 2 1 0 SNAPSHOT jar auxiliary Java package which establishes connection between Java and R envir
18. the data For example you should apply CAM ICA to datasets in data correlation folder CAM CM to data DCE MRI and CAM nWCA to data_image If this is not the case you may need to check the detailed information in Application status bar 3 The demo of NMF works well but when I use GUI to call NMF on the same dataset there is always error Answer One of the most possible reasons is that you did not install NMF package correctly After package update the mirror of NMF package is transferred from http cran r project org to http web cbio uct ac za renaud CRAN To avoid this problem the best way is to install NMF package manually beforehand through the command install packages NMF repos c http web cbio uct ac za renaud CRAN getOption repos Besides when error happens please check the Application Status carefully Detailed 23 information will tell you how to solve this problem Most error happenings are because of missing necessary packages or loading the wrong dataset 24
19. the optimal source number based on minimum descriptive length For the convenience of display we only set the number of sources from 2 to 10 in the algorithms we provide However users can set the source number to any integers they want by simply changing the XML file of corresponding algorithms For example if user wants to decompose the data into 50 sources by using NMF algorithm he or she just needs to simply add 50 in the parameter setting of NMF xml Before adding lt parameter name K type IntegerSet range 2 3 4 5 6 7 8 9 10 default 0 7 info Number of sources to be extracted gt After adding lt parameter name K type IntegerSet range 2 3 4 5 6 7 8 9 10 50 default 0 info Number of sources to be extracted gt Starting CAM Java jar you will find the integer 50 appears in the algorithm settings Algorithm Settings NMF _ Descriptions K Number of sources to be extracte d A k KE 4 5 6 7 8 9 n oo 4 Figure 3 After adjusting the parameter settings of NMF Another way we provide is to find the optimal model by using this software The model selection procedure is to use information theoretic to find the optimal models which best fits the observed data among several candidates Specifically a model selected with K sources by minimizing the total description length is defined as 3 MDL K lt NLlog 9 log N log L where K is number o
20. unctions called by the software are contained in the folder r_func Each of them can be used separately to implement a specific purpose affinity R performs Affinity Propagation Clustering algorithm SL_EM R performs Expectation Maximization EM algorithm measure_conv R performs minimum error margin convex optimization algorithm to identify vertices of a convex hull that best confines a set of points PCA R performs principal component analysis for dimension reduction multinorm R evaluates a multidimensional Gaussian value at a specified point with given mean vector and covariance matrix ve_cov_Jain R deals with the singularity problem and the realmin problem being used in multinorm R nnls R implements the Lawson and Hanson method for solving the least squares problems with non negativity constraints nnls_wrapper R is the wrapper function of the nnls R Whiten R is used to transform the input matrix to the form of white noise that is uncorrelated and has uniform variance nICA R is to perform nonnegative independent component analysis to separate a multivariate signal into two matrix mixing matrix and nonnegative sources Preprocess R is to perform centering for input matrix remmean R is to remove the mean of input matrix Gradient R is called by nICA R to minimize the cost function in nICA algorithm All the listed functions can b
21. vex analysis of mixtures automatically identifies pure volume pixels resided at the vertices of the clustered pixel time series scatter simplex without any knowledge of compartment distribution 2 Furthermore CAM nWCA and CAM nICA algorithm have also been developed to directly address non negative BSS problems Assume that sources contain sufficient number of well grounded points WGPs at which signals are highly expressed in one source relative to each of the remaining sources the goal is to estimate the column vectors of mixing matrix by identifying WGPs located at the corners of mixture observation scatter simplex and subsequently recover the hidden source signals Based on a geometrical latent variable model CAM learns the mixing matrix by identifying the lateral edges of convex data scatter plot The algorithm is supported theoretically by a well grounded mathematical framework Main steps of CAM algorithm are as follows 1 Projecting all the observations onto standard scatter simplex 2 Three additional core algorithms are implemented to processing the data in order to further reduce noise or outliers Including multivariate clustering based on standard finite normal mixture SFNM model affinity propagation clustering APC and the expectation maximization EM algorithm 3 Well grounded points can then be picked by identifying corner cluster centers of the scatter plot convex hull 21 2 Function Description All the R f
Download Pdf Manuals
Related Search