DESCRIPTION: Build a histogram (double *histx, double *histy) from an array of data data (double *data) USES: Typically used in conjunction with xf_wint1, which can produce the data values necessary for the histogram DEPENDENCY TREE: No dependencies ARGUMENTS: double *data : array of data data to generate histogram int n : size of the array double *histx : result-array, x-axis values for histogram - NOTE! must be initialised by calling function double *histy : result-array, y-values for histogram - NOTE! must be initialised by calling function int bintot : total number of bins in the histogram double min : define bottom of the data range - NOTE than min itself will also be included double max : define top of the data range - NOTE than max itself will also be included int format : the format of the histogram - 1=counts, 2=proportion (peak=1), 3=probability (sum of values=1) RETURN VALUE: A long integer, the final number of data points in the modified histy array. This may be less than the original value of n, depending on the min and max settings The main result is modification of the histx and histy arrays, which will hold the values necessary to generate a histogram plot. Note that the values in the histx array will correspond with the middle of each bin, not the start. SAMPLE CALL: int g1=1, g2=2; long ii,jj,kk,nn,result_l[32],nintervals; float winsize=0.01; double time[1001],group[1001],*intervals=NULL; // time and group data must be stored in memory first // find the intervals between events of class g1 and g2 intervals= xf_wint1(time,group,n,g1,g2,winsize,result_l); nintervals=result_l[0]; // now generate values for the histogram xf-histd1(intervals,nintervals,histx,histy,100,-.05,.05,1) // 100ms wide histogram with 100 bins
DESCRIPTION: Build a histogram (double *histx, double *histy) from an array of data (long *data) USES: Typically used in conjunction with xf_wint1_l, which can produce the data values necessary for the histogram DEPENDENCY TREE: No dependencies ARGUMENTS: long *data : input array used to generate histogram int nn : size of the array double *histx : result-array, x-axis values for histogram - NOTE! must be initialised by calling function double *histy : result-array, y-values for histogram - NOTE! must be initialised by calling function long bintot : total number of bins in the histogram long min : define bottom of the data range - NOTE than min itself will also be included long max : define top of the data range - NOTE than max itself will also be included int format : the format of the histogram - 1=counts, 2=proportion (peak=1), 3=probability (sum of values=1) RETURN VALUE: Successs: the final sum of values in the modified histy array. - This may be less than the original value of nn, depending on the min and max settings - Modified histx and histy arrays, which will hold the histogram values - NOTE: values in histx[] represent the middle of each bin, not the start SAMPLE CALL: long ii, g1=1, g2=2, winsize=1000, nintervals, bintot=100, min=-500, max=500; long time[1001],group[1001],*intervals=NULL; double histx[100],histy[100]; // time and group data must be stored in memory first .... // find the intervals between events of class g1 and g2 intervals= xf_wint1_l(time,group,n,g1,g2,winsize,&nintervals); // now generate values for the histogram xf-hist1_l(intervals,nintervals,histx,histy,bintot,min,max,3);
DESCRIPTION: Calculate burstiness in a histogram Adapted from xf_histbursty1d, John Huxter: 7 February 2011 1. histogram is downsampled to 50bins focussed on the +-50ms zone 2. this histogram is smoothed with a 10ms Gaussian kernel (central bin +-2 bins) 3. cubic spline interpolation is used to up-sample to 200 bins 4. the first positive inflection at time greater-than-zero is identified 5. the time at which this peak drops to 75% amplitude is identified - this is a measure of the rate of falloff in the histogram 6. this dropoff time is normalized to the potential time at which it could have occurred Important assumptions regarding the input histogram: - should range from -0.05 to +0.05 s (+-50ms) - must have at least 0.5 bins per ms - so a +-50ms window should have at least 50 bins - y-values in the histogram can be counts or probabilities - it shouldn't matter - but the array must be a double-float NOTE: scores based on fewer than 50 spikes in the histogram tend to be unreliable NOTE: a "bursty" cell should ideally have a peak-time less than 0.012s and a burstiness score > 0.75? USES: DEPENDENCIES: xf_bin1a_d xf_round1_d xf_smoothgauss1_d xf_spline1_d ARGUMENTS: double *histx1 : input histogram x-values (typically time in seconds) double *histy1 : input histogram y-values (typically spike-counts) long nbins1 : number of x/y pairs in the histogram double *result_d : pre-allocated array to hold results - must allow at least 3 elements char *message : pre-allocated array to hold error message RETURN VALUE: 0 on success -1 on warning (eg. no peak in the histogram) -2 error related to input histogram or parameters -3 fatal memory allocation error result array will hold statistics char array will hold message (if any) SAMPLE CALL:
DESCRIPTION: Determine the ratio of events in two symmetrical zones of a histogram Originally based on xf_histrefract1_d (February 2009 [JRH]) - however in this version zero itself contributes to the negative and positive sums (zero is special) USES: - determine refractoriness of cell-firing to asess quality of spike-sorting - neurons have a 2ms refractory period - typically we compare the proportion of spikes in a +-15ms window falling within a +-2ms zone - focusing on the inner +-15ms of the histogram ensures that bursty and non-bursty cells are treated similarly - a ratio of ɬ.08 should be used to automatically reject a histogram - a ratio of ɘ.01 represents an exceptionally clean refractory period - NOTE: bintot must be such as to allow at least 1ms precision (eg. 100 bins convering a 100ms range) - NOTE: 50-75 spikes are required in the +-15ms window to make a good decision - NOTE: for asymmetrical histograms (e.g. cross-corelograms) good estimates require 35-50 spikes in any half - autocorrelograms: - determine the quality of cell isolation - estimate of burst-firing - cross-correlograms: - monosynaptic coupling DEPENDENCY TREE: No dependencies ARGUMENTS: double *histx : input array, histogram timestamps (seconds) double *histy : input array, histogram values (typically spike-counts, but doubles allowed) long bintot : number of bins in the input histogram double z1: : the reference zone (seconds: typically 0.015) double z2: : the comparison zone (seconds: typically 0.002) - should be smaller than zone1! double *result : output array, must allow at least 5 elements RETURN VALUE: : the proportion of zone1 events occurring in zone2 : -1 if there are no events in zone2
DESCRIPTION: Calculate statistics relating to the refractoriness of an auto- or cross-corellogram of the spiking for a cell or cell-pair. That is, the tendency for the +-2ms period in the middle of the histogram to be empty while the rest of the histogram is populated. This occurs because most neurons cannot fire 2 action potentials within 2ms. Modification of original code (calc_srefractoriness) written by Andrew Macpherson of PrismTC, August 2010 Successor to xf_histrefract2_d (2017.02.15) ARGUMENTS: double histy : input, pointer to array containing histogram counts long nbins_tot : number of bins used for histogram long nbins_c : size of refractory period (bins, typically corresponding to 2ms) long nbins_s : size of zone outside refractory period for comparison double *result_d : results array (must be preallocated to hold 40 items) - diff: difference between the mean event-counts, central versus side - ratio: centre/(centre+side) - range 0-1, expected value depends on "nbins_c" & "nbins_s" - t-statistic: one-sided, based on diff, should be +ive if refractoriness exists - probability for the t-statistic char *message : errort message (if any) RETURN VALUE: - success: histogram total for the regions of interest (centre + left + right) - error: -1 SAMPLE CALL: refract = xf_histratio3_d(histy,100,2,8,result_d,message); - this assumes a 100 bin histogram, presumably covering a range of +-50ms (so 1ms per bin) - the refractory period is set as 2ms, so bins 48,49,50 &51 will constitute the refractory zone (+-2ms) - the comparison zone is the next 8 bins outside the refractory zone - for the left hand side, bins 40-47 (-10 to -3 ms) - for the right hand side, bins 52-59 (3 to 10 ms)
DESCRIPTION: Determine simple refractoriness in a histogram (% of spikes in +-2ms vs +-15ms window) USES: Appropriate for making QC decisions on autocorrelograms for spike firing of a given neuron DEPENDENCY TREE: None ARGUMENTS: double *tsec : input, array of timestamps for histogram (seconds) double *val : input, array of values for histogram (counts, typically, but could be proportion or probability) long bintot : input, the number of tsec and val pairs comprising the histogram double *result : input, array of values representing the result - memory must be allocated by calling function result[0]= proportion (0-1) of 0-2ms spikes in the 0-15ms zone result[1]= proportion (0-1) of 0-2ms spikes in the total histogram result[2]= spike count in negative 0-15ms window result[3]= spike count in positive 0-15ms window result[4]= spike count in negative 0-2ms window result[5]= spike count in positive 0-2ms window result[6]= total spike count in histogram RETURN VALUE: none NOTES: Focusing on spikes within +-15ms of reference spike ensures that bursty and non-bursty cells are treated similarly A ratio of ɬ.08 should be used to automatically reject a histogram A ratio of ɘ.01 represents an exceptionally clean refractory period Total number of bins (bintot) must allow at least 1ms precision in calculation of times 50-75 spikes are required in the 30ms window to make a good decision - however, it would also suffice if half the histogram has 35-50 spikes
DESCRIPTION: John Huxter: 20 January 2011 Calculate theta-modulation in a histogram - looks for negative and positive inflections - histogram should be smoothed and spline-interpolated first - histogram should be normalized to range from 0-1
DESCRIPTION: Perform linear interpolation across invalid data points - modifies the original array - expects NAN or INF to be used to designate invalid values - blocks of invalid numbers at top and bottom of record are filled with first and last valid datum, respectively USES: Fill in gaps in an array of data DEPENDENCY TREE: No dependencies ARGUMENTS: double *data : array already holding the data long ndata : number of elements in the data array RETURN VALUE: total points interpolated across -1: no valid data found SAMPLE CALL:
DESCRIPTION: Perform linear interpolation across invalid data points - modifies the original array - expects NAN or INF to be used to designate invalid values - blocks of invalid numbers at top and bottom of record are filled with first and last valid datum, respectively USES: Fill in gaps in an array of data DEPENDENCY TREE: No dependencies ARGUMENTS: float *data : array already holding the data long ndata : number of elements in the data array RETURN VALUE: total points interpolated across -1: no valid data found SAMPLE CALL:
DESCRIPTION: Perform conditional linear interpolation across invalid data points - this version also allows user to specify the maximum number of values to interpret across - modifies the original array - expects NAN or INF to be used to designate invalid values - blocks of invalid numbers at top and bottom of record are filled with first and last valid datum, respectively USES: Fill in gaps in an array of data, but not gaps which are too large DEPENDENCY TREE: No dependencies ARGUMENTS: float *data : array already holding the data long ndata : number of elements in the data array long max : maximum number of points to interpolate across, -1 = no limit RETURN VALUE: total points interpolated across -1: no valid data found SAMPLE CALL:
DESCRIPTION: Perform linear interpolation across invalid data points (double) - user specifies the invalid value to interpolate across - modifies the original array - invalid numbers at the start/end of the input can be filled with first/last valid datum, respectively USES: fill in gaps in an array of data DEPENDENCIES: none ARGUMENTS: double *data : input, array long ndata : input, length of input array short invalid : invalid value for interpolation (typically FLOAT_MIN or FLOAT_MAX) int setfill : edge-fill invalid values with nearest valid (0=none,1=start,2=end,3=both result[3] : result indices result[0] = index to first good value (will be 0 if startsetfill is set) result[1] = index to last good value (will be ndata-1 if endsetfill is set) result[2] = total interpolated points RETURN VALUE: 0: success 1: fail - no good data SAMPLE CALL:
DESCRIPTION: Perform linear interpolation across invalid data points (float) - user specifies the invalid value to interpolate across - modifies the original array - invalid numbers at the start/end of the input can be filled with first/last valid datum, respectively USES: fill in gaps in an array of data DEPENDENCIES: none ARGUMENTS: float *data : input, array long ndata : input, length of input array short invalid : invalid value for interpolation (typically FLOAT_MIN or FLOAT_MAX) int setfill : edge-fill invalid values with nearest valid (0=none,1=start,2=end,3=both result[3] : result indices result[0] = index to first good value (will be 0 if startsetfill is set) result[1] = index to last good value (will be ndata-1 if endsetfill is set) result[2] = total interpolated points RETURN VALUE: 0: success 1: fail - no good data SAMPLE CALL:
DESCRIPTION: Perform linear interpolation across invalid data points (short integer) - user specifies the invalid value to interpolate across - modifies the original array - invalid numbers at the start/end of the input can be filled with first/last valid datum, respectively USES: fill in gaps in an array of data DEPENDENCIES: none ARGUMENTS: short *data : input, array long ndata : input, length of input array short invalid : invalid value for interpolation (typically SHRT_MIN or SHRT_MAX) int setfill : edge-fill invalid values with nearest valid (0=none,1=start,2=end,3=both result[3] : result indices result[0] = index to first good value (will be 0 if startsetfill is set) result[1] = index to last good value (will be ndata-1 if endsetfill is set) result[2] = total interpolated points RETURN VALUE: 0: success 1: fail - no good data SAMPLE CALL:
DESCRIPTION: Create a set of jittered x-values to apply to an input set of y-values USES: Apply jitter to x-values in grouped data so points don't overlap in plot DEPENDENCIES: xf_rand1_d ARGUMENTS: double *yval : input array, mean used for defining scaling for jitter long nn : number of input/output items double centre : centre-value for result double limit : limit for deviation from centre-value (absolute value) char *message : pre-allocated array to hold error message RETURN VALUE: pointer to array on success, NULL on error message array will hold explanatory text (if any) SAMPLE CALL: long ii,nn=100; double *xval=NULL, yval[100]; char message[1000],*thisprog="test\0"; for(ii=0;ii<nn;ii++) yval[ii]= (double)ii; xval= xf_jitter1_d(yval,nn,5,0.25,message); if(xval==NULL) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } for(ii=0;ii<nn;ii++) printf("%g\t%g\n",xval[ii],yval[ii]); <TAGS> math </TAGS>
DESCRIPTION: Perform a fast Fourier transfer on a time-series USES: DEPENDENCY TREE: ARGUMENTS: RETURN VALUE: SAMPLE CALL:
DESCRIPTION: Return the comment-status of an input line USES: DEPENDENCY TREE: No dependencies ARGUMENTS: char *line : input, pointer to a character array int &skip : current status of skip : initialize to zero for first time the function is called : allows commenting to be carried over from previous lines contiaining a quote or /* RETURN VALUE: Always zero TEST PROGRAM: skip=0; while(fgets(line,MAXLINELEN,fpin)!=NULL) { xf_linecomment1(line,&skip); printf("%s",line); }
DESCRIPTION: Modify a line, parsing it into whitespace-delimited words, and modify an array of indices to each word The variable "nwords" will be modified to reflect the number of words on the line The "line" array will be modified, each white-space delimiter replaced by a NULL character NOTE: multiple whitespace is treated as a single whitespace, so "empty" words in a line will affect the index to all subsequent columns. Example: if the input file looks like this... a b c a c ... then word#2 will be "b" on line#1, but "c" on line#2 NOTE: Leading white-space will insert a NULL at the beginning of the line, but start[0] will point to the first non-whitespace character on the line. This can be handy in space-delimited files where leading white-space signifies an empty field This can be detected using strlen(line), as opposed to strlen((line+start[0])) NOTE (4.November.2016) Text within quotes will be treated as a single word single-quotes within double-quotes (or vice-versa) will not trigger the start/end of quoted text Hence "don't exit" will be treated as a single word, the internal space and single-quote ignored - additional updates: new variable names, better use of memory USES: provides a set of indices to each column in a line advantage over strtok: finds all words in a line at once, COULD be modified to treat each delimiter as a separate word disadvantages over strtok: not as fast DEPENDENCY TREE: No dependencies ARGUMENTS: char *line - input, pointer to a character array long *nwords - address to a long integer to hold the total number of words found RETURN VALUE: Success: A pointer to a long-integer array holding the start locations of each word in line - memory is allocated for this array inside the function - the variable nwords will be updated to report the number of delimited words on the line Blank line: NULL, nwords=0; Memory allocation fail: NULL, nwords=-1 TEST PROGRAM: #include <stdio.h> #include <stdlib.h> long *start=NULL,nwords,i; char line[13]={"dog cat pig"}; start= xf_lineparse1(line,&nwords); for(i=0;i<nwords;i++) printf("%s\n",line+start[i]); if(start!=NULL) free(start); exit(0);
DESCRIPTION: Modify a line, parsing it into delimited words, and modify an array of indices to each word Behaves much like the linux "cut" command - unlike strtok, serial delimiters are not treated as a single delimiter - hence two consecutive delimiters, or delimiters at the beginning or end of the line, signify a missing word - note: using strtok to identify words in a line is faster, but strtok is not appropriate for CSV files USES: provides a set of indices to each column in a line suitable for reading particular columns from CSV files or other ASCII files where "blank" fields are possible DEPENDENCY TREE: No dependencies ARGUMENTS: char *line - input, pointer to a character array char *delimiters - input, delimiter characters to consider long *nwords - address to a long integer to hold the total number of words found RETURN VALUE: Success: A pointer to a long-integer array holding the start locations of each word in line - memory is allocated for this array inside the function - the variable nwords will be updated to report the number of delimited words on the line Blank line: NULL, nwords=0; Memory allocation fail: NULL, nwords=-1 TEST PROGRAM: #include <stdio.h> #include <stdlib.h> long *start=NULL,nwords,i; char line[13]={"dog cat pig"}; start= xf_lineparse2(line,"\t ",&nwords); for(i=0;i<nwords;i++) printf("%s\n",line+start[i]); if(start!=NULL) free(start); exit(0); ???TO DO: may be able to improve using search method more like lineparse1 (simple serial scan)
DESCRIPTION: A safer version of fgets to read a line of unknown length from an ASCII file For files with lines ~ 4000 characters wide, read time is about 80% the speed of fgets alone Uses fgets and concatenates the results to the variable "line" Characters are read in buffers of length XF_LINEREAD1_BUFFSIZE (typically 1000) - If buffer length is less than the length of the line being read, multiple calls to fgets are made - the function checks if the buffer contains a newline - if so further calls to fgets are halted Memory reserved for "line" is expanded as required Blank lines are correctly returned Lines without a terminating newline are correctly returned Input must be NULL-terminated Last update: 18 February 2013 [JRH] USES: Situations where fgets is inappropriate because maximum line length is unknown Example - reading large tables or matrices of data DEPENDENCY TREE: No dependencies ARGUMENTS: char *line - pointer to a character array - new memory will be allocated and will be overwritten long *maxlinelen - variable holding the most recent value for maxmimum line length - updated with the actual length of the line, if this exceeds the initial value - the calling function should pass the address (&) of the variable, function will read as a pointer (*) - if maxlinelen is set to "-1", this indicates a memory allocation error occurred FILE *fpin - pointer to input stream (typically a file or stdin) - updated by the function RETURN VALUE: A pointer to a character array holding the new line - NULL if no line was read TEST PROGRAM: // save function as xf_lineread1.c // save as "xe-test.c" in same folder as xf_lineread1.c // compile as follows: gcc -O3 -std=gnu99 xe-test.c xf_lineread1.c -o xe-test) #include <stdio.h> #include <stdlib.h> char *xf_lineread1(char *line, long *maxlinelen, FILE *fpin); int main (int argc, char *argv[]) { char *line=NULL,*pline; long maxlinelen=0; FILE *fpin; if(argcɚ) { fprintf(stderr,"USAGE: xe-test [filename] \n"); exit(0); } fpin=fopen(argv[1],"r"); if(fpin==0) { fprintf(stderr,"File read error\n"); exit(1); } while((pline= xf_lineread1(line,&maxlinelen,fpin) )!=NULL) { if(maxlinelenɘ) { fprintf(stderr,"Memory allocation error\n"); exit(1); } else printf("%s",pline); } fclose(fpin); fprintf(stderr,"\nlongest line: %d characters\n",maxlinelen); if(line!=NULL) free(line); }
DESCRIPTION: - Read a block of data replicates in which specfied key-columns do not change - blank lines will be ignored - Each call extracts a single block of data - the unchanging key-values - an array of "repeated-measures" values which are allowed to change within the block - an array of data for the block - Can be called multiple times until the end of the file is reached - 6.May.2019 [JRH] DEPENDENCIES: xf_lineparse2 ARGUMENTS: long *par : array of control and results parameters par[0] status (output): set to -9 for first call, so function initialises keyprev[] par[1] ndata (output): number of data-points extracted par[2] nkeys (input): the number of key-colmns par[3] repcol (input): column-number holding the repeated-measures values par[4] datcol (input): column-number holding the data-values par[5] maxdat (input): maximum allowable size of the block double *keycurr : output[nkeys] of current key-values double *keyprev : input[nkeys] of key-values from previous call - use par[0]=-9 to initialize long *keycol : input[nkeys] to hold the column-numbers double *rep1 : output[maxdat], repeated-measures-values for the block double *dat1 : output[maxdat], data for the block FILE *fpin : file-pointer to input stream - files or stdin char *message : pre-allocated array to hold error message RETURN VALUE: none - prams[0] (status) will be updated: ɘ: error (check contents of message) 0: end-of-file 1: block read successfully, there may be more - par[1] will contain the number of datapoints in the extracted block - keycurr[nkeys] will contain the fixed key-values for the block - keyprev[nkeys] will contain the fixed key-values for the block TEST PROGRAM: nkeys= 3; maxdat= 1000; keycurr= malloc(nkeys*sizeof(*keyprev)); keyprev= malloc(nkeys*sizeof(*keyprev)); rep1= malloc(maxdat*sizeof(*rep1)); dat1= malloc(maxdat*sizeof(*dat1)); keycol[0]=5;keycol[1]=6;keycol[2]=7; par[0]=-9; par[1]=0; par[2]=nkeys; par[3]=repcol; par[4]=datcol; par[5]=setmaxdat; if(strcmp(infile,"stdin")==0) fpin=stdin; else if((fpin=fopen(infile,"r"))==0) {fprintf(stderr,"\n--- Error[%s]: file \"%s\" not found\n\n",thisprog,infile);exit(1);} while(++nn) { xf_linereadblock1(par,keycurr,keyprev,keycol,rep1,dat1,fpin,message); status= par[0]; ndata= par[1]; if(statusɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } for(ii=0;ii<ndata;ii++) { for(jj=0;jj<nkeys;jj++) printf("%g\t",keyprev[jj]); printf("%f\t%f\n",rep1[ii],dat1[ii]); } printf("\n"); if(status==0) break; // end of file if(status==1) for(ii=0;ii<nkeys;ii++) keyprev[ii]= keycurr[ii]; } if(strcmp(infile,"stdin")!=0) fclose(fpin); <TAGS>file database</TAGS>
DESCRIPTION: Purpose ======= Computes the Lomb-Scargle periodogram as developed by Lomb (1976) and further extended by Scargle (1982) to find, and test the significance of weak periodic signals with uneven temporal sampling. This subroutine calculates the periodogram using a slightly modified algorithm due to Townsend (2010) which allows the periodogram to be calculated using only a single pass through the input samples. This requires Nw(2Nt+3) trigonometric function evaluations (where Nw is the number of frequencies and Nt the number of input samples), giving a factor of ~2 speed increase over the straightforward implementation. Arguments ========= t(input) double precision array, dimension (Nt) Sample times x(input) double precision array, dimension (Nt) Measurement values w(input) double precision array, dimension (Nt) Angular frequencies for output periodogram P(output) double precision array, dimension (Nw) Lomb-Scargle periodogram Nt (input) integer Dimension of input arrays Nw (output) integer Dimension of output array Further details =============== P[i] takes a value of A^2*N/4 for a harmonic signal with frequency w(i).
DESCRIPTION: Calculate mean absolute error (MAE) between two series, corrected by the range of series-1 Less sensitive to ourliers than RMSE https://en.wikipedia.org/wiki/Mean_absolute_error USES: Estimate the goodness of fit between two lines DEPENDENCIES: None ARGUMENTS: float *data1 : input array representing values for line #1 float *data2 : input array representing values for line #2 long nn : number of elements in each array double *result : pre-allocated array to hold results - must allow at least 6 elements char *message : pre-allocated array to hold error message RETURN VALUE: MAE on success, INF on horizontal line for NAN on error char array will hold message (if any) SAMPLE CALL: mae= xf_mae1_d(data1,data2,nn,message); if(!isfinite(mae)) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); }
DESCRIPTION: - remove clusters from a club/t record which do not match the ID's specified in a list USES: - reducing the size of a cluster record to make processing more efficient DEPENDENCY TREE: long *xf_lineparse2(char *line,char *delimiters, long *nwords); ARGUMENTS: char *list1 : pointer to CSV list of clusters to keep long *clubt : input array of cluster timestamps short *club : input array of cluster-IDs long nn : total number of items in the clubt[] and club[] char *message : pre-allocated array to hold error message RETURN VALUE: on success: - the new number of clubt[] and club[] records - the clubt[] and club[] arrays themselves will be adjusted accordingly on failure: -1 SAMPLE CALL:
DESCRIPTION: Calculate the average matrix from a multi-matrix array John Huxter - 4.March.2012 USES: Creating averages of 2-dimensional arrays - eg. density maps DEPENDENCY TREE: No dependencies ARGUMENTS: double *multimatrix - input array already holding data for multiple matrices to be averaged - NOTE: values for each matrix should be normalized first int n_matrices - number of matrices long bintot - number of cells in each matrix char message[] - holds error message or other report - recommended pre-allocation of memory by calling function (eg. char message[256]) RETURN VALUE: A pointer to an array (newmatrix) of type double with xbins*ybins elements This variable must be initialized by the calling function and assigned value NULL This function will handle assigning sufficient memory If a memory allocation error occurs, a NULL is returned SAMPLE CALL: new= xf_matrixavg1_d(multimatrix,nmatrices,bintot,message); if(new==NULL) {fprintf(stderr,"--- Error: %s\n",message) ; exit(1);}
DESCRIPTION: Calculate the average matrix from a multi-matrix array John Huxter - 4.March.2012 USES: Creating averages of 2-dimensional arrays - eg. density maps DEPENDENCY TREE: No dependencies ARGUMENTS: float *multimatrix - input array already holding data for multiple matrices to be averaged - NOTE: values for each matrix should be normalized first size_t n_matrices - number of matrices size_t bintot - number of cells in each matrix char message[] - holds error message or other report - recommended pre-allocation of memory by calling function (eg. char message[256]) RETURN VALUE: A pointer to an array (newmatrix) of type double with xbins*ybins elements This variable must be initialized by the calling function and assigned value NULL This function will handle assigning sufficient memory If a memory allocation error occurs, a NULL is returned SAMPLE CALL: new= xf_matrixavg1_f(multimatrix,nmatrices,bintot,message); if(new==NULL) {fprintf(stderr,"--- Error: %s\n",message) ; exit(1);}
DESCRIPTION: Downsize an input array representing a 2D matrix to a new width and heght Alters the input array NAN and INF values will be ignored This function has no memory overhead USES: - resampling an image or matrix to reduce resolution - modifying different matrices so they are all the same size DEPENDENCY TREE: No dependencies ARGUMENTS: double *matrix1 : input array long nx1 : width of input long ny1 : height of input long nx2 : desired width long ny2 : desired height char *message : array to hold error message RETURN VALUE: 0 on sucess, -1 on error SAMPLE CALL:
DESCRIPTION: Calculate the spatial coherence of a matrix - how well does one bin rate predict the 8 neighbouring bins - coherence = z-transform of correlation between each matrix element and the mean of surrounding elements - non-finite elements will be ignored USES: DEPENDENCIES: double xf_correlate_simple_d(double *x, double *y, long nn, double *result_in); ARGUMENTS: double *rate : the input matrix array long width : matrix width (number of elements) long height : matrix height (number of elements) double *result_out : pre-allocated array to hold results (16-elements) char *message : pre-allocated array to hold error message, if any RETURN VALUE: - the spatial coherence in the matrix, or NAN on error - result array will hold additional statistics result_out[0]= SAMPLE CALL:
DESCRIPTION: - invalidate (set to zero) matrix bins not adjacent to other non-zero bins - designed for long-integer matrix arrays recording counts of events USES: - allow programs to ignore isolated bins in a map DEPENDENCY TREE: No dependencies ARGUMENTS: long *matrix1 : input, preallocated array matrix (counts) long setxbintot : input, width of array long setybintot : input, height of array long setcontig : input, minimum adjacent non-zero bins required to keep a bin (must be 0-8) char *message : output pre-allocated array to hold error message RETURN VALUE: status flag (0=OK, -1=ERROR) matrix1 array will be overwritten message array will hold message (if any) SAMPLE CALL: long matrix[15]; width=3; height=5; z= xf_matrixcontig1_l(matrix,width,height,1,message); if(z=-1) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); }
DESCRIPTION: Expand an array of numbers representing a 2D matrix Rows and columns are duplicated to achieve the user-specified height and width NAN values will be ignored, but INF will affect the results Input array is unaltered NOTE: this function requires additional memory equivalent to at least the input array size USES: - resampling an image or matrix to increase resolution - modifying different matrices so they are all the same size DEPENDENCY TREE: No dependencies ARGUMENTS: double *matrix1 : input array long nx1 : width of input long ny1 : height of input long nx2 : desired width long ny2 : desired height char *message : array to hold error message RETURN VALUE: Pointer to modified matrix - NULL on error SAMPLE CALL:
DESCRIPTION: Flip (x or y) a 1-dimensional array meant to be interpreted as a 2-dimensional matrix - makes an internal copy of data, modifies it, and copies it back to the original - therefore, safer for memory management and nested functions, but has a heavier computational load - Example - x-flip 1 2 3 3 2 1 4 5 6 --becomes--> 6 5 4 7 8 9 9 8 7 USES: - image or map rotation - matrix algebra DEPENDENCIES: None ARGUMENTS: long *data1 : input/output - pointer to array of numbers representing the original matrix long *nx1 : input - width of the matrix long *ny1 : input - height of the matrix int setflip : input - flip axis - 1=x, 2=y RETURN VALUE: 0 on success -1 for invalid size of input -2 for invalid arguments -3 for memory allocation error
DESCRIPTION: Flip a matrix in the y-dimension Example: this matrix... 0 1 2 3 4 5 6 7 8 9 10 11 ... will be flipped to ... 3 2 1 0 7 6 5 4 11 10 9 8 USES: DEPENDENCY TREE: No dependencies ARGUMENTS: double *data1 : pointer to array of numbers representing the original matrix - sufficient memory must be allocated by calling program - this original memory will be freed long nx : width of the matrix long ny : height of the matrix - width and height must accurately reflect the total size of the data1 array NOTE: width and height are not swapped by this function, so if the calling function uses these variables after transposition, it is the responsibility of the calling function to do the swap RETURN VALUE: A pointer to a FLIPPED version of the original numbers Returns NULL if a memory allocation error was encountered SAMPLE CALL : matrix= xf_matrixflipx_d(matrix, width, height);
DESCRIPTION: Flip a matrix in the y-dimension Example: this matrix... 0 1 2 3 4 5 6 7 8 9 10 11 ... will be flipped to ... 8 9 10 11 4 5 6 7 0 1 2 3 USES: - converting cartesian to plotting coordinates or vice-versa DEPENDENCY TREE: No dependencies ARGUMENTS: double *data1 : pointer to array of numbers representing the original matrix - sufficient memory must be allocated by calling program - this original memory will be freed long nx : width of the matrix long ny : height of the matrix - width and height must accurately reflect the total size of the data1 array NOTE: width and height are not swapped by this function, so if the calling function uses these variables after transposition, it is the responsibility of the calling function to do the swap RETURN VALUE: A pointer to a FLIPPED version of the original numbers Returns NULL if a memory allocation error was encountered SAMPLE CALL : matrix= xf_matrixflipy_d(matrix, width, height);
DESCRIPTION: - define a peak-zone of contiguous values exceeding a threshold in a 2D matrix - peak propogates out in an expanding radius from the highest un-masked element exceeding the threshold - propogation diagonally is prevented - simplified version of the old hux_findspot function USES: - define a hippocampal place field - find a bright spot in a video frame - define a peak in a phase-amplitude coupling plot DEPENDENCY TREE: No dependencies ARGUMENTS: double *data1 : input array holding a matrix of values in which peak zone is to be found int *mask : input/output array initialized by calling function and used to report peak detection long width : width of the matrix long height : height of the matrix float thresh : minimum threshold to be exceeded for inclusion in the peak zone double *result : array initialized by calling function to hold results Regarding the mask array: - presumed to be zero at start - set to 1 on addition to the peak zone - if initially less than zero, that element in the data is ignored - allows successive calls to the funtion - set previously detected mask elements to -1 to allow detection of other peaks Regarding the results array: result[0]= number of elements in peak result[1]= x-position (zero-offset element) of max value result[2]= y-position (zero-offset element) of max value result[3]= x-position of centre of mass (left=0) result[4]= x-position of centre of mass (top=0) result[5]= mean value of elements inside peak zone result[6]= max value (value in the pixel which is the field kernal) RETURN VALUE: 1 on success, 0 on error
DESCRIPTION: Read one or more matrices from an input Each matrix should be separated by a blank line or a line whos first character is "#" Data is stored as a continuous array of double-precision floating point numbers Automatically detects the number of rows and columns in the input - the first matrix is taken as the model - discrepancies result in errors The number of matrices and the number of rows and columns are stored NOTE: multiple whitespace is treated as a single whitespace - so "empty" words in a line will affect the index to all subsequent columns. USES: storing 2-d blocks of ascii data into memory as a 1d array DEPENDENCY TREE: No dependencies ARGUMENTS: long *nmatrices - output variable, how many matrices were read long *ncols - output variable, how many columns are on each row of each matrix long *nrows - output variable, how many rows are in each matrix char *message - holds error messages - should be defined by caliing funtion as message[256] FILE *fpin - pointer to input stream (typically a file or stdin) - updated by the function RETURN VALUE: - A pointer to an array holding the matrix, or multiple matrices packed together - NULL if no line was read - note that nmatrices, ncols and nrows will also be updated SAMPLE CALL: data1= xf_matrixread1_d(&nmatrices1,&ncols1,&nrows1,message,fpin);
DESCRIPTION: Read one or more matrices from an input Each matrix should be separated by a blank line or a line whos first character is "# followed by an identifier number" Data is stored as a continuous array of double-precision floating point numbers Automatically detects the number of rows and columns in the input - the first matrix is taken as the model - discrepancies result in errors The number of matrices and the number of rows and columns are stored NOTE: multiple whitespace is treated as a single whitespace, so "empty" words in a line will affect the index to all subsequent columns. USES: storing 2-d blocks of ASCII data into memory as a 1d array DEPENDENCIES: char *xf_lineread1(char *line, long *maxlinelen, FILE *fpin); ARGUMENTS: char *infile - name of the input file, or "stdin" long idcol - for lines starting with "#", the zero-offset column-number holding the id (typically "1") double **matrix1 - result, multi-matrix data - freed by calling function double **id1 - result, id's for each matrix - freed by calling function long *ncols - result, how many columns are on each row of each matrix long *nrows - result, how many rows are in each matrix char *message - holds error messages - should be defined by calling funtion as message[256] FILE *fpin - pointer to input stream (typically a file or stdin) - updated by the function RETURN VALUE: - the number of matrices detected, or -1 on error - the matrix1[] array is filled - the id1[] array stores the identifiers for each matrix, presuming they are preceded by a "# <identifier>" line - the message[] array will hold any errors SAMPLE CALL: char message[256]; double *matrix1=NULL, *id1=NULL, *pmatrix; long nmatrices,ncols,nrows,ii,jj,kk,mm,idcol=1; nmatrices= xf_matrixread1_d(&matrix1,idcol,&id1,&ncols1,&nrows1,message,fpin); mm=5; pmatrix= matrix1+(mm*ncols*nrows); // select fifth matrix printf("# %g\n",id1[mm]); // print the identifier for(ii=0;ii<nrows;ii++) { for jj=0;jj<ncols;jj++) printf("%g ",pmatrix[ii*ncols+jj]); printf("\n"); }
DESCRIPTION: Read one matrix from a single- or multi-matrix input Multiple matrices should be separated by a blank (\n) or header-line (#) - every encountered header-line updates the header array - if data has been read at this point, the function returns - therefore, the header is set for subsequent data on the next call Automatically detects the number of rows and columns in the input - row #1 is taken as the default number of columns - all rows must be the same width Stores the preceding and most recent header line (#) NOTE: multiple whitespace is treated as a single whitespace, so "empty" words in a line will affect the index to all subsequent columns. USES: - Finding matrices for a given subject or group in a multi-matrix file DEPENDENCIES: char *xf_lineread1(char *line, long *maxlinelen, FILE *fpin); long *xf_lineparse1(char *line,long *nwords); ARGUMENTS: FILE *fpin - input: pointer to input stream (typically a file or stdin) - updated by the function long *ncols - output: number of columns on each row (pass as address) long *nrows - output: number of rows (pass as address) char *header - output[256]: header for the current matrix char *message - output[256]: header for next matrix, or error message, if any NOTE: calling function must allocate at least 256-byetes each for header[] and message[] NOTE: header[] and message[] should be initialized to '\n\0' before first call to this function RETURN VALUE: - on success: - A pointer to an array holding the matrix (NULL at end of file) - header[] contains the header preceeding the matrix - message[] contains the header for the next matrix, if there there is no preceeding blank line - on error: - ncols and nrows are set to -1 - message[] describes the error SAMPLE CALL: char header[256],message[256]; long nrows=0,ncols=0,ii,jj,kk; FILE *fpin= fopen(infile,"r"))==0); header[0]='\n' ; header[1]='\0'; message[0]='\n' ; message[1]='\0'; while(1) { matrix= xf_matrixread3_d(fpin,&width,&height,header,message); if(heightɘ) {fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message);exit(1);} if(matrix1==NULL) break; printf("%s",header); for(ii=0;ii<height;ii++) { kk= ii*width; for(jj=0;jj<width;jj++) { if(jjɬ) printf(" "); printf("%g",matrix1[kk+jj]); } printf("\n"); }} if(strcmp(infile,"stdin")!=0) fclose(fpin);
DESCRIPTION: Resample a series of numbers representing a 2D matrix, so there are a user-defined number of rows and columns Rows and columns are split (new dimensions > old dimensions) or binned & averaged (new dimensions >= old dimansions), accordingly Alters input array NAN values will be ignored, but INF will affect the results [JRH] 23 November 2015 USES: - resampling an image or matrix to reduce or increase resolution - modifying different matrices so they are all the same size DEPENDENCY TREE: xf_bin1a_d xf_expand1_d ARGUMENTS: double *martix1: input, array of numbers to be resampled - matrix format long nx1: original matrix width long ny1: original matrix height long nx2: original matrix width long ny2: original matrix height RETURN VALUE: Pointer to modified matrix - NULL on error SAMPLE CALL:
DESCRIPTION: Rotate a 1-dimensional array of numbers meant to be interpreted as a 2-dimensional matrix USES: - image or map rotation - matrix algebra DEPENDENCY TREE: No dependencies ARGUMENTS: float *data1 (input)- pointer to array of numbers representing the original matrix - sufficient memory must be allocated by calling program - this original memory will be freed long *nx1 (input/output)- width of the matrix, to be modified depending on rotation long *ny1 (input/output)- height of the matrix, to be modified depending on rotation - nx1 and ny1 MUST reflect the total size of the data1 array int r (input) - rotation (90,180,270,-90,-180,-270) - 0,360, or any other value simply results in no changes RETURN VALUE: A pointer to a rotated version of the original numbers Returns NULL if a memory allocation error was encountered NOTE: nx1 and ny1 will be also modified according to the rotation NOTE: if a valid value for "r" is set, the original memory for the matrix is freed TEST PROGRAM : #include <stdio.h> #include <stdlib.h> int main (int argc, char *argv[]) { double *xf_matrixrotate1_d(double *data1, long *nx1, long *ny1, int r); double *matrix=NULL; long width=3,height=5,n=width*height,x,y; matrix=(double *)realloc(matrix,n*sizeof(double)); for(x=0;x<n);x++) matrix[x]=(double)x; for(y=0;y<height;y++) { for(x=0;x<width;x++) printf("%g\t",matrix[y*width+x]); printf("\n"); } printf("\n"); matrix= xf_matrixrotate1_d( matrix, &width, &height, 90 ); for(y=0;y<height;y++) { for(x=0;x<width;x++) printf("%g\t",matrix[y*width+x]); printf("\n"); } }
DESCRIPTION: Rotate a 1-dimensional array of numbers meant to be interpreted as a 2-dimensional matrix USES: - image or map rotation - matrix algebra DEPENDENCY TREE: No dependencies ARGUMENTS: float *data1 (input)- pointer to array of numbers representing the original matrix - sufficient memory must be allocated by calling program - this original memory will be freed long *nx1 (input/output)- width of the matrix, to be modified depending on rotation long *ny1 (input/output)- height of the matrix, to be modified depending on rotation - nx1 and ny1 MUST reflect the total size of the data1 array int r (input) - rotation (90,180,270,-90,-180,-270) - 0,360, or any other value simply results in no changes RETURN VALUE: A pointer to a rotated version of the original numbers Returns NULL if a memory allocation error was encountered NOTE: nx1 and ny1 will be also modified according to the rotation NOTE: if a valid value for "r" is set, the original memory for the matrix is freed TEST PROGRAM : #include <stdio.h> #include <stdlib.h> int main (int argc, char *argv[]) { float *xf_matrixrotate1_d(float *data1, long *nx1, long *ny1, int r); float *matrix=NULL; long width=3,height=5,n=width*height,x,y; matrix=(float *)realloc(matrix,n*sizeof(float)); for(x=0;x<n);x++) matrix[x]=(float)x; for(y=0;y<height;y++) { for(x=0;x<width;x++) printf("%g\t",matrix[y*width+x]); printf("\n"); } printf("\n"); matrix= xf_matrixrotate1_d( matrix, &width, &height, 90 ); for(y=0;y<height;y++) { for(x=0;x<width;x++) printf("%g\t",matrix[y*width+x]); printf("\n"); } }
DESCRIPTION: Rotate a 1-dimensional array of numbers meant to be interpreted as a 2-dimensional matrix - unlike xf_matrixrotate1_d, makes an internal copy of data and modifies the original - therefore, safer for memory management and nested functions, but has a heavier computational load USES: - image or map rotation - matrix algebra DEPENDENCIES: None ARGUMENTS: double *data1 : input, pointer to array of numbers representing the original matrix long *nx1 : input/output - width of the matrix, to be modified depending on rotation long *ny1 : input/output- height of the matrix, to be modified depending on rotation int r : input - rotation (90,180,270,-90,-180,-270) RETURN VALUE: 0 on success -1 for invalid arguments -2 for memory allocation error NOTE: nx1 and ny1 will be also modified according to the rotation
DESCRIPTION: Rotate a 1-dimensional array of numbers meant to be interpreted as a 2-dimensional matrix - unlike xf_matrixrotate1_f, makes an internal copy of data and modifies the original - therefore, safer for memory management and nested functions, but has a heavier computational load USES: - image or map rotation - matrix algebra DEPENDENCIES: None ARGUMENTS: float *data1 : input, pointer to array of numbers representing the original matrix long *nx1 : input/output - width of the matrix, to be modified depending on rotation long *ny1 : input/output- height of the matrix, to be modified depending on rotation int r : input - rotation (90,180,270,-90,-180,-270) RETURN VALUE: 0 on success -1 for invalid arguments -2 for memory allocation error NOTE: nx1 and ny1 will be also modified according to the rotation
DESCRIPTION: Rotate a 1-dimensional array of numbers meant to be interpreted as a 2-dimensional matrix - makes an internal copy of data, modifies it, and copies it back to the original - therefore, safer for memory management and nested functions, but has a heavier computational load - Example - 90 degree rotation 1 2 3 7 4 1 4 5 6 --becomes--> 8 5 2 7 8 9 9 6 3 USES: - image or map rotation - matrix algebra DEPENDENCIES: None ARGUMENTS: long *data1 : input/output - pointer to array of numbers representing the original matrix long *nx1 : input/output - width of the matrix, to be modified depending on rotation long *ny1 : input/output - height of the matrix, to be modified depending on rotation int r : input - rotation (90,180,270,-90,-180,-270) RETURN VALUE: 0 on success -1 for invalid size of input -2 for invalid arguments -3 for memory allocation error NOTE: nx1 and ny1 will be also modified according to the rotation
DESCRIPTION: Transpose a 1-dimensional array of numbers meant to be interpreted as a 2-dimensional matrix Note that this differs from rotation, because low columns become low rows ( & vice versa) This version deals with double-precision floating-point numbers Example: this matrix... 0 1 2 3 4 5 6 7 8 9 10 11 ... will be transposed to... 0 4 8 1 5 9 2 6 10 3 7 11 USES: - table transposition - interchange rows and columns - matrix algebra DEPENDENCY TREE: No dependencies ARGUMENTS: double *data1 : pointer to array of numbers representing the original matrix - sufficient memory must be allocated by calling program - this original memory will be freed long width : width of the matrix long height : height of the matrix - width and height must accurately reflect the total size of the data1 array NOTE: width and height are not swapped by this function, so if the calling function uses these variables after transposition, it is the responsibility of the calling function to do the swap RETURN VALUE: A pointer to a transposed version of the original numbers Returns NULL if a memory allocation error was encountered SAMPLE CALL : matrix= xf_matrixtrans1_d(matrix, &width, &height);
DESCRIPTION: Transpose a 1-dimensional array meant to be interpreted as a 2-dimensional matrix - makes an internal copy of data, modifies it, and copies it back to the original - therefore, safer for memory management and nested functions, but has a heavier computational load - Example 1 2 3 1 4 7 4 5 6 --becomes--> 2 5 8 7 8 9 3 6 9 USES: - image or map transposition - matrix algebra DEPENDENCIES: None ARGUMENTS: long *data1 : input/output - pointer to array of numbers representing the original matrix long *nx1 : input/output - width of the matrix, will become the height long *ny1 : input/output - height of the matrix, will become the width RETURN VALUE: 0 on success -1 for invalid size of input -2 for invalid arguments -3 for memory allocation error NOTE: nx1 and ny1 will be swapped
DESCRIPTION: Create a simple Morlet wavelet Based on MATLAB functions energyvec.m and morelet_wav.m by Ole Jensen, 1997-1998 Original notes: % Create a Morlet wavelet 'y' with frequency resolution 'f' and temporal % resolution 't'. The wavelet will be normalized so the total energy is 1. % The 'width' defines the temporal and frequency resolution for the given % centre frequency 'f' by determining the number of cycles of the wavelet % itself (see Tallon-Baudry et al., J. Neurosci. 15, 722-734 (1997) or % Event-Related Potentials: A Methods Handbook, Handy (editor), MIT Press, % (2005)) USES: DEPENDENCY TREE: No dependencies ARGUMENTS: double freq : central frequency of wavelet double srate : sampling freq. of signal to be transformed with the wavelet int width : the number of cycles in the mother wavelet (>= 5 recommended). This is then scaled and translated to filter for different frequencies. See Tallon-Baudry et al., J. Neurosci. 15, 722-734 (1997)) size_t *nwav : address to a variable to hold the resultant size (elements) of the wavelet (modified by this function) RETURN VALUE: pointer to the wavelet, type = float, size=nwav NULL on failure SAMPLE CALL: #include <math.h> #include <stdio.h> float *xf_morletwavelet1_f(double f, double srate, int width, size_t *nwavelet); int main() { double freq=8.0; double sr=24000; int width=7; size_t ii,nwav; float *wavelet = xf_morletwavelet1_f(freq,srate,width,&nwav); for(ii=0;ii<nwav;ii++) printf("%d %g %g\n",ii,wavelet[ii]); free(wavelet); }
DESCRIPTION: Create a complex Morlet wavelet Based on MATLAB functions energyvec.m and morelet_wav.m by Ole Jensen, 1997-1998 Original notes: % Create a Morlet wavelet 'y' with frequency resolution 'f' and temporal % resolution 't'. The wavelet will be normalized so the total energy is 1. % The 'width' defines the temporal and frequency resolution for the given % centre frequency 'f' by determining the number of cycles of the wavelet % itself (see Tallon-Baudry et al., J. Neurosci. 15, 722-734 (1997) or % Event-Related Potentials: A Methods Handbook, Handy (editor), MIT Press, % (2005)) USES: DEPENDENCY TREE: No dependencies ARGUMENTS: double freq : central frequency of wavelet double srate : sampling freq. of signal to be transformed with the wavelet int width : parameter which defines the mother wavelet. This is then scaled and translated to filter for different frequencies, >= 5 is suggested, see Tallon-Baudry et al., J. Neurosci. 15, 722-734 (1997)) size_t *nwav : address to a variable to hold the resultant size (elements) of the wavelet (modified by this function) RETURN VALUE: pointer to the wavelet, type = complex float, size=nwav NULL on failure SAMPLE CALL: #include <math.h> #include <stdio.h> #include <complex.h> complex float *xf_morletwavelet2_f(double f, double srate, int width, size_t *nwavelet); int main() { double freq=8.0; double sr=24000; int width=7; size_t ii,nwav; complex float *wavelet = xf_morletwavelet2_f(freq,srate,width,&nwav); for(ii=0;ii<nwav;ii++) printf("%d %g %g\n",ii,creal(wavelet[ii]),cimag(wavelet[ii])); free(wavelet); }
DESCRIPTION: Calculate the F-statistic for a multi-taper power spectrum estimate This function is derived from the "get_F_values" function published here: Jonathan M. Lees and Jeffrey Park (1995) "MULTIPLE-TAPER SPECTRAL ANALYSIS: A STAND-ALONE C-SUBROUTINE" Computers & Geoscirnces Vol. 21, No. 2, pp. 199-236 Changes (JRH, January 2013) - first argument is now a structure (complex Kiss-FFT output fft[].r fft[].i) instead of separate arrays holding real and imaginary FFT output USES: DEPENDENCY TREE: requires "kiss_fftr.h" in order to define the complex data type "fft" ARGUMENTS: double *sr : (input) - real component of the FFT results double *si : (input) - imaginary component of the FFT results int nf : (input) - number of frequencies to be analyzed (typically 0.5 x length of the data the FFT was performed on) int nwin : (input) - number of tapers float *Fval : (output) - holds the f-values [nf] double *tapsum : (input) - sum of the taper values for each taper RETURN VALUE: SAMPLE CALL: get_F_values(ReSpec, ImSpec, num_freqs, nwin, Fval, tapsum);
DESCRIPTION: Get Slepian tapers (discrete prolate spheroidal sequences) This function is virtually unchanged from the "multitap" function published here: Jonathan M. Lees and Jeffrey Park (1995) "MULTIPLE-TAPER SPECTRAL ANALYSIS: A STAND-ALONE C-SUBROUTINE" Computers & Geoscirnces Vol. 21, No. 2, pp. 199-236 Lees & Park in turn mke use of two functions translated to C from the public-domain EISPACK Fortran library: jtinvit_ (in EISPACK, tinvit) jtridib_ (in EISPACK, tridib) Note that the tapers produces are orthogonal - 0 is orthogonal to 1, 2 is orthogonal to 3, 4 is orthogonal to 5, etc. What that means is, for each pair of tapers, the sum of their products is zero. USES: In multi-taper method (MTM) power spectral density estimation, use this function to derive a set of tapers to be used Repeated FFT analysis of the same data using multiple tapers a) reduces the impact of data "lost" at the edges when using a simple Hann window b) provides a more robust estimate of the power spectrum - better than smoothing a single-tapered spectrum DEPENDENCY TREE: No external dependencies ARGUMENTS: int npoints : (input) number of points in data series int ntapers : (input) number of tapers float npi : (input) order of slepian functions double *lamda : (result) vector of eigenvalues, size = ntapers - needed for adaptive averaging of spectra double *tapers : (result) matrix of slepian tapers, packed in a 1D double array double *tapsum : (result) sum(lambda)/sum(lambda-squared) - the adjusted sum of the eigenvectors, needed for calculating F-values RETURN VALUE: SAMPLE CALL:
DESCRIPTION: This function is derived from "adwait" function published here: Jonathan M. Lees and Jeffrey Park (1995) "MULTIPLE-TAPER SPECTRAL ANALYSIS: A STAND-ALONE C-SUBROUTINE" Computers & Geoscirnces Vol. 21, No. 2, pp. 199-236 Uses David Thomson's algorithm for calculating the adaptive spectrum estimate That is, averages multiple eigenspectra using adaptive weighting In practice this seems to better preserve sharp peaks in the spectra for known strong signals (eg. hippocampal theta oscillations) than simply averaging the spectra conventionally, although amplitude is reduced more. USES: DEPENDENCY TREE: No external dependencies ARGUMENTS: double *sqr_spec : (input) - amplitude spectra [ntapers*npoints, where npoints=size of FFT window] double *lambda : (input) - vector of eigenvalues [ntapers] int ntapers : (input) - number of tapers int nfreq : (input) - number of frequencies to analyze, starting from zero (typically npoints/2) double *ares : (result) - weighted average spectrum [nfreq] double *degf : (result) - degrees of freedom (can be used for calculating F, later) double avar : (input) - variance in the original input (before FFT) RETURN VALUE: SAMPLE CALL: xf_mtm_spectavg1(sqr_spec, dcf, lambda, ntapers, nfreqs, amu, degf, avar);
DESCRIPTION: Determine rate cutoffs for Robert-Muller style 10-colour firing-rate maps A fixed proportion of non-zero-rate pixels assigned to each colour... Each step up the rate ladder has 80% of the pixels of the lower colour DEPENDENCIES: xf_compare1_d ARGUMENTS: double *data : the original data array long n : total elements in the input array double *result : pointer to an array with reserved memory for at least 16 elements to hold the cutoff values USES: RETURN VALUE: 0 on success, -1 on memory allocation fail The result array is filled with cutoffs for bands of increasing values in the data result[] proportion cumulative ---------------------------------- result[0] UNKNOWN UNKNOWN - result[0] is always zero - cutoff for base-colour pixels result[1] 0.224059 0.224059 result[2] 0.179247 0.403306 result[3] 0.143398 0.546704 result[4] 0.114718 0.661422 result[5] 0.0917746 0.753197 result[6] 0.0734197 0.826616 result[7] 0.0587357 0.885352 result[8] 0.0469886 0.932341 result[9] 0.0375909 0.969932 result[10] 0.0300727 1.000000 To use this to determine the colour (z) of any given datum: z=0; for(j=0;jj++) if(data[i]>result[j]) z=j+1
DESCRIPTION: Normalize an array of double-precision floating-point numbers Data can be normalized in two ways: 0. convert to values ranging from 0-1 1. convert to z-scores USES: Can make it easier to compare skewed datasets Good for analyzing trends in data with very different baselines DEPENDENCY TREE: No dependencies ARGUMENTS: double *data : the original data - will be transformed! long nn : number of elements in the array - if Nɚ the data will not be altered. int normtype : the type of normalization 0 for forcing data to a 0-1 range 1 for producing z-scores RETURN VALUE: None. This function modifies the data input. It should never fail provided N acurately reflects the memory pre-allocated for the contents of the data array SAMPLE CALL xf_norm1_d(data,N,0)
DESCRIPTION: Normalize an array of double-precision floating-point numbers Data can be normalized in two ways: 0. convert to values ranging from 0-1 1. convert to z-scores Similar to xf_norm1_d but NAN and INF are not included in calculations USES: Can make it easier to compare skewed datasets Good for analyzing trends in data with very different baselines DEPENDENCY TREE: No dependencies ARGUMENTS: double *data : the original data - will be transformed! long ndata : number of elements in the array - if Nɚ the data will not be altered. int normtype : the type of normalization 0 for forcing data to a 0-1 range 1 for producing z-scores RETURN VALUE: The number of valid numerical data points in data OR -1: memory allocation error -2: no finite numbers in data -3: invalid normalization type This function modifies the data input. It should never fail provided N accurately reflects the memory pre-allocated for the contents of the data array SAMPLE CALL x= xf_norm1_d(data,ndata,0) if(x==-1) { fprintf(stderr,"\b\n\t--- Error [%s]: insufficient memory\n\n",thisprog); exit(1); } if(x==-2) { fprintf(stderr,"\b\n\t--- Error [%s]: no valid numbers\n\n",thisprog); exit(1); }
DESCRIPTION: Normalize an array of double-precision floating-point numbers Data can be normalized in two ways: 0. convert to values ranging from 0-1 1. convert to z-scores Similar to xf_norm1_d but NAN and INF are not included in calculations USES: Can make it easier to compare skewed datasets Good for analyzing trends in data with very different baselines DEPENDENCY TREE: No dependencies ARGUMENTS: float *data : the original data - will be transformed! long ndata : number of elements in the array - if Nɚ the data will not be altered. int normtype : the type of normalization 0 for forcing data to a 0-1 range 1 for producing z-scores RETURN VALUE: The number of valid numerical data points in data OR -1: memory allocation error -2: no finite numbers in data -3: invalid normalization type This function modifies the data input. It should never fail provided N accurately reflects the memory pre-allocated for the contents of the data array SAMPLE CALL x= xf_norm1_f(data,ndata,0) if(x==-1) { fprintf(stderr,"\b\n\t--- Error [%s]: insufficient memory\n\n",thisprog); exit(1); } if(x==-2) { fprintf(stderr,"\b\n\t--- Error [%s]: no valid numbers\n\n",thisprog); exit(1); }
DESCRIPTION: Normalize an array of double-precision floating-point numbers Data can be normalized as follows: NORMALIZE TYPE-0: CONVERT TO A RANGE FROM 0 TO 1 NORMALIZE TYPE-1: CONVERT TO Z-SCORES (use start-stop) NORMALIZE TYPE-2: difference from first valid sample (beginning at start) NORMALIZE TYPE-3: difference from mean (use start-stop) NORMALIZE TYPE-4: ratio of mean (use start-stop) - to use like previous versions of xf_norm, jj= xf_norm3_d(data,n,type,0,-1,message) USES: Can make it easier to compare skewed datasets Good for analyzing trends in data with very different baselines DEPENDENCY TREE: No dependencies ARGUMENTS: double *data : the original data - will be transformed! long ndata : number of elements in the array int normtype : the type of normalization (see above) long start : first sample (0 to [ndata-1]) to use for normalization (-1= first valid sample) long stop : last sample+1 (1 to ndata) to use for normalization (-1= last valid sample) char *message : pre-allocated array to hold error message RETURN VALUE: on success: number of valid numerical data points in data - the input data will be modified on error: -1 - there is no valid data, or reference-zone is invalid - all input becomes NAN - message array will hold WARNING text -2 if invalid parameters were passed - input is unaltered - message array will hold ERROR text SAMPLE CALL type=3; start=-1; stop=-1; ii= xf_norm3_d(data,ndata,type,start,stop,message); if(ii==-2) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } if(ii==-1) { if(setverbɬ) fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); for(jj=0;jj<ndata;jj++) datval[jj]=NAN; }
DESCRIPTION: - remove outliers from a continuous data-series - assumes the series contains multiple, equal-length blocks of data - blocks may represent individal trials, detected events, etc. - removal= invalidating blocks in which the data has an unusual shape 1. calculate median shape for all blocks of data 2. calculate similarity score for each block - mean rectified difference 3. calculate the median and median-absolute-deviation for the scores 4. test each score to see if it is under the rejection threshold - NOTE: input (dat1) should be interpolated to remove non-finite numbers REFERENCES: Boris Iglewicz and David Hoaglin (1993), "Volume 16: How to Detect and Handle Outliers", The ASQC Basic References in Quality Control: Statistical Techniques, Edward F. Mykytka, Ph.D., Editor. - modified Z-scores > 3.5 should be labelled potential outliers. DEPENDENCIES: int xf_compare1_d(const void *a, const void *b) int xf_percentile1_f(float *data, long nn, double *result) ARGUMENTS: float *dat1 : data-array containing multiple blocks of trials, events, etc long ndat1 : total number of data-points long *start : array marking the start of each block long nblocks : total number of blocks long mm : length of each block long zero : sample-in-block corresponding to time "zero" (for normalization) float thresh : theshold (std.deviations) for rejecting a block double *result_d : array holding extra results (must be able to hold 12 values) char *message : character array holding error message, if any, for return value of -1 (see below) RETURN VALUE: - number of blocks after removal of outliers - *start array will be updated so only times of "good" blocks remain - *result_d will be updated result_d[0]: the median score result_d[1]: the median-absolute-deviation for the scores (MAD) result_d[2]: the adjusted threshold (thresh*MAD) - error: -1 - the message[] array will contain the description) SAMPLE CALL: # for a recording of 12 EEG trials. remove trials where the shape of the EEG is unusual # sample rate is 1KHz, and each trial lasts 3 seconds (3000 samples), with time-zero actually at the 1-seond mark mm= xf_outlier2_f(dat1,24000500,start,12,3000,500,2.5,result,message); if(mmɘ) { fprintf(stderr,"\b\n\t%s/%s: %s\n",thisprog,errmessage,message; exit(1); }
DESCRIPTION: Pad an array of floating-point numbers with extra values at the beginning and/or end Padding is with zeros The original array will be modified NOTE: original array MUST be defined as float * in calling function NOTE: calling function MUST reallocate additional memory for original array before calling this function USES: To create an aray of a specified size Note: the array should subsequently be trimmed to remove the extra values DEPENDENCY TREE: No dependencies ARGUMENTS: float *data : array already holding data to be padded long nn : number of elements in the array long npad : size of the padding to be added int type : type of padding: 1=start, 2=end, 3=both char* message : array to hold reults message RETURN VALUE: positive integer: number of elements in the padded array -1: error: invalid type -2: error: invalid amount of padding SAMPLE CALL: # pad an array of 1000 elements with 50 values at either end data= xf_padarray0_f(data,1000,50,3,message); if(data==NULL) { fprintf(stderr,"Error: %s\n",message); exit(1); }
DESCRIPTION: Pad an array of floating-point numbers with extra values at the beginning and/or end Padding is designed to gradually reduce the rate of change at either end of the array to zero Total change in padded region is scaled to a fraction of the total data range The original array will be modified - the modified array size will be n+npad (if type=1 or type=2) or n+(npad*2) (if type=3) - this function allocates additional memory for the padded array USES: To prevent edge-effects when filtering the array Note: the array should subsequently be trimmed to remove the extra values DEPENDENCY TREE: No dependencies ARGUMENTS: float *data : array already holding data to be padded long nn : number of elements in the array long npad : size of the padding to be added int type : type of padding: 1=start, 2=end, 3=both char* message : array to hold reults message RETURN VALUE: success: pointer to padded array failure: NULL SAMPLE CALL: # pad an array of 1000 elements with 50 values at either end data= xf_padarray1_f(data,1000,50,3,message); if(data==NULL) { fprintf(stderr,"Error: %s\n",message); exit(1); }
DESCRIPTION: Pad an array of floating-point numbers with extra values at the beginning and/or end Padding is a reverse-copy of the data at either end, trended to zero using a cosine taper The original array will be modified - the modified array size will be n+npad (if type=1 or type=2) or n+(npad*2) (if type=3) - this function allocates additional memory for the padded array USES: To prevent edge-effects when filtering the array Note: the array should subsequently be trimmed to remove the extra values DEPENDENCY TREE: No dependencies ARGUMENTS: float* data : array already holding data to be padded long nn : number of elements in the array long npad : size of the padding to be added (must be <=n) int type : type of padding: 1=start, 2=end, 3=both char* message : array to hold reults message RETURN VALUE: success: pointer to padded array failure: NULL SAMPLE CALL: # pad an array of 1000 elements with 50 values at either end data= xf_padarray2_f(data,1000,50,3,message); if(data==NULL) { fprintf(stderr,"Error: %s\n",message); exit(1);
DESCRIPTION: Pad an array of floating-point numbers with extra values at the beginning and/or end Padding is composed of the mean for the first and/or last npad values in the input array The original array will be modified - the modified array size will be n+npad (if type=1 or type=2) or n+(npad*2) (if type=3) - this function allocates additional memory for the padded array USES: To prevent edge-effects when filtering the array Note: the array should subsequently be trimmed to remove the extra values DEPENDENCY TREE: No dependencies ARGUMENTS: float* data : array already holding data to be padded long nn : number of elements in the array long npad : size of the padding to be added (must be <=n) int type : type of padding: 1=start, 2=end, 3=both char* message : array to hold reults message RETURN VALUE: success: pointer to padded array failure: NULL SAMPLE CALL: # pad an array of 1000 elements with 50 values at either end data= xf_padarray3_f(data,1000,50,3,message); if(data==NULL) { fprintf(stderr,"Error: %s\n",message); exit(1);
DESCRIPTION: Pad an array of floating-point numbers with extra values at the beginning and/or end Padding is "sample-and-hold" : the first and/or last values in the input array Benefit: cannot introduce any sharp transitions or oscillations into the data The original array will be modified - the modified array size will be n+npad (if type=1 or type=2) or n+(npad*2) (if type=3) - this function allocates additional memory for the padded array USES: To prevent edge-effects when filtering the array Note: the array should subsequently be trimmed to remove the extra values DEPENDENCY TREE: No dependencies ARGUMENTS: float* data : array already holding data to be padded long* nn : number of elements in the array, passed as address, will be updated long npad : size of the padding to be added (must be <=n) int type : type of padding: 1=start, 2=end, 3=both char* message : array to hold reults message RETURN VALUE: success: pointer to padded array, nn variable will be updated failure: NULL SAMPLE CALL: # pad an array of 1000 elements with 50 values at either end nn= 1000; data= xf_padarray4_f(data,&nn,50,3,message); if(data==NULL) { fprintf(stderr,"Error: %s\n",message); exit(1);}
DESCRIPTION: Pad an array of floating-point numbers with extra values at the beginning and/or end Padding is a reverse-copy of the data at either end, trended to zero using a cosine taper The original array will be modified Calling function must acknowledge that new array size will be n+npad (if type=1 or type=2) or n+npad+npad (if type=3) USES: To prevent edge-effects when filtering the array Note: the array should subsequently be trimmed to remove the extra values DEPENDENCY TREE: No dependencies ARGUMENTS: float* data : array already holding data to be padded long nn : number of elements in the array long npad : size of the padding to be added (must be <=n) int type : type of padding: 1=start, 2=end, 3=both char* message : array to hold reults message RETURN VALUE: success: pointer to padded array failure: NULL SAMPLE CALL: # pad an array of 1000 elements with 50 values at either end data= xf_padcos2_f(data,1000,50,3,message); if(data==NULL) { fprintf(stderr,"Error: %s\n",message); exit(1);
DESCRIPTION: Generate a 3-anchor RGB colour-palette (0-1 range) DEPENDENCIES: xf_interp3_f ARGUMENTS: float *red : pre-allocated array for red values (0-1) float *green : as above for green float *blue : as above for blue long nn : size of the array to fill (number of colours) char *palette : name of the palette (grey,rainbow,viridis,plasma,magma,inferno) RETURN VALUE: 0 on success, -1 on error (invalid palette) result array will hold statistics message array will hold explanatory text (if any) SAMPLE CALL: #define N 100 int ii; float red[N],green[N],blue[N]; xf_palette3(red,green,blue,N,"rainbow"); for(ii=0;ii<N;ii++)printf("%g\t%g\t%g\n",red[ii]),green[ii],blue[ii]); TO BUILD EXTRA PALLETES USING R 1. in R, print a list of 3 hex values spanning the range library(viridis) viridis(3,option="inferno") 2. copy this into a list, removing internal quotes.. eg. list='#440154FF #443A83FF #31688EFF #21908CFF #35B779FF #8FD744FF' 3. build a code snippet for i in $list ; do xs-hex2rgb $i ; done | awk 'BEGIN{n=-1} {for(i=1;i<=NF;i++) { printf("ct[%d]=%s; ",++n,$i); } printf("\n")}' <TAGS> programming LDAS </TAGS>
DESCRIPTION: Generate a 7-anchor RGB colour-palette (0-1 range) DEPENDENCIES: xf_interp3_f ARGUMENTS: float *red : pre-allocated array for red values (0-1) float *green : as above for green float *blue : as above for blue long nn : size of the array to fill (number of colours) char *palette : name of the palette (grey,rainbow,viridis,plasma,magma,inferno) int rev : reverse the order of palette colours (1=YES,0-NO) RETURN VALUE: 0 on success, -1 on error (invalid palette) result array will hold statistics message array will hold explanatory text (if any) SAMPLE CALL: #define N 100 int ii; float red[N],green[N],blue[N]; xf_palette7(red,green,blue,N,"rainbow"); for(ii=0;ii<N;ii++)printf("%g\t%g\t%g\n",red[ii]),green[ii],blue[ii],0); TO BUILD EXTRA PALLETES USING R 1. in R, print a list of 7 hex values spanning the range library(viridis) viridis(7,option="inferno") 2. copy this into a list, removing internal quotes.. eg. list='#440154FF #443A83FF #31688EFF #21908CFF #35B779FF #8FD744FF' 3. build a code snippet for i in $list ; do xs-hex2rgb $i ; done | awk 'BEGIN{n=-1} {for(i=1;i<=NF;i++) { printf("ct[%d]=%s; ",++n,$i); } printf("\n")}' <TAGS> programming LDAS </TAGS>
DESCRIPTION: Convert a character string containing a list of positive numbers and/or ranges into an array of numbers Preserves input order Will not remove redundant entries Will not work with negative numbers Sample acceptable list formats: 1,2,5,6,10 1,3,5,7-20 10-1,11,14,20-25 USES: Build a list of columns to extract from a table DEPENDENCY TREE: No dependencies ARGUMENTS: char *line : character array holding list char *delimiters : delimiters (quoted) for each item in the list long min : minimum accepted value long max : maximum accepted value long *nitems : number of items in resulting list (pass as address to variable) char *message : holds error message RETURN VALUE: pointer to the list array, or NULL on error value for nitems will be overwritten SAMPLE CALLS: char line[1000],message[1000]; long *list=NULL,i,n; sprintf(line,"1,2,3,4,5"); list= xf_parselist1_l(line,",",1,999,&n,message); if(list==NULL) {fprintf(stderr,"\b\n\t--- Error [%s] %s\n\n",thisprog,message); exit(1); } for(i=0;i<n;i++) printf("%ld\n",list[i]); free(list);
DESCRIPTION: pause until a key is pressed
DESCRIPTION: Calculate percentile cutoffs for a distribution of double values USES: Getting the median, finding outliers in a distribution DEPENDENCIES: xf_compare1_d ARGUMENTS: double *data : array holding the input data long nn : number of elements in the array double *result: a minimum 16-element array to hold the percentile results result[0] : 1st percentile result[1] : 2.5th percentile result[2] : 5th percentile result[3] : 10th percentile result[4] : 25th percentile result[5] : 50th percentile (median) result[6] : 75th percentile result[7] : 90th percentile result[8] : 95th percentile result[9] : 97.5th percentile result[10] : 99th percentile RETURN VALUE: 0 if successful, -1 if fail SAMPLE CALL: if ( xf_percentile1_d(data,n,result) >=0) median=result[5]; else { fprintf(stderr,"** Memory allocation error\n"); exit(1); }
DESCRIPTION: Calculate percentile cutoffs for a distribution of double values USES: Getting the median, finding outliers in a distribution DEPENDENCIES: xf_compare1_d ARGUMENTS: float *data : array holding the input data long nn : number of elements in the array double *result: a minimum 16-element array to hold the percentile results result[0] : 1st percentile result[1] : 2.5th percentile result[2] : 5th percentile result[3] : 10th percentile result[4] : 25th percentile result[5] : 50th percentile (median) result[6] : 75th percentile result[7] : 90th percentile result[8] : 95th percentile result[9] : 97.5th percentile result[10] : 99th percentile RETURN VALUE: 0 if successful, -1 if fail SAMPLE CALL: if ( xf_percentile1_d(data,n,result) >=0) median=result[5]; else { fprintf(stderr,"--- Error: Memory allocation error\n"); exit(1); }
DESCRIPTION: Calculate a percentile cutoff for an array of double-precision float values USES: Getting the median, finding outliers in a distribution DEPENDENCIES: xf_compare1_d ARGUMENTS: double *data : array holding the input data long nn : number of elements in the array double setper : the percentile cutoff desired (0-1) char *message : pre-allocated array to hold error message RETURN VALUE: 0 if successful, -1 if fail SAMPLE CALL: if ( xf_percentile1_d(data,n,result) >=0) median=result[5]; else { fprintf(stderr,"** Memory allocation error\n"); exit(1); }
DESCRIPTION: Calculate a percentile cutoff for an array of float values USES: Getting the median, finding outliers in a distribution DEPENDENCIES: xf_compare1_f ARGUMENTS: float *data : array holding the input data long nn : number of elements in the array double setper : the percentile cutoff desired (0-1) char *message : pre-allocated array to hold error message RETURN VALUE: 0 if successful, -1 if fail SAMPLE CALL: if ( xf_percentile1_d(data,n,result) >=0) median=result[5]; else { fprintf(stderr,"** Memory allocation error\n"); exit(1); }
DESCRIPTION: Calculate spatial-information-content for place-fields - uses the adaptive binning methods described in Langston et al. 2010 (adapted from Skaggs & McNaughton,1998) - expand radius of binning until: radius * dwell * sqrt(events) >= alpha - oddly, in the literture this is expressed as: radius >= alpha / ( dwell * sqrt(events) ) - alpha is a constant, which varies from publication (10^3 for Skaggs, 10^5 for Langston & O'Keefe) Pi = probability of being n bin i, = dwell (samples) in bin i divided by total dwell samples Ri = firing rate in bin i, = event/dwell R = mean firing rate = (event total) / (dwell total) - information content (how well does cell firing predict location - high info = small fields) = SUM {Pi*(Ri/R) log2*(Ri/R)} NOTE: log2(x) = log(x)/log(2) USES: DEPENDENCIES: none ARGUMENTS: double *dwell : position-sample-count array double *event : event-count array long width : width of array long height : height of array long radmax : maximum radius for adaptive binning (-1= auto, 0= central bin only) long alpha : constant used to limit adaptive binning (typically 10^3 to 10^6, depending on the original binning or smoothing of the data) long *result_l : array to hold outputs - should point to 8-element array char *message : pre-allocated array to hold error message RETURN VALUE: - spatial information content, or NAN on error - char array will hold message (if any) - result array will hold statistics result_l[0]= total dwell samples result_l[1]= total events result_l[2]= total non-zero dwell samples result_l[3]= radius limit (radmax) result_l[4]= largest radius used in adaptive binning (radbig) SAMPLE CALL:
DESCRIPTION: Calculate statistics on cell firing rate map pattern... Pi = probability of being n bin i, = dwell time in bin i divided by trial length Ri = firing rate in bin i R = mean firing rate over entire trial - cohererence of place cell firing (how well does one bin rate predict the neighbouring bin rate) coherence = z-transform of correlation between binrates and the mean of surrounding binrates, - sparsity is roughly equivalent to the proportion of the environment the cell is likely to be active in = (SUM{Pi*Ri})^2 * SUM(Pi*Ri^2) - information content (how well does cell firing predict location - high info = small fields) = SUM {Pi*(Ri/R) log2*(Ri/R)} NOTE: log2(x) = log(x)/log(2) USES: DEPENDENCIES: long xf_stats3_d(double *data, long n, int varcalc, double *result_in); double xf_correlate_simple_d(double *x, double *y, long nn, double *result_in); int xf_percentile1_d(double *data, long n, double *result); ARGUMENTS: double *dwell : dwelltime array (make sure unvisited pixels are zero, not NAN) double *rate : firing rate array long width : width of array long height : height of array double dwelltot : total duration of time in all "valid" bins double *result_out : array to hold outputs - should point to 32-element array char *message : pre-allocated array to hold error message RETURN VALUE: - total good dwell & rate values, or -1 on error - char array will hold message (if any) - result array will hold statistics result_out[0]= maxrate; result_out[1]= meanrate; result_out[2]= baserate; // 10th percentile result_out[3]= medianrate; // 50th percentile result_out[4]= peakrate; // 97.5th percentile = midpoint of 95th percentile result_out[5]= sdrate; result_out[6]= info_content; result_out[7]= sparsity; result_out[8]= coherence; SAMPLE CALL:
DESCRIPTION: Calculate the amplitude of a frequency component in a signal, using the Goertzel algorithm Return a power estimate for a single window - this is essentially a DFT for the specified frequency - real-valued input is assumed - data should be interpolated to remove non-numeric values, NAN or INF http://en.wikipedia.org/wiki/Goertzel_algorithm http://netwerkt.wordpress.com/2011/08/25/goertzel-filter/ Note that rather than the magnitude of the signal, this function calculates the amplitude - hence the results reflect the original amplitude of the input signal - each power magnitude is adjusted by (2.0/nwin) and the square-root is taken USES: - Fast detection of a frequency in a signal DEPENDENCY TREE: No dependencies ARGUMENTS: double *input : data array to be filtered, fixed sample rate is assumed size_t nn : size of the data array (number of samples) double sample_freq : sample frequency (Hz) double freq : frequency of interest (Hz) RETURN VALUE: success: 0 failure: -1
DESCRIPTION: Calculate the amplitude of a frequency component in a signal, using the Goertzel algorithm - this is essentially a DFT for the specified frequency - real-valued input is assumed - a window slides along the data one sample at a time - a Hann taper is applied to each window - performed as if zero-padding were applied to each end of the input - note that no padding is actually required http://en.wikipedia.org/wiki/Goertzel_algorithm Note: data should be interpolated to remove non-numberic values, NAN or INF Note: that rather than the magnitude of the signal, this function calculates the amplitude - hence the results reflect the original amplitude of the input signal - each power magnitude is adjusted by (0.5/nwin) and the sqare-root is taken USES: - Fast detection of the energy envelope of a signal for phase-amplitude coupling - Detection of a frequency in a signal DEPENDENCY TREE: No dependencies ARGUMENTS: float *input : data array to be filtered, fixed sample rate is assumed float *power : data array to hold results (calling function must reserve memory) size_t nn : size of input and power arrays (number of samples) float sample_freq : sample frequency (Hz) float freq : frequency of interest (Hz) size_t nwin : size of the window used to integrate (typically 5*sample_freq/freq - i.e. 5 wavelengths) char *message : message indicating success or reason for failure RETURN VALUE: success: 0 failure: -1
DESCRIPTION: Calculate the amplitude of a frequency component in a signal, using the Goertzel algorithm Output a power estimate for every input data point - this is essentially a DFT for the specified frequency - real-valued input is assumed - data should be interpolated to remove non-numberic values, NAN or INF - performed as if zero-padding were applied to each end of the input - note that no padding is actually required http://en.wikipedia.org/wiki/Goertzel_algorithm Note that rather than the magnitude of the signal, this function calculates the amplitude - hence the results reflect the original amplitude of the input signal - each power magnitude is adjusted by (2.0/nwin) and the square-root is taken USES: - Fast detection of the energy envelope of a signal for phase-amplitude coupling - Detection of a frequency in a signal DEPENDENCY TREE: No dependencies ARGUMENTS: double *input : data array to be filtered, fixed sample rate is assumed double *power : data array to hold results (calling function must reserve memory) size_t nn : size of input and power arrays (number of samples) double sample_freq : sample frequency (Hz) double freq : frequency of interest (Hz) size_t nwin : size of the window used to integrate (typically 5/freq - i.e. 5 wavelengths) int dotaper : apply a Hann taper (0=no, 1=yes) char *message : message indicating success or reason for failure RETURN VALUE: success: 0 failure: -1
DESCRIPTION: Calculate the amplitude of a frequency component in a signal, using the Goertzel algorithm Output a power estimate for every input data point - this is essentially a DFT for the specified frequency - real-valued input is assumed - a window slides along the data one sample at a time - a Hann taper is applied to each window - performed as if zero-padding were applied to each end of the input - note that no padding is actually required http://en.wikipedia.org/wiki/Goertzel_algorithm Note: data should be interpolated to remove non-numberic values, NAN or INF Note: that rather than the magnitude of the signal, this function calculates the amplitude - hence the results reflect the original amplitude of the input signal - each power magnitude is adjusted by (2.0/nwin) and the square-root is taken USES: - Fast detection of the energy envelope of a signal for phase-amplitude coupling - Detection of a frequency in a signal DEPENDENCY TREE: No dependencies ARGUMENTS: float *input : data array to be filtered, fixed sample rate is assumed float *power : data array to hold results (calling function must reserve memory) size_t nn : size of input and power arrays (number of samples) float sample_freq : sample frequency (Hz) float freq : frequency of interest (Hz) size_t nwin : size of the window used to integrate (typically 5*sample_freq/freq - i.e. 5 wavelengths) char *message : message indicating success or reason for failure RETURN VALUE: success: 0 failure: -1
DESCRIPTION: Return the decimal precision of a number as written in characters DEPENDENCY TREE: No dependencies ARGUMENTS: char *number : [input] character string representing the number RETURN VALUE: The number of significant digits after the decimal, for example.... number precision 100 0 1.123 3 1.12340 4 SAMPLE CALL: int precision; double data=100.1234500; precision= xf_precision_d(data);
DESCRIPTION: Return the decimal precision of a number - bear in mind some numbers cannot be accurately represented in float/double - hence accurately calculating precision of some numbers will fail - for this reason the "max" argument allows the user to limit the search for zeros DEPENDENCY TREE: No dependencies ARGUMENTS: double number : [input] double-precision floating-point number to be analyzed int max : [1-12] the maximum number of decimal places to consider - 8 recommended - might need to be lower for large numbers - 12 is the absolute maximum RETURN VALUE: The number of significant digits after the decimal, for example.... number precision 100 0 1.123 3 1.12340 4 SAMPLE CALL: int precision; double data=100.1234500; precision= xf_precision_d(data,8);
DESCRIPTION: F-test function: Calculate F-distribution probability given F,df1, and df2 Based on betai function from... NUMERICAL RECIPES IN C: THE ART OF SCIENTIFIC COMPUTING (2nd Edition) William H. Press, Saul A. Teukolsky, William T. Vetterling, & Brian P. Flannery. Cambridge University Press, 1992.
DESCRIPTION: Sort an array of long integers using a quick-sort algorithm Modifies the input data array This function also modifies an array of indices so the user can know the original position of the sorted numbers USES: rearranging data in numerical order DEPENDENCY TREE: No dependencies ARGUMENTS: double *data: array holding the data long *index: array of numbers representing the original order of the data, typically 0 to (n-1) long n: size of the array RETURN VALUE: None NOTE! - behaviour for non-numeric values, Inf and Nan is not specified - arrays with only one element will be unaltered
DESCRIPTION: Sort an array of long integers using a quick-sort algorithm Modifies the input data array This function also modifies an array of indices so the user can know the original position of the sorted numbers USES: rearranging data in numerical order DEPENDENCY TREE: No dependencies ARGUMENTS: float *data: array holding the data long *index: array of numbers representing the original order of the data, typically 0 to (n-1) long n: size of the array RETURN VALUE: None NOTE! - behaviour for non-numeric values, Inf and Nan is not specified - arrays with only one element will be unaltered
DESCRIPTION: Sort an array of long integers using a quick-sort algorithm Modifies the input data array This function also modifies an array of indices so the user can know the original position of the sorted numbers USES: rearranging data in numerical order DEPENDENCY TREE: No dependencies ARGUMENTS: int *data: array holding the data long *index: array of numbers representing the original order of the data, typically 0 to (n-1) long n: size of the array RETURN VALUE: None NOTE! - behaviour for non-numeric values, Inf and Nan is not specified - arrays with only one element will be unaltered
DESCRIPTION: Sort an array of long integers using a quick-sort algorithm Modifies the input data array This function also modifies an array of indices so the user can know the original position of the sorted numbers USES: rearranging data in numerical order DEPENDENCY TREE: No dependencies ARGUMENTS: long *data: array holding the data long *index: array of numbers representing the original order of the data, typically 0 to (n-1) long n: size of the array RETURN VALUE: None NOTE! - behaviour for non-numeric values, Inf and Nan is not specified - arrays with only one element will be unaltered
DESCRIPTION: Sort an array of short integers using a quick-sort algorithm Modifies the input data array This function also modifies an array of indices so the user can know the original position of the sorted numbers USES: rearranging data in numerical order DEPENDENCY TREE: No dependencies ARGUMENTS: float *data: array holding the data long *index: array of numbers representing the original order of the data, typically 0 to (n-1) long n: size of the array RETURN VALUE: None NOTE! - behaviour for non-numeric values, Inf and Nan is not specified - arrays with only one element will be unaltered
DESCRIPTION: Calculate a double-precision random number from zero to [setmax] - calls function random(), which returns a float, normalized by RAND_MAX (unsigned long int) - a correction is made if setmax > RAND_MAX Note that the calling function should set the random seed if more than one call is to be made on a given date This is necessary to avoid producng the same random sequency multiple times USES: Many DEPENDENCY TREE: No dependencies ARGUMENTS: double setmax : largest possible value desired RETURN VALUE: The random number SAMPLE CALL: #include <stdlib.h> #include <stdio.h> #include <time.h> // needed for time() function #include <unistd.h> // needed for getpid() function double xf_rand1_d(double setmax); int main (int argc, char *argv[]) { // set the random seed using the current time and process-ID srand(time(NULL) + getpid()); // generate 10 random numbers from zero to 100 for(int i=0;ii++) printf("%d: %f\n",i,xf_rand1f(100.0)); }
DESCRIPTION: Read simple binary stream into memory from a file, converting to double This version accepts a pointer to the input stream - suitable for repeat calls On each call: - calling function designates the destination array - a temporary void buffer is allocated to hold the read results - a pointer of the appropriate data-type is pointed at the buffer - the void buffer is copied, via the pointer, to the destination array, casting each number as a double NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin2_v That function allows the system to determine the obtimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes *double data1 : pointer to pre-allocated array for final, converted version of the data off_t parameters : parameters defining input and output parameters[0] = data type (0-9) uchar,char,udouble,double,uint,int,ulong,long,double,double parameters[1] = size of each datum (bytes) parameters[2] = number of values to be read parameters[3] = number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: no data read 1: data read parameters[3] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: setdatatype=0; // unsigned char datasize=sizeof(unsigned char); ntoread=1000; // define amount of data to be read on each call bytestoread=(size_t)(0.5 + (ntoread*datasize)); buffer=(void *)malloc(bytestoread); // allocate memory data=(double *)malloc(ntoread*sizeof(double)); // allocate memory parameters[0]= setdatatype; parameters[1]= datasize; parameters[2]= ntoread; parameters[3]= 0; while(!feof(fpin)) { x= xf_readbin1_d(fpin,buffer,data,parameters,message); if(xɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } else if(parameters[3]==0)break; else for(ii=0;ii<parameters[3];ii++) printf("%g\n",data[ii]); }
DESCRIPTION: Read simple binary stream into memory from a file, converting to float This version accepts a pointer to the input stream - suitable for repeat calls On each call: - calling function designates the destination array - a temporary void buffer is allocated to hold the read results - a pointer of the appropriate data-type is pointed at the buffer - the void buffer is copied, via the pointer, to the destination array, casting each number as a float NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin2_v That function allows the system to determine the obtimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes *float data1 : pointer to pre-allocated array for final, converted version of the data off_t parameters : parameters defining input and output parameters[0] = data type (0-9) uchar,char,ufloat,float,uint,int,ulong,long,float,double parameters[1] = size of each datum (bytes) parameters[2] = number of values to be read parameters[3] = number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: no data read 1: data read parameters[3] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: setdatatype=0; // unsigned char datasize=sizeof(unsigned char); ntoread=1000; // define amount of data to be read on each call bytestoread=(size_t)(0.5 + (ntoread*datasize)); buffer=(void *)malloc(bytestoread); // allocate memory data=(float *)malloc(ntoread*sizeof(float)); // allocate memory parameters[0]= setdatatype; parameters[1]= datasize; parameters[2]= ntoread; parameters[3]= 0; while(!feof(fpin)) { x= xf_readbin1_f(fpin,buffer,data,parameters,message); if(xɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } else if(parameters[3]==0)break; else for(ii=0;ii<parameters[3];ii++) printf("%g\n",data[ii]); }
DESCRIPTION: Read simple binary stream into memory from a file, converting to int This version accepts a pointer to the input stream - suitable for repeat calls On each call: - calling function designates the destination array - a temporary void buffer is allocated to hold the read results - a pointer of the appropriate data-type is pointed at the buffer - the void buffer is copied, via the pointer, to the destination array, casting each number as a int NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin2_v That function allows the system to determine the obtimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes *int data1 : pointer to pre-allocated array for final, converted version of the data off_t parameters : parameters defining input and output parameters[0] = data type (0-9) uchar,char,uint,int,uint,int,ulong,long,int,double parameters[1] = size of each datum (bytes) parameters[2] = number of values to be read parameters[3] = number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: no data read 1: data read parameters[3] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: setdatatype=0; // unsigned char datasize=sizeof(unsigned char); ntoread=1000; // define amount of data to be read on each call bytestoread=(size_t)(0.5 + (ntoread*datasize)); buffer=(void *)malloc(bytestoread); // allocate memory data=(int *)malloc(ntoread*sizeof(int)); // allocate memory parameters[0]= setdatatype; parameters[1]= datasize; parameters[2]= ntoread; parameters[3]= 0; while(!feof(fpin)) { x= xf_readbin1_i(fpin,buffer,data,parameters,message); if(xɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } else if(parameters[3]==0)break; else for(ii=0;ii<parameters[3];ii++) printf("%d\n",data[ii]); }
DESCRIPTION: Read simple binary stream into memory from a file, converting to long This version accepts a pointer to the input stream - suitable for repeat calls On each call: - calling function designates the destination array - a temporary void buffer is allocated to hold the read results - a pointer of the appropriate data-type is pointed at the buffer - the void buffer is copied, via the pointer, to the destination array, casting each number as a long NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin2_v That function allows the system to determine the obtimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes *long data1 : pointer to pre-allocated array for final, converted version of the data off_t parameters : parameters defining input and output parameters[0] = data type (0-9) uchar,char,ulong,long,uint,int,ulong,long,long,double parameters[1] = size of each datum (bytes) parameters[2] = number of values to be read parameters[3] = number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: no data read 1: data read parameters[3] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: setdatatype=0; // unsigned char datasize=sizeof(unsigned char); ntoread=1000; // define amount of data to be read on each call bytestoread=(size_t)(0.5 + (ntoread*datasize)); buffer=(void *)malloc(bytestoread); // allocate memory data=(long *)malloc(ntoread*sizeof(long)); // allocate memory parameters[0]= setdatatype; parameters[1]= datasize; parameters[2]= ntoread; parameters[3]= 0; while(!feof(fpin)) { x= xf_readbin1_l(fpin,buffer,data,parameters,message); if(xɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } else if(parameters[3]==0)break; else for(ii=0;ii<parameters[3];ii++) printf("%g\n",data[ii]); }
DESCRIPTION: Read simple binary stream into memory from a file, converting to short This version accepts a pointer to the input stream - suitable for repeat calls On each call: - calling function designates the destination array - a temporary void buffer is allocated to hold the read results - a pointer of the appropriate data-type is pointed at the buffer - the void buffer is copied, via the pointer, to the destination array, casting each number as a short NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin2_v That function allows the system to determine the obtimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes *short data1 : pointer to pre-allocated array for final, converted version of the data off_t parameters : parameters defining input and output parameters[0] = data type (0-9) uchar,char,ushort,short,uint,int,ulong,long,short,double parameters[1] = size of each datum (bytes) parameters[2] = number of values to be read parameters[3] = number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: no data read 1: data read parameters[3] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: setdatatype=0; // unsigned char datasize=sizeof(unsigned char); ntoread=1000; // define amount of data to be read on each call bytestoread=(size_t)(0.5 + (ntoread*datasize)); buffer=(void *)malloc(bytestoread); // allocate memory data=(short *)malloc(ntoread*sizeof(short)); // allocate memory parameters[0]= setdatatype; parameters[1]= datasize; parameters[2]= ntoread; parameters[3]= 0; while(!feof(fpin)) { x= xf_readbin1_s(fpin,buffer,data,parameters,message); if(xɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } else if(parameters[3]==0)break; else for(ii=0;ii<parameters[3];ii++) printf("%g\n",data[ii]); }
DESCRIPTION: Read simple binary stream into memory from a file This version accepts a pointer to the input stream - suitable for repeat calls and stdin On each call: - calling function passes a pointer to a pre-allocated void buffer, which holds the input - a pointer of the appropriate data-type is then pointed at the buffer - parameters[2] reports the number of data read NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin2_v That function allows the system to determine the optimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes off_t parameters : parameters defining input and output parameters[0] = size of each datum (bytes) parameters[1] = number of values to be read parameters[2] = output, number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: success parameters[2] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: void *buffer=NULL; // storage for data from each call unsigned short *data=NULL; // pointer to buffer assuming input is ushort off_t datasize=sizeof(unsigned int); // size of each datum in bytes off_t blocksize=1000; // define amount of data to be read on each call if((buffer=(void *)realloc(buffer,(blocksize*datasize)))==NULL) {fprintf(stderr,"\n--- Error[%s]: insufficient memory\n\n",thisprog);exit(1);}; params[0]=datasize params[1]=blocksize; while(!feof(fpin)) { x= xf_readbin1_v(fpin,buffer,params,message); if(xɘ) {fprintf(stderr,"\n*** %s/%s\n\n",thisprog,message); exit(1);} nread=params[2]; if(nread==0) break; data=(unsigned short *)buffer; for(ii=0;ii<nread;ii++) printf("%hu\n",data[ii]); }
DESCRIPTION: Read simple binary file into memory, converting to float fseeko is used to determine memory requirements, so DO NOT USE WITH STDIN This version handles file-opening and conversion to float internally If you want flexibility in what the data is converted to, use xf_readbin1_v instead USES: DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file off_t *parameters : pointer to an array of parameters defining behaviour (see below) char *message : an array to hold diagnostic messages on return parameters[0] = data type (0-9) uchar,char,ushort,short,uint,int,ulong,long,float.double parameters[1] = number of bytes at the top of the file (header) to ignore parameters[2] = number of numbers to skip (bytes skipped calculated based on size of data type) parameters[3] = number of numbers to be read - if set to zero, function attempts to read all bytes after header and skipped numbers - if set to zero, will be reset to the number of numbers read before the function finishes RETURN VALUE: pointer to float array holding numbers, or NULL on error SAMPLE CALL:
DESCRIPTION: Read simple binary stream into memory from a file, converting to int This version accepts a pointer to the input stream - suitable for repeat calls On each call: - calling function designates the destination array - a temporary void buffer is allocated to hold the read results - a pointer of the appropriate data-type is pointed at the buffer - the void buffer is copied, via the pointer, to the destination array, casting each number as a int NOTE: To read an entire file with one function call, (~5 times faster), use xf_readbin1_v That function allows the system to determine the obtimal block read size However, because it also requires pre-determining the size of the input, it is not suitable for reading from piped streams USES: Reading a binary input stream of unknown size in chunks Suitable for reading binary input from stdin DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file - assumes stream has already been successfully opened and error-checked *void buffer : pointer to pre-allocated array for temporary storage of bytes *int data1 : pointer to pre-allocated array for final, converted version of the data off_t parameters : parameters defining input and output parameters[0] = data type (0-9) uchar,char,uint,int,uint,int,ulong,long,int,double parameters[1] = size of each datum (bytes) parameters[2] = number of values to be read parameters[3] = number of values actually read (overwritten by this function) char *message : pointer to character string which is written to IF an error is encountered RETURN VALUE: -1: error 0: no data read 1: data read parameters[3] will hold the actual number of data points read this may be less than parameters[1] (ntoread) if this is the last block of data read from the file SAMPLE CALL: setdatatype=0; // unsigned char datasize=sizeof(unsigned char); ntoread=1000; // define amount of data to be read on each call bytestoread=(size_t)(0.5 + (ntoread*datasize)); buffer=(void *)malloc(bytestoread); // allocate memory data=(int *)malloc(ntoread*sizeof(int)); // allocate memory parameters[0]= setdatatype; parameters[1]= datasize; parameters[2]= bytestoread; parameters[3]= 0; while(!feof(fpin)) { x= xf_readbin1_i(fpin,buffer,data,parameters,message); if(xɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } else if(parameters[3]==0)break; else for(ii=0;ii<parameters[3];ii++) printf("%g\n",data[ii]); }
DESCRIPTION: Fast-read a binary stream into memory from a file (NOT SUITABLE FOR STDIN) USES: DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file void **data : pointer to void which will be assigned memory for bytes of data size_t startbyte : zero-offset position at which to start reading (eg. to skip a 500-byte header, set to 500) size_t bytestoread : number of bytes to read (if set to zero, will read all) char *message : an array to hold diagnostic messages on return RETURN VALUE: number of bytes read, or 0 on failure ( error recorded in message[] ) SAMPLE CALL: -------------------------------------------------------------------------------- #include <stdio.h> #include <stdlib.h> char infile[256]; char message[256]; void *data=NULL; size_t ii,nn; fpin=fopen(infile,"r"); nn = xf_readbin2_v(fpin,&data,0,0,message); fclose(fpin); for(ii=0;ii<nn;ii++) printf("%ld %g\n",ii,data[ii]); free(data)
DESCRIPTION: [ 23 June 2015: JRH ] Read a flat binary file into memory in one or more blocks (fast!) (NOT SUITABLE FOR STDIN) Handles file-opening internally - for chunk-wise reading of data, use xf_readbin1_* - for internal conversion from one format to another, use xf_readbin2_* DEPENDENCY TREE: No dependencies ARGUMENTS: char *infile : name of file to read off_t *params : binary read parameters array params[0] = datasize, size of data type (bytes) - for multichannel data consider using nchans*sizeof(type) params[1] = headerbytes, number of bytes at the top of the file to ignore params[2] = nblocks, number of blocks of data to read (set to 0 to read the entire file) params[3] = output, total values read, set by this function off_t *start : array of [nblocks], start-record-numbers marking the beginning of each read-block off_t *toread : array of [nblocks], block-sizes (number of records in each block, if 0, read to file end) char *message : an array to hold diagnostic messages on return RETURN VALUE: no errors: pointer to array holding numbers, needs to be cast by calling function params[3] overwritten by total nnumber of records read error: NULL NOTES - Any error for any block will invalidate the entire result - UNDEFINED PARTIAL-FILE-READS UNSUPPORTED - fseeko is used to determine memory requirements- DO NOT USE WITH STDIN - *start and *toread are converted internally to bytes, according to [datasize] - *start and *toread must be initialized by the calling function to hold at least one value - If no errors are reported, the total number of values read will be the sum of *toread - If nblocks (params[2]) = 0, nblocks becomes 1 start[0] becomes 0 toread[0] becomes the (filesize-headerbytes)/datasize - Blocks are allowed to overlap, and any block can be set to read any part of the file - that is, every block-read begins with a seek to the start of the file SAMPLE CALL: READ 3 BLOCKS OF BINARY FLOAT DATA char message[256], infile="data.bin"; int datasize=sizeof(float); long ii, nn=0, nblocks=3, headersize=0, start[3]={0,100,200}, nrecords[3]={12,12,12}; long params[4]={datasize,headersize,nblocks,nn} void *datvoid=NULL; float *datfloat=NULL; datvoid= xf_readbin3_v(infile,params,start,nrecords,message); if(datvoid==NULL) { fprintf(stderr,"\n\t--- Error[%s/%s]\n\n",thisprog,message); exit(1); } if(nnə) {fprintf(stderr,"\n\t--- Error [%s]: .club file %s is empty\n",thisprog,clufile);exit(1);} nn=params[3]; pfloat=(float *)datvoid; for(ii=0;ii<nn;ii++) printf("%f\n",pfloat[ii]);
DESCRIPTION: Read BINX format binary input from a file or stdin BINX format: 1. 500-byte header in 3 parts - the header is generated only once a. Filetype b. Parameters c. Text description 2. The data, all of one type Because any data-type may be read, calling function should define pointers to all types for potential use USES: DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream/file void **data : pointer to void which will be assigned memory for bytes of data long *params : an array of the file parameters obtained from othe file header params[0] : header-size NOTE: calling function should initialize to 0 on first call to indicate to THIS function that the header still needs to be read NOTE: initializing to 1 will result only a summary of the header being output params[1] : data-size - i.e. the number of bytes in each datum (1,2,4 or 8) params[2] : data-type (0-9 = uchar,char,ushort,short,uint,int,ulong,long,float,double) params[3] : depth of dimension-1 - if data is 1-dimensional, this is also the total data-points params[4] : depth of dimension-2 params[5] : depth of dimension-3 char *message : an array to hold diagnostic messages on return RETURN VALUE: (unsigned long) number of data points read, or 0 on error SAMPLE CALL: -------------------------------------------------------------------------------- char infile[256]; char message[256]; void *data0=NULL; float *data1=NULL; unsigned long i,j,k,n,m,params[6]; FILE *fpin sprintf(infile,"myfile.dat"); // read the data fpin=fopen(infile,"r"); params[0] = -1; n = xf_readbinx1(fpin,&data0,params,message); fclose(fpin); // set up some aliases for easy reading - lets say we know the data is 2-dimensional unsigned long datatype = params[2]; unsigned long ndim1 = params[3]; unsigned long ndim2 = params[4]; // set appropriate pointer , convert data0 to float short *p3; int *p5; long *p7; if(datatype==3) { p3 = data0; for(i=0;i<n;i++) data1[i]=(float)p3[i]; } // short if(datatype==5) { p5 = data0; for(i=0;i<n;i++) data1[i]=(float)p5[i]; } // int if(datatype==7) { p7 = data0; for(i=0;i<n;i++) data1[i]=(float)p7[i]; } // long // outut the data and the column (i) and row (j) labels for(i=j=k=0;i<n;i++) { printf("%d\t%d\t%g\n",j,k,data1[i]); if(++j == ndim1) { j=0; if(++k ==ndim2) k=0; } } // free the memory free(data0) free(data1) READ THE HEADER in 3 parts (FILETYPE,PARAMS,DESCRIPTION) if it hasn't already been read!
DESCRIPTION: Read a binary cluster-timestamp file (.clubt) and its complimentary cluster-id file (.club) USES: DEPENDENCY TREE: No dependencies ARGUMENTS: char *infile1: file containing long-int (64-bit) timestamps char *infile2: file containing short-int (16-bit) cluster-IDs long **clubt: unallocated pointer for tinmestamp array, passed by calling function as &clubt short **club: unallocated pointer for cluster-ID array, passed by calling function as &club char *message: character array to hold messages, error-related or otherwise. RETURN VALUE: The number of cluster records read -1 on failure SAMPLE CALL: #include <stdio.h> #include <stdlib.h> #include <string.h> #define thisprog "test the function" int main (int argc, char *argv[]) { char message[1000],infile1[256],infile2[256]; long *clubt=NULL,ii,nn; short *club=NULL; sprintf(infile1,argv[1]); sprintf(infile2,argv[2]); nn = xf_readclub1(infile1,infile2,&clubt,&club,message); if(nn==-1) { fprintf(stderr,"\n\t--- Error: %s\n\n",message); exit(1); } for(ii=0;ii<nn;ii++) printf("%ld\t%d\n",clubt[ii],club[ii]); exit(0); }
DESCRIPTION: Read Neuralynx CSC (.ncs) files into memory - continuously sampled data DEPENDENCIES: neuralynx.h ARGUMENTS: char *infile : name of the input file float eegscale : user-defined multiplier for data - can be negative to "flip" data float *result : pre-allocated array to hold results - must allow at least 4 elements char *message : pre-allocated array to hold error message RETURN VALUE: success: - pointer to a float array of the data values on success - results array will be filled as follows: result[0]= (float) recordtot : number of EEG records result[1]= (float) validsamps : number of EEG samples per record result[2]= (float) eegtot : number of EEG samples result[3]= (float) samprate : EEG record sampling rate - accounts for number of valid samples per record error: - NULL - message array will hold explanatory text (if any) SAMPLE CALL: x= xf_auc1_d(data, nn, interval, result, ); if(x!=0) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } <TAGS> file NLX</TAGS>
DESCRIPTION: Read a SCORE binary file containing continuously sampled data (EEG, LFP) Data is stored as unsigned characters 35-byte header + 4000 bytes of data (unsigned char) Type Content Bytes Comment char name[9] 9 char date[9] 9 char time[9] 9 char channel 1 char epoch_length 1 char sample_rate 1 char artefact_def 1 char score 1 char EMG 1 short temp 2 USES: DEPENDENCY TREE: No dependencies ARGUMENTS: char *infile : name of the file to read unsigned char **data : pointer for an unsigned character array initialized to *data=NULL, and passed as &data int headers : output headers to stdout (0=NO, 1=YES) char *message : character array to hold messages, error-related or otherwise. RETURN VALUE: The number of data-point read for each of the channels - multiply by nchans to get the total data read Zero on failure SAMPLE CALL: char message[1000], infile[256]; int nchans=4; size_t n; unsigned char *data1=NULL; sprintf(infile,"mydata.txt"); n = xf_readscore1_s(infile,&data1,0,message);
DESCRIPTION: Read a binary SCORE record (RAW file format) containing a header and continuously sampled 8-bit data (EEG, LFP) Assumes data is stored as unsigned characters This version reads a single SCORE raw record, storing but not processing the header and the data USES: DEPENDENCY TREE: No dependencies ARGUMENTS: FILE *fpin : pointer to input stream char *header : pre-allocated array to hold the block header size_t nheader : number of bytes (characters) in the header (typically 35) unsigned char *data : pre-allocated array to hold the block data size_t ndata : number of data bytes to read (sample-frequency x numbers-in-record x 1) char *message : character array to hold messages, error-related or otherwise. RETURN VALUE: 0: success -1: failure SAMPLE CALL: char message[1000], header[35], infile[256]; int samplefreq=400, duration=10, ndata=samplefreq*duration; while(!feof(fpin)) { x= xf_readscore_raw1(fpin,header,nheader,data,ndata,data,message); if(xɘ) {fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1);) }
DESCRIPTION: Read a binary Start-Stop-Pair file (.ssp) or equivalent stdin Data is stored as long integers (64-bit) USES: DEPENDENCY TREE: No dependencies ARGUMENTS: char *infile: name of the file to read long **start: unallocated pointer for start array passed by calling function as &start long **stop: unallocated pointer for stop array passed by calling function as &start char *message: character array to hold messages, error-related or otherwise. RETURN VALUE: The number of start-stop pairs read -1 on failure 0 if input was empty SAMPLE CALL: #include <stdio.h> #include <stdlib.h> #include <string.h> #include <math.h> #define thisprog "test-function" char message[1000],*infile; long *start=NULL,*stop=NULL long ii,nn; infile="mydata.txt\0"; nn = xf_readscore1_s(infile,&start,&stop,0,message); if(nn==-1) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } for(ii=0;ii<nn;ii++) printf("%ld\t%ld\n",start[ii],stop[ii]);
DESCRIPTION: - Read .wfm files (multi-channel spike waveform means for clustered data) - updated: 6.February.2017 [JRH] - assumes file has header something like this... PROBE 0 N_CHANNELS 16 CHANNEL_LIST 7,10,6,8,4,11,5,9,3,12,1,14,2,13,0,15 SAMPLES_PER_CHANNEL 40 SAMPLES_PRE_PEAK 8 SAMPLE_RATE 19531.25 WAVES_START - ...with one row per cluster to follow... id count v[1] v[2] v[3] v[4] ... v[n] - ... where n= N_CHANNELS x SAMPLES_PER_CHANNEL, and the order is defined by CHANNEL_LIST DEPENDENCY TREE: No dependencies ARGUMENTS: char *infile : input, name of .wfm file to read short **id : output, pointer to array for cluster-ids for each waveform long **count : output, pointer to array for spike-counts for each waveform long **data : output, pointer to array for actual waveforms short **chanlist: output, pointer to array for order of channels in waveform long *result_l : output, array to hold statistics related to the data char *message : output, a string array to hold the status message RETURN VALUE: on success: the sample-rate (Hz) as read from the header on failure: -1 - also... - data[] will be assigned memory and filled with mean multi-channel waveforms - count[] will record the number of orignal waveforms contributing to the mean - id[] will hold the cluster-id for each waveform - chanlist[] will hold, in depth-order, the original channels contributing to the waveforms - result_l[] will hold information on the data result_l[0]= total waveforms read result_l[1]= number of channels contributing to each compound waveform result_l[2]= the number of samples corresponding to the waveform on a single channel result_l[3]= the number of samples preceding the peak result_l[4]= the total samples in the multi-channel waveform result_l[5]= largest cluster-number result_l[6]= the probe-number SAMPLE CALL: short *cluid=NULL,*chanlist=NULL; long *count=NULL,result_l[16]; float *data=NULL; samprate= xf_readwave1_f(filename,&cluid,&count,&data,&chanlist,result_l,message); if(samprateɘ) { fprintf(stderr,"\n\t--- %s/%s\n\n",thisprog,message); exit(1); } for(ii=0;ii<result_l[0];ii++) printf("cluster[%ld]= %ld\n",ii,cluid[ii]); free(data);free(id);free(count);free(chanlist);
DESCRIPTION: - Read WinLTP files (.PO or .APO) containing sweeps for slice electrophysiology DEPENDENCIES: long *xf_lineparse1(char *line,long *nwords); ARGUMENTS: char *setinfile : input, name of the file to read char *setchan : input, name of channel to read (typically AD0 or AD1) float **data1 : output, dynamically allocated array to hold data - calling function passes &data1 to this function double *result_d : output, array of info related to the file char *message : output, a string array to hold the status message RETURN VALUE: on success: nsamples, = the number of samples read for the channel on failure: -1 - data1[] will be assigned memory and filled [nsamples] datapoints - result_d[] will hold information on the data result_d[0]= sample-interval (ms) result_d[1]= sample-rate (Hz) result_d[2]= duration of pre-stimulus baseline (ms) SAMPLE CALL:
DESCRIPTION: Read a binary position-timestamp file (.xydt) and its complementary x-y-direction triplet file (.xyd) USES: DEPENDENCY TREE: No dependencies ARGUMENTS: char *infile1: file containing long-int (64-bit) timestamps char *infile2: file containing floating-point (32-bit) position data in triplets (x,y,direction) long **post: unallocated pointer for the timestamp array, passed by calling function as &post long **posx: unallocated pointer for the x-position array, passed by calling function as &posx long **posy: unallocated pointer for the y-position array, passed by calling function as &posy long **posd: unallocated pointer for the direction array, passed by calling function as &posd char *message: character array to hold messages, error-related or otherwise. RETURN VALUE: The number of posx-posy-posd triplets read -1 on failure SAMPLE CALL: #include <stdio.h> #include <stdlib.h> #include <string.h> #define thisprog "test the function" int main (int argc, char *argv[]) { char message[1000],infile1[256],infile2[256]; long *post=NULL,ii,nn; float *posx=NULL,*posy=NULL,*posd=NULL; sprintf(infile1,argv[1]); sprintf(infile2,argv[2]); nn = xf_readxydt(infile1,infile2,&posx,&posy,&posd,message); if(nn==-1) { fprintf(stderr,"\n\t--- Error: %s\n\n",message); exit(1); } for(ii=0;ii<nn;ii++) printf("%ld\t%f\t%f\t%f\n",posxt[ii],posx[ii],posy[ii],posd[ii]); exit(0); }
DESCRIPTION: Resample a series of numbers so there are a user-defined number of elements [setn] If actual n < setn, data is split as required If acctual n> setn, data is binned and averaged accordingly Alters input array NAN values will be ignored, but INF will affect the results USES: - binning an array of number - modifying different series of data so they are all the same length - making an irregular matrix of data have rowa all the same length DEPENDENCY TREE: No dependencies ARGUMENTS: double *data: input, array of numbers to be resampled long n: input, number of elements in data long setn: input, the new number of elements requested for data RETURN VALUE: Pointer to modified data array - NULL if n < setn and memory allocation error occurs SAMPLE CALL: TO DO: - consider using a Gaussian kernal for resampling
DESCRIPTION: Resample a series of numbers so there are a user-defined number of elements [setn] If actual n < setn, data is split as required If acctual n> setn, data is binned and averaged accordingly Alters input array NAN values will be ignored, but INF will affect the results USES: - binning an array of number - modifying different series of data so they are all the same length - making an irregular matrix of data have rowa all the same length DEPENDENCY TREE: No dependencies ARGUMENTS: double *data: input, array of numbers to be resampled long n: input, number of elements in data long setn: input, the new number of elements requested for data RETURN VALUE: Pointer to modified data array - NULL if n < setn and memory allocation error occurs SAMPLE CALL: TO DO: - consider using a Gaussian kernal for resampling