showxcorrx
Description:
This is the newest, most avant-garde version of showxcorr. Because it’s an x file, it’s more fluid and I don’t guarantee that it will keep a stable interface (or even work at any given time). But every time I add something new, it goes here. The goal is eventually to make this the “real” version. Unlike rapidtide, however, I’ve let it drift quite a bit without syncing it because some people here actually use showxcorr and I don’t want to disrupt workflows…
Inputs:
showxcorrx requires two text files containing timecourses with the same sample rate, one timepoint per line, which are to be correlated, and the sample rate.
Outputs:
showxcorrx outputs everything to standard out, including the Pearson correlation, the maximum cross correlation, the time of maximum cross correlation, and estimates of the significance levels (if specified). There are no output files.
Usage:
Calculate and display crosscorrelation between two timeseries.
usage: showxcorrx [-h] [--samplerate FREQ | --sampletime TSTEP]
[--searchrange LAGMIN LAGMAX] [--fixdelay DELAYTIME]
[--timerange START END]
[--windowfunc {hamming,hann,blackmanharris,None}]
[--zeropadding PADVAL]
[--filterband {None,vlf,lfo,resp,cardiac,hrv_ulf,hrv_vlf,hrv_lf,hrv_hf,hrv_vhf,lfo_legacy}]
[--filterfreqs LOWERPASS UPPERPASS]
[--filterstopfreqs LOWERSTOP UPPERSTOP]
[--filtertype {trapezoidal,brickwall,butterworth}]
[--butterorder ORDER] [--padseconds SECONDS]
[--detrendorder ORDER] [--trimdata]
[--corrweighting {None,phat,liang,eckart}] [--invert]
[--label LABEL] [--partialcorr FILE] [--cepstral]
[--calccsd] [--calccoherence]
[--permutationmethod {shuffle,phaserandom}]
[--numnull NREPS] [--skipsighistfit]
[--similaritymetric {correlation,mutualinfo,hybrid}]
[--sigmamax SIGMAMAX] [--sigmamin SIGMAMIN]
[--mutualinfosmoothingtime TAU] [--outputfile FILE]
[--corroutputfile FILE] [--summarymode] [--labelline]
[--title TITLE] [--xlabel LABEL] [--ylabel LABEL]
[--legend LEGEND] [--legendloc LOC] [--color COLOR]
[--nolegend] [--noxax] [--noyax] [--linewidth LINEWIDTH]
[--tofile FILENAME] [--fontscalefac FAC] [--saveres DPI]
[--noprogressbar] [--nodisplay] [--nonorm] [--nprocs NPROCS]
[--debug] [--verbose]
infilename1 infilename2
Positional Arguments
- infilename1
Text file containing a timeseries. Select column COLNUM if multicolumn file
- infilename2
Text file containing a timeseries. Select column COLNUM if multicolumn file
General Options
- --samplerate
Set the sample rate of the data file to FREQ. If neither samplerate or sampletime is specified, sample rate is 1.0.
Default: auto
- --sampletime
Set the sample rate of the data file to 1.0/TSTEP. If neither samplerate or sampletime is specified, sample rate is 1.0.
Default: auto
- --searchrange
Limit fit to a range of lags from LAGMIN to LAGMAX. Default is -30.0 to 30.0 seconds.
Default: (-30.0, 30.0)
- --fixdelay
Don’t fit the delay time - set it to DELAYTIME seconds for all voxels.
- --timerange
Limit analysis to data between timepoints START and END in the input file. If END is set to -1, analysis will go to the last timepoint. Negative values of START will be set to 0. Default is to use all timepoints.
Default: (-1, -1)
Windowing options
- --windowfunc
Possible choices: hamming, hann, blackmanharris, None
Window function to use prior to correlation. Options are hamming, hann, blackmanharris, and None. Default is hamming
Default: “hamming”
- --zeropadding
Pad input functions to correlation with PADVAL zeros on each side. A PADVAL of 0 does circular correlations, positive values reduce edge artifacts. Set PADVAL < 0 to set automatically. Default is 0.
Default: 0
Filtering options
- --filterband
Possible choices: None, vlf, lfo, resp, cardiac, hrv_ulf, hrv_vlf, hrv_lf, hrv_hf, hrv_vhf, lfo_legacy
Filter timecourses to specific band. Use “None” to disable filtering. Default is “lfo”.
Default: “lfo”
- --filterfreqs
Filter timecourses to retain LOWERPASS to UPPERPASS. If –filterstopfreqs is not also specified, LOWERSTOP and UPPERSTOP will be calculated automatically.
- --filterstopfreqs
Filter timecourses to with stop frequencies LOWERSTOP and UPPERSTOP. LOWERSTOP must be <= LOWERPASS, UPPERSTOP must be >= UPPERPASS. Using this argument requires the use of –filterfreqs.
- --filtertype
Possible choices: trapezoidal, brickwall, butterworth
Filter timecourses using a trapezoidal FFT, brickwall FFT, or butterworth bandpass filter. Default is “trapezoidal”.
Default: “trapezoidal”
- --butterorder
Set order of butterworth filter (if used). Default is 6.
Default: 6
- --padseconds
The number of seconds of padding to add to each end of a filtered timecourse to reduce end effects. Default is 30.0.
Default: 30.0
Preprocessing options
- --detrendorder
Set order of trend removal (0 to disable, default is 1 - linear).
Default: 1
- --trimdata
Trimming data to match
Default: False
- --corrweighting
Possible choices: None, phat, liang, eckart
Method to use for cross-correlation weighting. Default is None.
Default: “None”
- --invert
Invert the second timecourse prior to calculating similarity.
Default: False
- --label
Label for the delay value.
Default: “None”
- --partialcorr
Use the columns of FILE as controlling variables and return the partial correlation.
Additional calculations
- --cepstral
Check time delay using Choudhary’s cepstral technique.
Default: False
- --calccsd
Calculate the cross-spectral density.
Default: False
- --calccoherence
Calculate the coherence.
Default: False
Similarity function options
- --similaritymetric
Possible choices: correlation, mutualinfo, hybrid
Similarity metric for finding delay values. Choices are ‘correlation’ (default), ‘mutualinfo’, and ‘hybrid’.
Default: “correlation”
- --sigmamax
Reject lag fits with linewidth wider than SIGMAMAX Hz. Default is 1000.0 Hz.
Default: 1000.0
- --sigmamin
Reject lag fits with linewidth narrower than SIGMAMIN Hz. Default is 0.25 Hz.
Default: 0.25
- --mutualinfosmoothingtime
Time constant of a temporal smoothing function to apply to the mutual information function. Default is 3.0 seconds. TAU <=0.0 disables smoothing.
Default: 3.0
Output options
- --outputfile
Save results to FILE.
- --corroutputfile
Write correlation function to FILE.
- --summarymode
Print all results on a single line.
Default: “False”
- --labelline
Print a header line identifying fields in the summary line.
Default: “False”
General plot appearance options
- --title
Use TITLE as the overall title of the graph.
Default: “”
- --xlabel
Label for the plot x axis.
Default: “”
- --ylabel
Label for the plot y axis.
Default: “”
- --legend
Legends for the timecourse.
- --legendloc
Integer from 0 to 10 inclusive specifying legend location. Legal values are: 0: best, 1: upper right, 2: upper left, 3: lower left, 4: lower right, 5: right, 6: center left, 7: center right, 8: lower center, 9: upper center, 10: center. Default is 2.
Default: 2
- --color
Color of the timecourse plot.
- --nolegend
Turn off legend label.
Default: True
- --noxax
Do not show x axis.
Default: True
- --noyax
Do not show y axis.
Default: True
- --linewidth
Linewidth (in points) for plot. Default is 1.
- --tofile
Write figure to file FILENAME instead of displaying on the screen.
- --fontscalefac
Scaling factor for annotation fonts (default is 1.0).
Default: 1.0
- --saveres
Write figure to file at DPI dots per inch (default is 1000).
Default: 1000
Miscellaneous options
- --noprogressbar
Will disable showing progress bars (helpful if stdout is going to a file).
Default: True
- --nodisplay
Do not plot the data (for noninteractive use)
Default: True
- --nonorm
Will disable normalization of the mutual information function.
Default: True
- --nprocs
Use NPROCS worker processes for multiprocessing. Setting NPROCS to less than 1 sets the number of worker processes to n_cpus - 1.
Default: 1
Debugging options
- --debug
Enable additional debugging output.
Default: False
- --verbose
Print out more debugging information
Default: False