From ad98f0d5e63ab5f439bdecfe4450d5450a31fc17 Mon Sep 17 00:00:00 2001 From: Ben Fulcher Date: Wed, 21 Oct 2026 18:35:26 +1100 Subject: [PATCH 1/5] Drop the Python 2 build Python 2 has been end-of-life since 2020, and Ben decided to drop it (#19). Python/setup.py was its only build script and the only user of Python/catchaMouse16_wrap.c, so both go; setup_P3.py remains the build script. Co-Authored-By: Claude Opus 5.5 --- Python/catchaMouse16_wrap.c | 309 ------------------------------------ Python/setup.py | 28 ---- 2 files changed, 337 deletions(-) delete mode 100644 Python/catchaMouse16_wrap.c delete mode 100644 Python/setup.py diff --git a/Python/catchaMouse16_wrap.c b/Python/catchaMouse16_wrap.c deleted file mode 100644 index bb47a94..0000000 --- a/Python/catchaMouse16_wrap.c +++ /dev/null @@ -1,309 +0,0 @@ -#include - -// include functions -#include "../C/src/CO_AutoCorr.h" -#include "../C/src/CO_AddNoise.h" -#include "../C/src/CO_HistogramAMI.h" -#include "../C/src/CO_NonlinearAutocorr.h" -#include "../C/src/CO_TranslateShape.h" -#include "../C/src/IN_AutoMutualInfoStats.h" -#include "../C/src/DN_RemovePoints.h" -#include "../C/src/FC_LoopLocalSimple.h" -#include "../C/src/PH_Walker.h" -#include "../C/src/ST_LocalExtrema.h" -#include "../C/src/SY_DriftingMean.h" -#include "../C/src/SY_SlidingWindow.h" -#include "../C/src/SC_FluctAnal.h" -#include "../C/src/fft.h" -#include "../C/src/helper_functions.h" -#include "../C/src/histcounts.h" -#include "../C/src/stats.h" - - -// --------------------------------------------------------------------- -// -------------------- Main wrapper function -------------------------- -// --------------------------------------------------------------------- - -// used for all functions to wrap via a function handle - -static PyObject * python_wrapper_double(PyObject * args, double (*f) (const double*, const int), int normalize) -{ - - PyObject * py_tuple; - int n; - double * c_array; - - // parse arguments - if(!PyArg_ParseTuple(args, "O", &py_tuple)){ - return NULL; - } - - if (PyList_Check(py_tuple)){ - - n = (int) PyList_Size(py_tuple); - - // allocate space for input array (C data format) - c_array= malloc(n*sizeof(double)); - - // write input array to c array - int i; - for (i=0; i Date: Wed, 21 Oct 2026 18:35:45 +1100 Subject: [PATCH 2/5] Accept NumPy arrays and any sequence of numbers in the Python wrapper The single-feature functions raised SystemError for NumPy arrays and for non-numeric items (#15): the C wrapper accepted only lists and tuples, returned NULL without setting an exception for anything else, and ignored PyFloat_AsDouble errors, so a bad item became -1 with a pending exception. The wrapper now reads float64 buffers (e.g., NumPy arrays) directly and converts any other one-dimensional sequence or iterable element by element, raising TypeError for strings, multi-dimensional arrays and non-numeric items. An empty series gives NaN instead of z-scoring zero values. It uses PyMem_Malloc with error checks and drops a redundant copy of the input and the unused int-valued wrapper. catchaMouse16_all passed list(data) to each feature, which for a NumPy array is a list of NumPy scalars; it now passes sequences through, and reads only one-shot iterators (generators) into a list. setup_P3.py imports setuptools instead of distutils (removed from the standard library in Python 3.12), and adds GSL's include and library folders from gsl-config when it is available, so Homebrew and conda installs build without setting CFLAGS or LDFLAGS. Co-Authored-By: Claude Opus 5.5 --- Python/catchaMouse16/catchaMouse16.py | 9 +- Python/catchaMouse16_wrap_P3.c | 256 +++++++++++++------------- Python/setup_P3.py | 36 +++- 3 files changed, 161 insertions(+), 140 deletions(-) diff --git a/Python/catchaMouse16/catchaMouse16.py b/Python/catchaMouse16/catchaMouse16.py index 3f08264..5eab49e 100644 --- a/Python/catchaMouse16/catchaMouse16.py +++ b/Python/catchaMouse16/catchaMouse16.py @@ -21,7 +21,14 @@ def catchaMouse16_all(data): 'CO_TranslateShape_circle_35_pts_std' ] - data = list(data) + # The feature functions accept any sequence of numbers (list, tuple, + # NumPy array, ...). Read a one-shot iterator (e.g., a generator) into a + # list, since each of the 16 features reads the data. + try: + if iter(data) is data: + data = list(data) + except TypeError: + pass # not iterable: the feature functions raise a TypeError featureOut = [] for f in features: diff --git a/Python/catchaMouse16_wrap_P3.c b/Python/catchaMouse16_wrap_P3.c index da8ce6a..1a2ccaf 100644 --- a/Python/catchaMouse16_wrap_P3.c +++ b/Python/catchaMouse16_wrap_P3.c @@ -1,4 +1,8 @@ +#define PY_SSIZE_T_CLEAN #include +#include +#include +#include // include functions #include "../C/src/CO_AutoCorr.h" @@ -21,165 +25,153 @@ // --------------------------------------------------------------------- -// -------------------- Main wrapper function -------------------------- +// ------------------------- Input conversion -------------------------- // --------------------------------------------------------------------- -// used for all functions to wrap via a function handle - -static PyObject * python_wrapper_double(PyObject * args, double (*f) (const double*, const int), int normalize) +// Is this buffer format a native double? +static int is_double_format(const char *format) { + return format != NULL && (strcmp(format, "d") == 0 || strcmp(format, "@d") == 0 || + strcmp(format, "=d") == 0); +} - PyObject * py_tuple; - int n; - double * c_array; - - // parse arguments - if(!PyArg_ParseTuple(args, "O", &py_tuple)){ - return NULL; +// Copy a one-dimensional sequence of real numbers (a list, tuple, NumPy +// array, array.array, or any other iterable) into a new C array of doubles. +// Returns 0 on success. On failure, returns -1 with a Python exception set +// (TypeError for input that is not a one-dimensional sequence of numbers). +static int to_double_array(PyObject *obj, double **out, int *n_out) +{ + double *y = NULL; + Py_ssize_t n; + + // strings and bytes are sequences, but not of numbers + if (PyUnicode_Check(obj) || PyBytes_Check(obj) || PyByteArray_Check(obj)) { + PyErr_Format(PyExc_TypeError, "expected a sequence of numbers, not %.200s", + Py_TYPE(obj)->tp_name); + return -1; } - if (PyList_Check(py_tuple)){ - - n = (int) PyList_Size(py_tuple); - - // allocate space for input array (C data format) - c_array= malloc(n*sizeof(double)); - - // write input array to c array - int i; - for (i=0; i INT_MAX) { + PyBuffer_Release(&view); + PyErr_SetString(PyExc_OverflowError, "time series is too long"); + return -1; + } + y = PyMem_Malloc((n > 0 ? n : 1) * sizeof *y); + if (y == NULL) { + PyBuffer_Release(&view); + PyErr_NoMemory(); + return -1; + } + for (Py_ssize_t i = 0; i < n; i++) + memcpy(&y[i], (const char *)view.buf + i * view.strides[0], sizeof(double)); + PyBuffer_Release(&view); + *out = y; + *n_out = (int)n; + return 0; + } + // other element types (e.g., integer or float32 arrays) are + // converted element by element below + PyBuffer_Release(&view); + } else { + PyErr_Clear(); } - } - else - { - if (PyTuple_Check(py_tuple)){ - - n = (int) PyTuple_Size(py_tuple); - // allocate space for input array (C data format) - c_array= malloc(n*sizeof(double)); - - // write input array to c array - int i; - for (i=0; i INT_MAX) { + Py_DECREF(seq); + PyErr_SetString(PyExc_OverflowError, "time series is too long"); + return -1; + } + y = PyMem_Malloc((n > 0 ? n : 1) * sizeof *y); + if (y == NULL) { + Py_DECREF(seq); + PyErr_NoMemory(); + return -1; + } + PyObject **items = PySequence_Fast_ITEMS(seq); + for (Py_ssize_t i = 0; i < n; i++) { + y[i] = PyFloat_AsDouble(items[i]); + if (y[i] == -1.0 && PyErr_Occurred()) { + if (PyErr_ExceptionMatches(PyExc_TypeError)) { + PyErr_Format(PyExc_TypeError, + "expected a sequence of numbers, but element %zd is %.200s", + i, Py_TYPE(items[i])->tp_name); } - - } - else{ - return NULL; + PyMem_Free(y); + Py_DECREF(seq); + return -1; } } + Py_DECREF(seq); + *out = y; + *n_out = (int)n; + return 0; +} - // result variables - double result; - PyObject * ret; - - // copy input vector (just in case it is altered by the function) - double * copy = malloc(n * sizeof * copy); - memcpy(copy, c_array, n * sizeof * copy); - - if (normalize){ - - double * y_zscored = malloc(n * sizeof * y_zscored); - zscore_norm2(copy, n, y_zscored); - - result = f(y_zscored, n); - - free(y_zscored); - } - else { - result = f(copy, n); - } - - free(c_array); - free(copy); - // build the resulting string into a Python object. - ret = Py_BuildValue("d", result); +// --------------------------------------------------------------------- +// -------------------- Main wrapper function -------------------------- +// --------------------------------------------------------------------- - return ret; -}; +// used for all functions to wrap via a function handle -static PyObject * python_wrapper_int(PyObject * args, int (*f) (const double*, const int), int normalize) +static PyObject * python_wrapper_double(PyObject * args, double (*f) (const double*, const int), int normalize) { - - PyObject * py_tuple; + PyObject * input; + double * y; int n; - double * c_array; + double result; // parse arguments - if(!PyArg_ParseTuple(args, "O", &py_tuple)){ - return NULL; + if (!PyArg_ParseTuple(args, "O", &input)) + return NULL; + if (to_double_array(input, &y, &n) != 0) + return NULL; + + // an empty series has no features + if (n == 0) { + PyMem_Free(y); + return PyFloat_FromDouble(NAN); } - if (PyList_Check(py_tuple)){ - - n = (int) PyList_Size(py_tuple); - - // allocate space for input array (C data format) - c_array= malloc(n*sizeof(double)); - - // write input array to c array - int i; - for (i=0; i Date: Wed, 21 Oct 2026 18:35:45 +1100 Subject: [PATCH 3/5] Accept row or column vectors in MATLAB and find GSL in mexAll catchaMouse16_all transposed its input, so it failed on a column vector ("Input must be a column vector."), while the single-feature MEX functions failed on a row vector (#15). The MEX wrapper now accepts any vector (the data are contiguous either way) and returns NaN for an empty input, and catchaMouse16_all passes data(:) after checking the input is a real vector. mexAll hard-coded -I/usr/local/include and -L/usr/local/lib, which fails for Apple-silicon Homebrew (/opt/homebrew) and conda installs. It is now a function that takes an optional GSL install prefix and otherwise uses gsl-config (also looked for in CONDA_PREFIX and the Homebrew bin folders, since MATLAB's PATH often lacks them), then /opt/homebrew, /usr/local and /usr. It adds an rpath for GSL's library folder so conda's @rpath libraries load, works from any folder, writes the MEX files next to itself, and no longer compiles the command-line program's main.c into every MEX file. Co-Authored-By: Claude Opus 5.5 --- Matlab/M_wrapper.c | 30 ++++++--- Matlab/catchaMouse16_all.m | 16 ++++- Matlab/mexAll.m | 125 ++++++++++++++++++++++++++++++------- 3 files changed, 139 insertions(+), 32 deletions(-) diff --git a/Matlab/M_wrapper.c b/Matlab/M_wrapper.c index 9f6a96d..16d365f 100644 --- a/Matlab/M_wrapper.c +++ b/Matlab/M_wrapper.c @@ -8,7 +8,7 @@ void M_wrapper_double( int nlhs, mxArray *plhs[], double (*f) (const double*, const int), int normalize ) { - double *inMatrix; /* 1xN input matrix */ + double *inMatrix; /* input vector (1xN or Nx1) */ int nrows; double *outMatrix; /* output matrix */ @@ -26,19 +26,27 @@ void M_wrapper_double( int nlhs, mxArray *plhs[], mexErrMsgIdAndTxt("catchaMouse16:notDouble", "Input vector must be type double."); } - if(mxGetN(prhs[0]) != 1) { - mexErrMsgIdAndTxt("catchaMouse16:notColumnVector", - "Input must be a column vector."); + // accept a row or a column vector (the data are contiguous either way) + if(!mxIsEmpty(prhs[0]) && (mxGetNumberOfDimensions(prhs[0]) != 2 || + (mxGetM(prhs[0]) != 1 && mxGetN(prhs[0]) != 1))) { + mexErrMsgIdAndTxt("catchaMouse16:notVector", + "Input must be a vector."); } // get input inMatrix = mxGetPr(prhs[0]); - nrows = mxGetM(prhs[0]); + nrows = (int) mxGetNumberOfElements(prhs[0]); // set output plhs[0] = mxCreateDoubleMatrix(1,1,mxREAL); outMatrix = mxGetPr(plhs[0]); + // an empty series has no features + if (nrows == 0) { + outMatrix[0] = mxGetNaN(); + return; + } + // calculate result if (normalize){ @@ -62,7 +70,7 @@ void M_wrapper_int( int nlhs, mxArray *plhs[], int (*f) (const double*, const int), int normalize ) { - double *inMatrix; /* 1xN input matrix */ + double *inMatrix; /* input vector (1xN or Nx1) */ int nrows; int *outMatrix; /* output matrix */ @@ -80,14 +88,16 @@ void M_wrapper_int( int nlhs, mxArray *plhs[], mexErrMsgIdAndTxt("catchaMouse16:notDouble", "Input vector must be type double."); } - if(mxGetN(prhs[0]) != 1) { - mexErrMsgIdAndTxt("catchaMouse16:notColumnVector", - "Input must be a column vector."); + // accept a row or a column vector (the data are contiguous either way) + if(!mxIsEmpty(prhs[0]) && (mxGetNumberOfDimensions(prhs[0]) != 2 || + (mxGetM(prhs[0]) != 1 && mxGetN(prhs[0]) != 1))) { + mexErrMsgIdAndTxt("catchaMouse16:notVector", + "Input must be a vector."); } // get input inMatrix = mxGetPr(prhs[0]); - nrows = mxGetM(prhs[0]); + nrows = (int) mxGetNumberOfElements(prhs[0]); // set output plhs[0] = mxCreateNumericMatrix(1,1, mxINT32_CLASS, mxREAL); diff --git a/Matlab/catchaMouse16_all.m b/Matlab/catchaMouse16_all.m index 0b92583..c71a588 100644 --- a/Matlab/catchaMouse16_all.m +++ b/Matlab/catchaMouse16_all.m @@ -1,4 +1,18 @@ function [featureValues, featureNames] = catchaMouse16_all(data) +% catchaMouse16_all Compute all 16 catchaMouse16 features of a time series. +% +% [featureValues, featureNames] = catchaMouse16_all(data) +% +% data is a row or column vector. Each feature z-scores the series first. +% Run mexAll first to compile the feature functions. + +if ~(isnumeric(data) || islogical(data)) || ~isreal(data) + error('catchaMouse16:notReal', 'Input must be a real numeric vector.'); +end +if ~isvector(data) && ~isempty(data) + error('catchaMouse16:notVector', 'Input must be a vector (row or column).'); +end +data = double(data(:)); % the feature functions take a double column vector featureNames = ... { ... @@ -27,7 +41,7 @@ fh = str2func(['catchaMouse16_', featureName]); - featureValues(featureInd) = fh(data'); + featureValues(featureInd) = fh(data); end diff --git a/Matlab/mexAll.m b/Matlab/mexAll.m index 94eaa8c..5d5a865 100644 --- a/Matlab/mexAll.m +++ b/Matlab/mexAll.m @@ -1,33 +1,116 @@ -% path where C implementation lives -basePath = '../C/src'; -ipath = {['-I', basePath], ['-I','/usr/local/include'], '-I.'}; +function mexAll(gslPrefix) +% mexAll Compile the catchaMouse16 MEX functions (needs GSL). +% +% mexAll finds GSL with gsl-config, or else in /opt/homebrew, +% /usr/local or /usr +% mexAll(prefix) uses the GSL installed under prefix (prefix/include and +% prefix/lib), e.g., mexAll('/opt/homebrew') or +% mexAll(getenv('CONDA_PREFIX')) +% +% The MEX files are written to the folder that contains this file. -% list all C files to include in the mex-call -CFiles = dir(basePath); -CFiles = CFiles(cellfun(@(x) contains(x, '.c'), {CFiles.name})); -CFileNames = {CFiles.name}; +% folder of this file, and where the C implementation lives +matlabDir = fileparts(mfilename('fullpath')); +basePath = fullfile(matlabDir, '..', 'C', 'src'); + +if nargin < 1 + gslPrefix = ''; +end +[gslIncludeDirs, gslLibDirs] = findGSL(gslPrefix); +fprintf('Using GSL headers in %s\n', strjoin(gslIncludeDirs, ', ')); + +ipath = [{['-I', basePath], ['-I', matlabDir]}, strcat('-I', gslIncludeDirs)]; +lpath = strcat('-L', gslLibDirs); +% find GSL's shared libraries at run time too (e.g., conda's @rpath libraries) +if isunix && ~isempty(gslLibDirs) + lpath{end+1} = ['LDFLAGS=$LDFLAGS', sprintf(' -Wl,-rpath,%s', gslLibDirs{:})]; +end + +% list all C files to include in the mex-call (not the command-line program) +CFiles = dir(fullfile(basePath, '*.c')); +CFileNames = setdiff({CFiles.name}, {'main.c'}); % add path to the c file names includeFiles = cellfun(@(x) fullfile(basePath, x), CFileNames, 'UniformOutput', false); % get function names -fid = fopen('../featureList.txt','r'); -i = 1; -tline = fgetl(fid); -featureNames{i} = tline; -while ischar(tline) - i = i+1; - tline = fgetl(fid); - featureNames{i} = tline; -end -fclose(fid); +featureNames = strsplit(strtrim(fileread(fullfile(matlabDir, '..', 'featureList.txt')))); % mex all feature functions separately -for i = 1:length(featureNames)-1 - +for i = 1:length(featureNames) + featureName = featureNames{i}; - + fprintf('Compiling %s...\n', featureName); - mex(ipath{:}, ['catchaMouse16_', featureName,'.c'], 'M_wrapper.c', includeFiles{:}, ['-L','/usr/local/lib'], '-lgsl', '-lgslcblas', '-lm')%, '-v', 'OPTIMFLAGS=-O2') + mex(ipath{:}, fullfile(matlabDir, ['catchaMouse16_', featureName, '.c']), ... + fullfile(matlabDir, 'M_wrapper.c'), includeFiles{:}, lpath{:}, ... + '-lgsl', '-lgslcblas', '-lm', '-outdir', matlabDir) fprintf('\n'); end + +end + +%------------------------------------------------------------------------------- +function [includeDirs, libDirs] = findGSL(gslPrefix) +% Find GSL's include and library directories. + +hasHeaders = @(includeDir) exist(fullfile(includeDir, 'gsl', 'gsl_vector.h'), 'file') == 2; + +% 1. a prefix given by the user +if ~isempty(gslPrefix) + includeDirs = {fullfile(gslPrefix, 'include')}; + libDirs = {fullfile(gslPrefix, 'lib')}; + if ~hasHeaders(includeDirs{1}) + error('catchaMouse16:noGSL', 'GSL headers not found in %s', includeDirs{1}); + end + return +end + +% 2. gsl-config (MATLAB's PATH may not include Homebrew or conda, so also +% look in their usual bin folders) +gslConfigs = {'gsl-config', '/opt/homebrew/bin/gsl-config', '/usr/local/bin/gsl-config'}; +condaPrefix = getenv('CONDA_PREFIX'); +if ~isempty(condaPrefix) + gslConfigs = [{fullfile(condaPrefix, 'bin', 'gsl-config')}, gslConfigs]; +end +for k = 1:length(gslConfigs) + [status, cflags] = system([gslConfigs{k}, ' --cflags']); + if status ~= 0 + continue + end + [status, libs] = system([gslConfigs{k}, ' --libs']); + if status ~= 0 + continue + end + includeDirs = flagValues(cflags, '-I'); + libDirs = flagValues(libs, '-L'); + if any(cellfun(hasHeaders, includeDirs)) + return + end +end + +% 3. the usual install locations +prefixes = {'/opt/homebrew', '/usr/local', '/usr'}; +for k = 1:length(prefixes) + if hasHeaders(fullfile(prefixes{k}, 'include')) + includeDirs = {fullfile(prefixes{k}, 'include')}; + if strcmp(prefixes{k}, '/usr') + libDirs = {}; % the linker searches the system folders already + else + libDirs = {fullfile(prefixes{k}, 'lib')}; + end + return + end +end + +error('catchaMouse16:noGSL', ['GSL not found. Install GSL (e.g., brew install gsl, ', ... + 'or apt install libgsl-dev) or call mexAll(prefix) with its install prefix.']); +end + +%------------------------------------------------------------------------------- +function values = flagValues(flags, flag) +% Values of the compiler flags that start with flag, e.g., '-I' or '-L'. +tokens = strsplit(strtrim(flags)); +tokens = tokens(startsWith(tokens, flag)); +values = cellfun(@(t) t(length(flag)+1:end), tokens, 'UniformOutput', false); +end From 4ec6b4baf501070b0a20e950e673817dd245f0ab Mon Sep 17 00:00:00 2001 From: Ben Fulcher Date: Wed, 21 Oct 2026 18:35:45 +1100 Subject: [PATCH 4/5] Add CI and value tests for the Python and MATLAB wrappers Nothing ran the C value checks from #3 automatically, the Python test only printed values (picking features via dir()[:16]), and MATLAB had no test (#14). The GitHub Actions workflow runs make test in C/ with gcc and clang on Ubuntu and clang on macOS (the FFT bug fixed in #2 was GCC-only), with GSL from apt or Homebrew. It passes only CC to make, so it doesn't depend on the Makefile's warning flags. It also builds and installs the Python extension with setup_P3.py, as the README says, and runs the Python tests on Ubuntu (Python 3.9 and 3.13) and macOS. Python/test_features.py now asserts the hctsa v1.03 reference values from C/tests/test_features.c (test_ts.csv and the C test series), with the same tolerance, and checks the input handling: NumPy arrays, lists, tuples and generators give identical values, bad input raises TypeError, and N = 8 and empty series give NaN rather than a crash. It runs with pytest or as a script. Matlab/test_catchaMouse16.m checks the same reference values for row and column vectors, catchaMouse16_all, short and empty series, and bad input. It needs a MATLAB licence, so it is not in CI. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 80 +++++++++++++ Matlab/test_catchaMouse16.m | 114 +++++++++++++++++++ Python/test_features.py | 221 ++++++++++++++++++++++++++++++++---- 3 files changed, 392 insertions(+), 23 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 Matlab/test_catchaMouse16.m diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b3360c7 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,80 @@ +name: CI + +on: + push: + branches: [master] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + c: + name: C (${{ matrix.os }}, ${{ matrix.cc }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-latest + cc: gcc + - os: ubuntu-latest + cc: clang + - os: macos-latest + cc: clang + steps: + - uses: actions/checkout@v5 + - name: Install GSL (Ubuntu) + if: runner.os == 'Linux' + run: sudo apt-get update && sudo apt-get install -y libgsl-dev + - name: Install GSL (macOS) + if: runner.os == 'macOS' + run: | + brew install gsl + # Homebrew's prefix is not on Apple clang's default search paths + echo "CPATH=$(brew --prefix gsl)/include" >> "$GITHUB_ENV" + echo "LIBRARY_PATH=$(brew --prefix gsl)/lib" >> "$GITHUB_ENV" + - name: Compiler version + run: ${{ matrix.cc }} --version + - name: Build + working-directory: C + run: make CC=${{ matrix.cc }} + - name: Test (values against hctsa v1.03) + working-directory: C + run: make test CC=${{ matrix.cc }} + + python: + name: Python ${{ matrix.python-version }} (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-latest + python-version: "3.9" + - os: ubuntu-latest + python-version: "3.13" + - os: macos-latest + python-version: "3.13" + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-python@v6 + with: + python-version: ${{ matrix.python-version }} + - name: Install GSL (Ubuntu) + if: runner.os == 'Linux' + run: sudo apt-get update && sudo apt-get install -y libgsl-dev + - name: Install GSL (macOS) + if: runner.os == 'macOS' + run: brew install gsl + - name: Install build and test dependencies + run: python -m pip install setuptools numpy pytest + - name: Build and install the extension + working-directory: Python + run: | + python setup_P3.py build + python setup_P3.py install + - name: Test (values against hctsa v1.03, input handling) + working-directory: Python + run: python -m pytest -v test_features.py diff --git a/Matlab/test_catchaMouse16.m b/Matlab/test_catchaMouse16.m new file mode 100644 index 0000000..40dbd00 --- /dev/null +++ b/Matlab/test_catchaMouse16.m @@ -0,0 +1,114 @@ +% test_catchaMouse16 Check the catchaMouse16 MEX functions. +% +% Run mexAll first, then run this script (from any folder). It errors on +% the first failed check. +% +% Feature values are checked against the hctsa v1.03 reference values used in +% C/tests/test_features.c (computed in MATLAB R2026a on the z-scored series). +% CO_AddNoise (different random number generator to MATLAB) and the +% SC_FluctAnal standard error (GSL's robust fit vs MATLAB's robustfit) cannot +% match hctsa closely, so only their NaN behavior is checked. + +testDir = fileparts(mfilename('fullpath')); +addpath(testDir); +repoDir = fullfile(testDir, '..'); +dataDir = fullfile(repoDir, 'C', 'tests', 'data'); +numChecks = 0; + +% Same tolerance as the C tests: relative 1e-9 (absolute 1e-12 near 0) +isClose = @(value, expected) (isnan(expected) && isnan(value)) || ... + (~isnan(value) && abs(value - expected) <= 1e-9 * max(abs(expected), 1e-3)); + +% hctsa v1.03 values for test_ts.csv (N = 900) +reference = { + 'AC_nl_035', 0.029388510653943489 + 'AC_nl_036', -0.089862158681074611 + 'AC_nl_112', 0.95527350930096855 + 'CO_HistogramAMI_even_2_3', 0.0064026521213012694 + 'CO_HistogramAMI_even_10_3', 0.069437467855260393 + 'IN_AutoMutualInfoStats_diff_20_gaussian_ami8', 0.0017376086763743674 + 'DN_RemovePoints_absclose_05_ac2rat', 0.36055461984180104 + 'CO_TranslateShape_circle_35_pts_std', 0.81476734130849149 + 'CO_TranslateShape_circle_35_pts_statav4_m', 0.063948212366642623 + 'SY_DriftingMean50_min', -0.17515608004321692 + 'PH_Walker_biasprop_05_01_sw_meanabsdiff', 0.79368904259375106 + 'PH_Walker_momentum_5_w_momentumzcross', 0.15016685205784205 + 'FC_LoopLocalSimple_mean_stderr_chn', 0.090009471873276056 + 'ST_LocalExtrema_n100_diffmaxabsmin', 0.78721699565949121 +}; + +x = readmatrix(fullfile(repoDir, 'test_ts.csv')); +assert(iscolumn(x) && length(x) == 900, 'test_ts.csv should be 900 values'); + +% --- single features: reference values, for column and row vectors --- +for i = 1:size(reference, 1) + name = reference{i, 1}; + fh = str2func(['catchaMouse16_', name]); + valueColumn = fh(x); + valueRow = fh(x'); + assert(isClose(valueColumn, reference{i, 2}), ... + 'test_ts %s: got %.17g, expected %.17g', name, valueColumn, reference{i, 2}); + assert(isequal(valueRow, valueColumn), 'test_ts %s: row and column vectors differ', name); + numChecks = numChecks + 2; +end + +% --- catchaMouse16_all: row and column vectors give the same values --- +[valuesColumn, names] = catchaMouse16_all(x); +valuesRow = catchaMouse16_all(x'); +assert(isequal(size(valuesColumn), [16, 1]) && length(names) == 16, 'expected 16 features'); +assert(isequaln(valuesRow, valuesColumn), 'catchaMouse16_all: row and column vectors differ'); +featureList = strsplit(strtrim(fileread(fullfile(repoDir, 'featureList.txt')))); +assert(isequal(sort(names(:)), sort(featureList(:))), 'feature names differ from featureList.txt'); +for i = 1:size(reference, 1) + value = valuesColumn(strcmp(names, reference{i, 1})); + assert(isClose(value, reference{i, 2}), 'catchaMouse16_all %s: got %.17g, expected %.17g', ... + reference{i, 1}, value, reference{i, 2}); +end +% cannot match hctsa closely, but should be a number at N = 900 +assert(all(isfinite(valuesColumn)), 'catchaMouse16_all: expected 16 finite values at N = 900'); +numChecks = numChecks + 4; + +% --- other hctsa v1.03 reference values from C/tests/test_features.c --- +otherReference = { + 'wn299.txt', 'ST_LocalExtrema_n100_diffmaxabsmin', 0.91471424058108486 + 'rw437.txt', 'ST_LocalExtrema_n100_diffmaxabsmin', 0.97902825419057138 + 'int1000.txt', 'DN_RemovePoints_absclose_05_ac2rat', 0.21171499248284334 + 'wn150.txt', 'SC_FluctAnal_2_dfa_50_2_logi_r2_se2', NaN +}; +for i = 1:size(otherReference, 1) + y = readmatrix(fullfile(dataDir, otherReference{i, 1}), 'FileType', 'text'); + fh = str2func(['catchaMouse16_', otherReference{i, 2}]); + value = fh(y); + assert(isClose(value, otherReference{i, 3}), '%s %s: got %.17g, expected %.17g', ... + otherReference{i, 1}, otherReference{i, 2}, value, otherReference{i, 3}); + numChecks = numChecks + 1; +end + +% --- short series: NaN rather than a crash --- +values8 = catchaMouse16_all(x(1:8)); +assert(isequal(size(values8), [16, 1]), 'N = 8: expected 16 values'); +assert(isnan(catchaMouse16_FC_LoopLocalSimple_mean_stderr_chn(x(1:8))), 'N = 8: expected NaN'); +assert(all(isnan(catchaMouse16_all([]))), 'empty input: expected NaN'); +numChecks = numChecks + 3; + +% --- bad input raises an error --- +badInputs = {zeros(900, 2), 'abc', complex(x, 1)}; +for i = 1:length(badInputs) + threw = false; + try + catchaMouse16_all(badInputs{i}); + catch + threw = true; + end + assert(threw, 'catchaMouse16_all: bad input %d did not raise an error', i); + threw = false; + try + catchaMouse16_AC_nl_035(badInputs{i}); + catch + threw = true; + end + assert(threw, 'catchaMouse16_AC_nl_035: bad input %d did not raise an error', i); + numChecks = numChecks + 2; +end + +fprintf('All %d catchaMouse16 MATLAB checks passed.\n', numChecks); diff --git a/Python/test_features.py b/Python/test_features.py index e6ed459..a7b6ac6 100644 --- a/Python/test_features.py +++ b/Python/test_features.py @@ -1,27 +1,202 @@ +"""Tests for the catchaMouse16 Python wrapper. +Feature values are checked against the hctsa v1.03 reference values used in +C/tests/test_features.c (computed in MATLAB R2026a on the z-scored series). +CO_AddNoise (different random number generator to MATLAB) and the +SC_FluctAnal standard error (GSL's robust fit vs MATLAB's robustfit) cannot +match hctsa closely, so only their NaN behavior is checked. + +Run with `python test_features.py` or `python -m pytest test_features.py` +(inside Python/, after building the extension). +""" + +import math import os -import pandas as pd + +import numpy as np + import catchaMouse16 -#------------------------------------------------------------------------------- -def giveMeFeatureVector(tsData): - ''' - Returns a catchaMouse-16 feature vector from input time-series data - ''' - features = dir(catchaMouse16) - features = [item for item in features if not '__' in item] - features = features[:16] - featureVector = [] - for testFun in features: - featureFun = getattr(catchaMouse16,testFun) - featureVector.append(featureFun(tsData)) - - return featureVector - -#------------------------------------------------------------------------------- - -x = pd.read_csv('../test_ts.csv',header=None); -tsData = x[0].values.tolist() -fV = giveMeFeatureVector(tsData) -print(fV) -print("Test Successful!") +HERE = os.path.dirname(os.path.abspath(__file__)) +REPO = os.path.dirname(HERE) +TEST_TS = os.path.join(REPO, "test_ts.csv") +C_TEST_DATA = os.path.join(REPO, "C", "tests", "data") + +FEATURE_NAMES = [ + "SY_DriftingMean50_min", + "DN_RemovePoints_absclose_05_ac2rat", + "AC_nl_036", + "AC_nl_112", + "ST_LocalExtrema_n100_diffmaxabsmin", + "IN_AutoMutualInfoStats_diff_20_gaussian_ami8", + "CO_HistogramAMI_even_2_3", + "CO_TranslateShape_circle_35_pts_statav4_m", + "CO_AddNoise_1_even_10_ami_at_10", + "PH_Walker_momentum_5_w_momentumzcross", + "SC_FluctAnal_2_dfa_50_2_logi_r2_se2", + "PH_Walker_biasprop_05_01_sw_meanabsdiff", + "CO_HistogramAMI_even_10_3", + "AC_nl_035", + "FC_LoopLocalSimple_mean_stderr_chn", + "CO_TranslateShape_circle_35_pts_std", +] + +# hctsa v1.03 values for test_ts.csv (N = 900), as in C/tests/test_features.c +TEST_TS_REFERENCE = { + "AC_nl_035": 0.029388510653943489, + "AC_nl_036": -0.089862158681074611, + "AC_nl_112": 0.95527350930096855, + "CO_HistogramAMI_even_2_3": 0.0064026521213012694, + "CO_HistogramAMI_even_10_3": 0.069437467855260393, + "IN_AutoMutualInfoStats_diff_20_gaussian_ami8": 0.0017376086763743674, + "DN_RemovePoints_absclose_05_ac2rat": 0.36055461984180104, + "CO_TranslateShape_circle_35_pts_std": 0.81476734130849149, + "CO_TranslateShape_circle_35_pts_statav4_m": 0.063948212366642623, + "SY_DriftingMean50_min": -0.17515608004321692, + "PH_Walker_biasprop_05_01_sw_meanabsdiff": 0.79368904259375106, + "PH_Walker_momentum_5_w_momentumzcross": 0.15016685205784205, + "FC_LoopLocalSimple_mean_stderr_chn": 0.090009471873276056, + "ST_LocalExtrema_n100_diffmaxabsmin": 0.78721699565949121, +} + +# Other hctsa v1.03 reference values from C/tests/test_features.c: +# (data file in C/tests/data, feature, expected value; NaN means NaN expected) +OTHER_REFERENCE = [ + ("wn299.txt", "ST_LocalExtrema_n100_diffmaxabsmin", 0.91471424058108486), + ("rw437.txt", "ST_LocalExtrema_n100_diffmaxabsmin", 0.97902825419057138), + ("int1000.txt", "DN_RemovePoints_absclose_05_ac2rat", 0.21171499248284334), + ("wn150.txt", "SC_FluctAnal_2_dfa_50_2_logi_r2_se2", math.nan), +] + + +def load_test_ts(): + return np.loadtxt(TEST_TS) + + +def assert_close(value, expected, label): + """Same tolerance as the C tests: relative 1e-9 (absolute 1e-12 near 0).""" + assert isinstance(value, float), "%s: expected a float, got %r" % (label, value) + if math.isnan(expected): + assert math.isnan(value), "%s: got %r, expected NaN" % (label, value) + else: + tol = 1e-9 * max(abs(expected), 1e-3) + assert not math.isnan(value) and abs(value - expected) <= tol, ( + "%s: got %.17g, expected %.17g" % (label, value, expected)) + + +def assert_raises_type_error(fun, arg, label): + try: + fun(arg) + except TypeError: + return + except Exception as err: + raise AssertionError("%s: raised %s (%s), expected TypeError" + % (label, type(err).__name__, err)) + raise AssertionError("%s: no error, expected TypeError" % label) + + +def same_values(a, b): + """Elementwise equal, treating NaN as equal to NaN.""" + return len(a) == len(b) and all( + (math.isnan(x) and math.isnan(y)) or x == y for x, y in zip(a, b)) + + +def test_feature_names(): + out = catchaMouse16.catchaMouse16_all(load_test_ts()) + assert out["names"] == FEATURE_NAMES + with open(os.path.join(REPO, "featureList.txt")) as f: + assert sorted(f.read().split()) == sorted(FEATURE_NAMES) + for name in FEATURE_NAMES: + assert callable(getattr(catchaMouse16, name)), name + + +def test_reference_values_test_ts(): + x = load_test_ts() + assert len(x) == 900 + for name, expected in TEST_TS_REFERENCE.items(): + assert_close(getattr(catchaMouse16, name)(x.tolist()), expected, "test_ts " + name) + # cannot match hctsa closely, but should be a number at N = 900 + for name in ["CO_AddNoise_1_even_10_ami_at_10", "SC_FluctAnal_2_dfa_50_2_logi_r2_se2"]: + value = getattr(catchaMouse16, name)(x) + assert isinstance(value, float) and math.isfinite(value), (name, value) + + +def test_reference_values_other_series(): + for filename, name, expected in OTHER_REFERENCE: + x = np.loadtxt(os.path.join(C_TEST_DATA, filename)) + assert_close(getattr(catchaMouse16, name)(x), expected, filename + " " + name) + + +def test_catchaMouse16_all_matches_single_features(): + x = load_test_ts() + out = catchaMouse16.catchaMouse16_all(x) + single = [getattr(catchaMouse16, name)(x) for name in FEATURE_NAMES] + assert same_values(out["values"], single) + for name, value in zip(out["names"], out["values"]): + if name in TEST_TS_REFERENCE: + assert_close(value, TEST_TS_REFERENCE[name], "catchaMouse16_all " + name) + + +def test_input_types_give_identical_values(): + x = load_test_ts() + reference = [getattr(catchaMouse16, name)(x.tolist()) for name in FEATURE_NAMES] + inputs = { + "NumPy array": x, + "tuple": tuple(x.tolist()), + "list of NumPy floats": list(x), + "non-contiguous NumPy array": np.repeat(x, 2)[::2], + "generator": (v for v in x.tolist()), + } + for label, data in inputs.items(): + if label != "generator": + values = [getattr(catchaMouse16, name)(data) for name in FEATURE_NAMES] + assert same_values(values, reference), label + out = catchaMouse16.catchaMouse16_all(data) + assert same_values(out["values"], reference), "catchaMouse16_all " + label + + # integer input is converted to floating point + xi = np.arange(1, 901) % 7 + assert catchaMouse16.AC_nl_035(xi) == catchaMouse16.AC_nl_035([float(v) for v in xi]) + + +def test_bad_input_raises_type_error(): + bad_inputs = { + "string": "1 2 3", + "None": None, + "scalar": 5.0, + "list with a string": [1.0, 2.0, "3"], + "list with None": [1.0, None, 3.0], + "nested list": [[1.0, 2.0], [3.0, 4.0]], + "2-D NumPy array": np.zeros((900, 1)), + "NumPy string array": np.array(["a", "b", "c"]), + } + for label, data in bad_inputs.items(): + assert_raises_type_error(catchaMouse16.AC_nl_035, data, "AC_nl_035 " + label) + assert_raises_type_error(catchaMouse16.catchaMouse16_all, data, + "catchaMouse16_all " + label) + + +def test_short_series_give_nan_not_a_crash(): + # N = 8: FC_LoopLocalSimple used to crash (training length > N) + x8 = load_test_ts()[:8] + out = catchaMouse16.catchaMouse16_all(x8) + assert len(out["values"]) == 16 + assert all(isinstance(v, float) for v in out["values"]) + assert math.isnan(catchaMouse16.FC_LoopLocalSimple_mean_stderr_chn(x8)) + # features that need more than 8 samples return NaN + for name in ["SY_DriftingMean50_min", "ST_LocalExtrema_n100_diffmaxabsmin", + "SC_FluctAnal_2_dfa_50_2_logi_r2_se2"]: + assert math.isnan(getattr(catchaMouse16, name)(x8)), name + # an empty series gives NaN for every feature + for data in ([], np.array([])): + out = catchaMouse16.catchaMouse16_all(data) + assert len(out["values"]) == 16 and all(math.isnan(v) for v in out["values"]) + + +if __name__ == "__main__": + tests = [(name, fun) for name, fun in sorted(globals().items()) + if name.startswith("test_") and callable(fun)] + for name, fun in tests: + fun() + print("passed:", name) + print("All %d tests passed." % len(tests)) From 96009c4cd6a2d4bf81271e7cc2b4eb3fcd0cada9 Mon Sep 17 00:00:00 2001 From: Ben Fulcher Date: Wed, 21 Oct 2026 18:35:45 +1100 Subject: [PATCH 5/5] Update the README for the new wrapper input handling The Python features now take NumPy arrays, the MATLAB functions take row or column vectors, mexAll finds GSL itself, the Python 2 build is gone, and the Python build needs setuptools rather than distutils. Remove the workarounds the README described for the old behavior and mention the test scripts. Co-Authored-By: Claude Opus 5.5 --- README.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 57fd346..a84bb7a 100644 --- a/README.md +++ b/README.md @@ -24,39 +24,38 @@ Then build for your language of choice. |---|---|---| | C | [`C/`](C) | run `make` inside `C/` | | Python | [`Python/`](Python) | `python3 setup_P3.py build` then `python3 setup_P3.py install` | -| MATLAB | [`Matlab/`](Matlab) | run `mexAll` inside `Matlab/` (it looks for GSL in `/usr/local`; edit the paths in `mexAll.m` if GSL is installed elsewhere, e.g., `/opt/homebrew` on Apple silicon) | +| MATLAB | [`Matlab/`](Matlab) | run `mexAll` inside `Matlab/` (it finds GSL with `gsl-config` or in `/opt/homebrew`, `/usr/local` or `/usr`; for GSL elsewhere, run `mexAll('')`) | | Julia | [CatchaMouse16.jl](https://github.com/brendanjohnharris/CatchaMouse16.jl) | `] add CatchaMouse16` (pre-built binaries for all platforms) | -The Python build uses `distutils` (provided by setuptools on recent Python versions). +The Python build needs setuptools (`pip install setuptools`). Some features return `NaN` (and print an error message) for very short series; for example, `ST_LocalExtrema_n100_diffmaxabsmin` returns `NaN` for series of 100 and 150 samples. The mouse fMRI series in the paper have 900 samples. -A Python 2 build is also available through `setup.py`; see the [documentation](https://time-series-features.gitbook.io/time-series-analysis-tools/feature-subsets/catchamouse16) for details. ## Quick start -In Python (the features take a list of floats; a NumPy array must be converted with `.tolist()`): +In Python (the features take a list, tuple or NumPy array of numbers): ```python import numpy as np import catchaMouse16 -x = np.random.randn(900).tolist() # your time series +x = np.random.randn(900) # your time series print(catchaMouse16.SC_FluctAnal_2_dfa_50_2_logi_r2_se2(x)) # a single feature out = catchaMouse16.catchaMouse16_all(x) # a dict with 'names' and 'values' ``` -Run `python3 test_features.py` inside `Python/` to compute all 16 features for the example series [`test_ts.csv`](test_ts.csv). +Run `python3 test_features.py` inside `Python/` to check all 16 features against reference values for the example series [`test_ts.csv`](test_ts.csv). In MATLAB (after running `mexAll`): ```matlab -x = randn(900, 1); % a column vector -f = catchaMouse16_AC_nl_035(x); % a single feature (needs a column vector) -[featureValues, featureNames] = catchaMouse16_all(x'); % all 16 features (needs a row vector) +x = randn(900, 1); % a row or column vector +f = catchaMouse16_AC_nl_035(x); % a single feature +[featureValues, featureNames] = catchaMouse16_all(x); % all 16 features ``` Individual features are available as `catchaMouse16_{feature}`. -Note that `catchaMouse16_all` currently requires a row vector, whereas the individual feature functions require a column vector. +Run `test_catchaMouse16` to check the compiled features against reference values. From the command line (after running `make` inside `C/`), compute all features for the time series in ``: