Update README.md

DynamicsAndNeuralSystems · Aug 25, 2020 · 8aa64d5 · 8aa64d5
1 parent e937855
commit 8aa64d5
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 27 deletions.
diff --git a/Matlab/M_wrapper.c b/Matlab/M_wrapper.c
@@ -9,7 +9,7 @@ void M_wrapper_double( int nlhs, mxArray *plhs[],
 
 { 
     double *inMatrix;       /* 1xN input matrix */
-    int ncols;
+    int nrows;
     double *outMatrix; /* output matrix */
 
     // check inputs
@@ -26,14 +26,14 @@ void M_wrapper_double( int nlhs, mxArray *plhs[],
         mexErrMsgIdAndTxt("catchaMouse16:notDouble",
             "Input vector must be type double.");
     }
-    if(mxGetM(prhs[0]) != 1) {
-        mexErrMsgIdAndTxt("catchaMouse16:notRowVector",
-                          "Input must be a row vector.");
+    if(mxGetN(prhs[0]) != 1) {
+        mexErrMsgIdAndTxt("catchaMouse16:notColumnVector",
+                          "Input must be a column vector.");
     }
 
     // get input
     inMatrix = mxGetPr(prhs[0]);
-    ncols = mxGetN(prhs[0]);
+    nrows = mxGetM(prhs[0]);
 
     // set output
     plhs[0] = mxCreateDoubleMatrix(1,1,mxREAL);
@@ -42,15 +42,15 @@ void M_wrapper_double( int nlhs, mxArray *plhs[],
     // calculate result
     if (normalize){
 
-        double * y_zscored = malloc(ncols * sizeof * y_zscored);
-        zscore_norm2(inMatrix, ncols, y_zscored);
+        double * y_zscored = malloc(nrows * sizeof * y_zscored);
+        zscore_norm2(inMatrix, nrows, y_zscored);
 
-        outMatrix[0] = f(y_zscored, ncols);
+        outMatrix[0] = f(y_zscored, nrows);
 
         free(y_zscored);
     } 
     else {
-        outMatrix[0] = f(inMatrix, ncols);
+        outMatrix[0] = f(inMatrix, nrows);
     }   
 
     return;
@@ -63,7 +63,7 @@ void M_wrapper_int( int nlhs, mxArray *plhs[],
 
 { 
     double *inMatrix;       /* 1xN input matrix */
-    int ncols;
+    int nrows;
     int *outMatrix; /* output matrix */
 
     // check inputs
@@ -80,14 +80,14 @@ void M_wrapper_int( int nlhs, mxArray *plhs[],
         mexErrMsgIdAndTxt("catchaMouse16:notDouble",
             "Input vector must be type double.");
     }
-    if(mxGetM(prhs[0]) != 1) {
-        mexErrMsgIdAndTxt("catchaMouse16:notRowVector",
-                          "Input must be a row vector.");
+    if(mxGetN(prhs[0]) != 1) {
+        mexErrMsgIdAndTxt("catchaMouse16:notColumnVector",
+                          "Input must be a column vector.");
     }
 
     // get input
     inMatrix = mxGetPr(prhs[0]);
-    ncols = mxGetN(prhs[0]);
+    nrows = mxGetM(prhs[0]);
 
     // set output
     plhs[0] = mxCreateNumericMatrix(1,1, mxINT32_CLASS, mxREAL);
@@ -96,15 +96,15 @@ void M_wrapper_int( int nlhs, mxArray *plhs[],
     // calculate result
     if (normalize){
 
-        double * y_zscored = malloc(ncols * sizeof * y_zscored);
-        zscore_norm2(inMatrix, ncols, y_zscored);
+        double * y_zscored = malloc(nrows * sizeof * y_zscored);
+        zscore_norm2(inMatrix, nrows, y_zscored);
 
-        outMatrix[0] = f(y_zscored, ncols);
+        outMatrix[0] = f(y_zscored, nrows);
 
         free(y_zscored);
     } 
     else {
-        outMatrix[0] = f(inMatrix, ncols);
+        outMatrix[0] = f(inMatrix, nrows);
     }   
 
     return;

diff --git a/README.md b/README.md
@@ -7,36 +7,112 @@ For information on the full set of over 7000 features, see the following (open)
 * B.D. Fulcher and N.S. Jones. [_hctsa_: A computational framework for automated time-series phenotyping using massive feature extraction](http://www.cell.com/cell-systems/fulltext/S2405-4712\(17\)30438-6). *Cell Systems* **5**, 527 (2017).
 * B.D. Fulcher, M.A. Little, N.S. Jones [Highly comparative time-series analysis: the empirical structure of time series and their methods](http://rsif.royalsocietypublishing.org/content/10/83/20130048.full). *J. Roy. Soc. Interface* **10**, 83 (2013).
 
-# Raw C
 
-## Installation of additional libraries
+
+# Installation of additional libraries
 
 Install GSL library using brew (for Mac Users):
 ```
 $ brew install gsl
 ```
 If there is a permission denied error, try this and install again:
 ```
-sudo chown -R $(whoami) $(brew --prefix)/*
+$ sudo chown -R $(whoami) $(brew --prefix)/*
 ```
 Check if it is installed correctly with command
 ```
-gsl-config --cflags --libs-without-cblas
+$ gsl-config --cflags --libs-without-cblas
 ```
 It should print the following
 ```
 -I/usr/local/Cellar/gsl/2.6/include
 -L/usr/local/Cellar/gsl/2.6/lib -lgsl
 ```
 
-## Compilation
+# Using the *catchaMouse16*-features from C, Matlab and Python
+
+The features are efficiently implemented in C and it can also be used in Matlab and Python. Currently it has been tested only on OS X.
+
+## Raw C
+
+### Compilation
+
+To compile, simply run the makefile inside the 'C' folder using
+```
+$ make
+```
+
+### Usage
+Then run the executable file (make sure you have provided the correct csv or text file name containing the time series data)
+```
+$ ./run_feat <infile> <outfile>
+```
+
+The outfile is optional. If not provided then it will print in stdout.
+
+
+## Matlab
+
+### Compilation
+Go to the ‘Matlab' directory and run _mexAll_ command in Matlab application
+```
+mexAll
+```
+This will create a bunch of Matlab executable files with name *catchaMouse16_<feature_name>*.
+
+### Usage
+Now you can test it by run the *catchaMouse16_all* script 
+```
+ts_data = randn(100,1) % column vector
+catchaMouse16_all(ts_data)
+```
+This will return a feature vector.
+
+Or you can also call the features individually, for example “AC_nl_035” :
+```
+catchaMouse16_AC_nl_035(ts_data)
+```
+
+## Python
+
+The wrapper needs to be build with linked C library before being importable into some python code. Installation procedure for Python 2 and Python 3 are given below.
+
+### Install in Python 2
+Copy the following command and run it inside the 'Python' directory
+```
+$ python setup.py build
+$ python setup.py install
+```
+To test this module execute the test python script:
+```
+$ python test_features.py
+```
+### Install in Python 3
+Copy the following command and run it inside the 'Python' directory
+```
+$ python3 setup_P3.py build
+$ python3 setup_P3.py install
+```
+To test this module execute the test python script:
+```
+$ python3 test_features.py
+```
+
+### Usage
+Now you can import *catchaMouse16* in your code and call the individual features
 
-To compile, run the makefile inside C folder
 ```
-make
+import catchaMouse16
+ts_data = np.rand(100,1)
+catchaMouse16.SC_FluctAnal_2_dfa_50_2_logi_r2_se2(ts_data)
 ```
 
-Then run the executable file (make sure you have provided the csv or text file name containing the time series data)
+Or get the feature vector using
 ```
-./run_feat
+from catchaMouse16 import catchaMouse16_all
+features = catchaMouse16_all(ts_data)
 ```
+
+# Contribution
+
+Please feel free to ask any query in the Issue section. Any suggestions or improvements are welcomed through Pull Requests.