:orphan: .. _ahelp_@grayplot: ********* @grayplot ********* .. contents:: :local: | .. code-block:: none Usage: @grayplot [OPTIONS] dirname Script to read files from an afni_proc.py results directory and produce a grayplot from the errts dataset(s), combined with a motion magnitude indicator graph. * NOTE: This script requires various programs from the NETPBM packege to run. If those programs are not found, this script will fail. Will produce a plot for each dataset whose name fits the wildcard *errts.*+tlrc.HEAD including errts.SUBJECT+tlrc and errts.SUBJECT_REML+tlrc, if both datasets were computed. Dataset errts.SUBJECT_REMLwh+tlrc will also be plotted, if option '-regress_opts_reml -Rwherr errts.SUBJECT_REMLwh' was given to afni_proc.py -- this is the 'pre-whitened' residuals dataset, which is the noise examplar from which the 3dREMLfit statistics are computed. * NOTE: dataset all_runs.*+tlrc.HEAD will also be grayplotted if it is found in the results directory. * NOTE: this script will now work with +orig datasets if the +tlrc datasets are not available [11 Aug 2018]. The output images are grayscale, stored in .png format, and have names like 'Grayplot.errts.WHATEVER.ORDERMETH.png'. * See the OPTIONS section below for the ordering methods of the voxels in the output. Note that time points which were censored out will have errts=0 (and thus look flat), and the motion magnitude graph will be set to 0 at these points as well -- to avoid having large motions dominate the graph and make it hard to see other movements. Censored time points are also overlaid with a gray band in the graph above the dataset grayplot. (Gray so that the resulting png file is pure grayscale -- without color.) Segments the anatomy (or uses an existing segmentation, if it was run by afni_proc.py), and grayplots the GM, WM, and CSF voxels separately from top to bottom, with dashed lines dividing the partitions. COMMAND LINE ARGUMENTS: * The last argument is the afni_proc.py results directory. To use the current working directory, use '.' as the last argument. * The only OPTIONS at this time control the ordering of the voxel (time series)graphs inside each mask partition in the grayplot, downward in the image: -pvorder = Within each partition, voxels are ordered by a simple similarity measure, so the top of each partition will echo have voxel time series that are more similar than the bottom of the partition. This ordering helps make it clear if there are many time series with similar temporal patterns, which will show up as vertical bands in the grayplot. * Note that '-pvorder' is based on the data, so the voxel order in the grayplot will differ between datasets in the same directory, unlike the geometrically-based orderings '-peelorder' and '-ijkorder'. * I personally like '-pvorder' for the clarity provided by having similar voxel time series clustered together. -peelorder = Within each partition, voxels are ordered by how many 'peel' operations are needed to reach a given voxel; that is, how far a voxel is from the partition's boundary. Voxels at the edge of the partition are first, etc. -ijkorder = Within each partition, voxels are just ordered by the 3D index in which they appear in the dataset. Possibly not exciting. This order will primarily be from Inferior to Superior in the brain (top to bottom in the grayplot image), using AFNI's convention for storing +tlrc datasets. -ALLorder = Create grayplots for all ordering methods. Can be useful for comparisons, but of course will take a little longer to run. **** Only one of these options can be given; if you give more options, then the script will become confused and not work. **** The default (no option given) order is '-ijkorder'. NOTA BENE: * Also see '3dGrayplot -help', since the actual grayplot is created by that program. * Since the vertical (spatial) dimension of the output grayplot image is only 1200 pixels, each horizontal (time) row in the plot will be the combination of multiple voxels, in whatever order they appear. * Since the horizontal dimension of the output grayplot image is 1800 pixels, unless the time series has more than 1800 points, each time point will be stretched (interpolated) to fill more than one pixel. * I personally find '-pvorder' to be the most useful, but the other orderings can also be interesting to compare. * I like to use the AFNI 'aiv' program to view the images, rather than a standard image viewer program, since aiv's default settings show more contrast, which helps me see more structure in the grayplots. * Note that 'structure' in the grayplots of the errts datasets is in some sense BAD, since individual-subject statistics are computed from the errts dataset assuming it is just noise. * I prefer using 3dREMLfit and so the most relevant grayplot is from errts.SUBJECT_REMLwh+tlrc (the pre-whitened errts.SUBJECT_REML+tlrc). The voxelwise pre-whitening tends to removes a little of the visible structure in the grayplot. * Author: RWCox -- May 2018 * Notice: Subject to horrific and drastic change at any instant. * Changes since original version: a) Revised 3dGrayplot and @grayplot to plot data with a fixed range, so the images from different datasets can be compared.