Sam cov - Revision history

Nugenta at 15:36, 5 March 2019

2019-03-05T15:36:46Z

← Older revision		Revision as of 11:36, 5 March 2019
Line 19:		Line 19:
	Other options:		Other options:

	-v ~~or --verbose :~~ verbose mode		-v verbose mode
	-h ~~or --help :~~ show help		-h show help

	Required parameters (either in the .param file or on the command line):		Required parameters (either in the .param file or on the command line):

Nugenta at 15:35, 5 March 2019

2019-03-05T15:35:39Z

← Older revision		Revision as of 11:35, 5 March 2019
Line 14:		Line 14:

	==Usage==		==Usage==
	sam_cov -r <dataset_name> -m <parameter_file_name> ~~[-v]~~ [options]		sam_cov -r <dataset_name> -m <parameter_file_name> [options]
	The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param).		The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param).

	Other options:		Other options:

	-v: verbose mode		-v or --verbose : verbose mode
	-h: show help		-h or --help : show help

			Required parameters (either in the .param file or on the command line):
	The required parameters are:

	NumMarkers: the number of markers or zero		NumMarkers: the number of markers or zero
Line 30:		Line 30:
	If NumMarkers is greater than zero, Marker1 through MarkerN should also be specified - see parameter descriptions as well as the examples below.		If NumMarkers is greater than zero, Marker1 through MarkerN should also be specified - see parameter descriptions as well as the examples below.

	Optional parameters ~~are~~:		Optional parameters:

	OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation		OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation

Nugenta at 15:34, 5 March 2019

2019-03-05T15:34:05Z

← Older revision		Revision as of 11:34, 5 March 2019
Line 15:		Line 15:
	==Usage==		==Usage==
	sam_cov -r <dataset_name> -m <parameter_file_name> [-v] [options]		sam_cov -r <dataset_name> -m <parameter_file_name> [-v] [options]
	The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param). ~~The -v option specifies verbose output, else sam_cov works silently. Many of the parameters are also available on the command line, see the output of sam_cov -h.~~		The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param).

			Other options:

			-v: verbose mode
			-h: show help

	The required parameters are:		The required parameters are:

Nugenta at 17:46, 4 March 2019

2019-03-04T17:46:13Z

← Older revision		Revision as of 13:46, 4 March 2019
Line 1:		Line 1:
	~~Return to~~ [[Source Localization - SAM \| Source Localization - SAM]]		[[Source Localization - SAM \| Return to Source Localization - SAM]]

	==Description==		==Description==

Nugenta at 17:29, 4 March 2019

2019-03-04T17:29:44Z

← Older revision		Revision as of 13:29, 4 March 2019
Line 1:		Line 1:
			Return to [[Source Localization - SAM \| Source Localization - SAM]]
	=sam_cov=

	==Description==		==Description==

Nugenta at 17:08, 4 March 2019

2019-03-04T17:08:45Z

← Older revision		Revision as of 13:08, 4 March 2019
Line 27:		Line 27:
	Optional parameters are:		Optional parameters are:

	OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation. This defaults to CovBand if OrientBand is not given. It is suggested that orientation is determined by a frequency band for which the signal-to-noise ratio is highest (beta-band is a good choice).		OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation
	NoiseBand: high- and low-pass frequencies for estimating the SQUID sensor noise ~~(must be far above frequencies where MEG signals are significant).~~		NoiseBand: high- and low-pass frequencies for estimating the SQUID sensor noise
	DataSegment: override the start and end times of all the markers.		DataSegment: override the start and end times of all the markers

	The rules are:
			The OrientBand defaults to CovBand if OrientBand is not given. It is suggested that orientation is determined by a frequency band for which the signal-to-noise ratio is highest (beta-band is a good choice). If NoiseBand is specified, it should be far above frequencies where MEG signals are significant.

			==Output Files==

	A Global.cov file is always generated, by default, regardless of the number of markers or other parameters.		A Global.cov file is always generated, by default, regardless of the number of markers or other parameters.
Line 40:		Line 43:
	Marker2 9r1 -.25 .25 FALSE		Marker2 9r1 -.25 .25 FALSE
	Marker3 9r2 -.25 .25 TRUE		Marker3 9r2 -.25 .25 TRUE

	sam_cov will generate Global.cov, 9r0.cov, 9r1.cov, 9r2.cov, and Sum.cov. The Sum.cov includes only markers that are flagged as TRUE.		sam_cov will generate Global.cov, 9r0.cov, 9r1.cov, 9r2.cov, and Sum.cov. The Sum.cov includes only markers that are flagged as TRUE.

	An Orient.cov file is always written, using the frequency bandpass specfied by CovBand, unless OrientBand is specified.		An Orient.cov file is always written, using the frequency bandpass specfied by CovBand, unless OrientBand is specified.

	If a noise covariance passband is designated in the parameter file, then an additional noise covariance matrix will be computed. ~~Assuming~~ ~~that~~ a ~~dataset~~ is ~~acquired~~ ~~with~~ a ~~DC–1000~~ Hz ~~bandwidth:~~		If a noise covariance passband is designated in the parameter file, then an additional noise covariance matrix will be computed. Ideally, when the bandwidth is above physiologically plausible brain signal, the Noise.cov covariance file will contain very little MEG brain signal and will be dominated by the primary SQUID sensor noise. When multiplied by the SAM beamformer coefficients, Noise.cov will yield the most accurate estimate of beamformer projected noise for any given voxel. When setting this parameter, be mindful of your sampling rate and the quarter-Nyquist filter automatically imposed by the system.

			sam_cov will also output the time segments used for calculating the covariance matrices, as well as eigenvalue spectra. Information on interpreting these files is given in the next section.
	NoiseBand 250. 300.
	generates a Noise.cov covariance file containing very little MEG brain signal and dominated by the primary SQUID sensor noise. When multiplied by the SAM beamformer coefficients, Noise.cov will yield the most accurate estimate of beamformer projected noise for any given voxel. When setting this parameter, be mindful of your sampling rate and the quarter-Nyquist filter automatically imposed by the system.

	==Diagnostics==		==Diagnostics==

Nugenta at 17:01, 4 March 2019

2019-03-04T17:01:23Z

← Older revision		Revision as of 13:01, 4 March 2019
Line 14:		Line 14:

	==Usage==		==Usage==
	sam_cov -r <dataset_name> -m <parameter_file_name> [-v] [options]		sam_cov -r <dataset_name> -m <parameter_file_name> [-v] [options]
	The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param). The -v option specifies verbose output, else sam_cov works silently. Many of the parameters are also available on the command line, see the output of sam_cov -h.		The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param). The -v option specifies verbose output, else sam_cov works silently. Many of the parameters are also available on the command line, see the output of sam_cov -h.

	The required parameters are:		The required parameters are:

	NumMarkers: the number of markers or zero		NumMarkers: the number of markers or zero
	CovBand: high- and low-pass frequencies (Hz)		CovBand: high- and low-pass frequencies (Hz)
	ImageBand: high- and low-pass frequencies (Hz) for subsequent analysis		ImageBand: high- and low-pass frequencies (Hz) for subsequent analysis

	If NumMarkers is greater than zero, Marker1 through MarkerN should also be specified - see parameter descriptions as well as the examples below.		If NumMarkers is greater than zero, Marker1 through MarkerN should also be specified - see parameter descriptions as well as the examples below.

	Optional parameters are:		Optional parameters are:

	OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation. This defaults to CovBand if OrientBand is not given. It is suggested that orientation is determined by a frequency band for which the signal-to-noise ratio is highest (beta-band is a good choice).		OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation. This defaults to CovBand if OrientBand is not given. It is suggested that orientation is determined by a frequency band for which the signal-to-noise ratio is highest (beta-band is a good choice).
	NoiseBand: high- and low-pass frequencies for estimating the SQUID sensor noise (must be far above frequencies where MEG signals are significant).		NoiseBand: high- and low-pass frequencies for estimating the SQUID sensor noise (must be far above frequencies where MEG signals are significant).
	DataSegment: override the start and end times of all the markers.		DataSegment: override the start and end times of all the markers.
Line 35:		Line 36:
	If NumMarkers is greater than zero, then a covariance file is computed for each named marker. In addition, a Sum.cov covariance file is generated by summing over the time segments for all markers flagged as TRUE. For example, assuming a parameter file containing:		If NumMarkers is greater than zero, then a covariance file is computed for each named marker. In addition, a Sum.cov covariance file is generated by summing over the time segments for all markers flagged as TRUE. For example, assuming a parameter file containing:

	NumMarkers 3		NumMarkers 3
	Marker1 9r0 -.25 .25 TRUE		Marker1 9r0 -.25 .25 TRUE
	Marker2 9r1 -.25 .25 FALSE		Marker2 9r1 -.25 .25 FALSE
	Marker3 9r2 -.25 .25 TRUE		Marker3 9r2 -.25 .25 TRUE
	sam_cov will generate Global.cov, 9r0.cov, 9r1.cov, 9r2.cov, and Sum.cov. The Sum.cov includes only markers that are flagged as TRUE.		sam_cov will generate Global.cov, 9r0.cov, 9r1.cov, 9r2.cov, and Sum.cov. The Sum.cov includes only markers that are flagged as TRUE.

	An Orient.cov file is always written, using the frequency bandpass specfied by CovBand, unless OrientBand is specified.		An Orient.cov file is always written, using the frequency bandpass specfied by CovBand, unless OrientBand is specified.
Line 45:		Line 46:
	If a noise covariance passband is designated in the parameter file, then an additional noise covariance matrix will be computed. Assuming that a dataset is acquired with a DC–1000 Hz bandwidth:		If a noise covariance passband is designated in the parameter file, then an additional noise covariance matrix will be computed. Assuming that a dataset is acquired with a DC–1000 Hz bandwidth:

	NoiseBand ~~900~~. ~~1000~~.		NoiseBand 250. 300.
	generates a Noise.cov covariance file containing very little MEG brain signal and dominated by the primary SQUID sensor noise. When multiplied by the SAM beamformer coefficients, Noise.cov will yield the most accurate estimate of beamformer projected noise for any given voxel.		generates a Noise.cov covariance file containing very little MEG brain signal and dominated by the primary SQUID sensor noise. When multiplied by the SAM beamformer coefficients, Noise.cov will yield the most accurate estimate of beamformer projected noise for any given voxel. When setting this parameter, be mindful of your sampling rate and the quarter-Nyquist filter automatically imposed by the system.

	==Diagnostics==		==Diagnostics==

Nugenta at 16:55, 4 March 2019

2019-03-04T16:55:32Z

← Older revision		Revision as of 12:55, 4 March 2019
Line 2:		Line 2:

	==Description==		==Description==
	sam_cov reads an MEG dataset and a parameter file (with the .param extension) and outputs multiple covariance files in accord with the contents of the parameter file and a set of internal rules. The parameter file is parsed for the frequency passband(s), time windows and markers (if present). It also allows for generation of an optional noise covariance file for determination of individual sensor noise levels. Beamformer weights are generated from data within the specified covariance bandpass. The covariance files are stored in a subdirectory within the SAM/ directory of the dataset. The subdirectory inherits the name of the parameter file concatenated with the covariance bandpass. For example, if the parameter file is MyTest.param and CovBand is 4–50 Hz, the subdirectory will be named MyTest,4-50Hz. The subdirectory name is not influenced by the ImageBand, OrientBand or NoiseBand frequencies. Assuming a dataset named XYZABC.ds, the covariance files will be written to the directory: XYZABC.ds/SAM/MyTest.4-50Hz. Several covariance files will be saved. The Global.cov file contains a covariance matrix defined from the entire dataset. If there are markers, there will be a covariance file for each marker (named MARKERNAME.cov), and there will be a Sum.cov covariance file which is calculated from the data surrounding all the named markers. SAMcov-Segments defines the start and endpoints in the dataset over which each covariance file was created. Eigenvalue files are also created for each named marker, which give the ranked singular values for the covariance matrix.		sam_cov reads an MEG dataset and a parameter file (with the .param extension) and outputs multiple covariance files in accord with the contents of the parameter file and a set of internal rules. The parameter file is parsed for the frequency passband(s), time windows and markers (if present). It also allows for generation of an optional noise covariance file for determination of individual sensor noise levels. Beamformer weights are generated from data within the specified covariance bandpass. The covariance files are stored in a subdirectory within the SAM/ directory of the dataset. The subdirectory inherits the name of the parameter file concatenated with the covariance bandpass. For example, if the parameter file is MyTest.param and CovBand is 4–50 Hz, the subdirectory will be named MyTest,4-50Hz. The subdirectory name is not influenced by the ImageBand, OrientBand or NoiseBand frequencies. Assuming a dataset named XYZABC.ds, the covariance files will be written to the directory: XYZABC.ds/SAM/MyTest.4-50Hz. Several covariance files will be saved. The Global.cov file contains a covariance matrix defined from the entire dataset. If there are markers, there will be a covariance file for each marker (named MARKERNAME.cov), and there will be a Sum.cov covariance file which is calculated from the data surrounding all the named markers marked 'TRUE' in the parameter file. SAMcov-Segments defines the start and endpoints in the dataset over which each covariance file was created. Eigenvalue files are also created for each named marker, which give the ranked singular values for the covariance matrix.

	Note that sam_cov creates the SAM/ subdirectory if it does not exist.		Note that sam_cov creates the SAM/ subdirectory if it does not exist.
Line 22:		Line 22:
	CovBand: high- and low-pass frequencies (Hz)		CovBand: high- and low-pass frequencies (Hz)
	ImageBand: high- and low-pass frequencies (Hz) for subsequent analysis		ImageBand: high- and low-pass frequencies (Hz) for subsequent analysis
	If NumMarkers is greater than zero, Marker1 through MarkerN ~~(where~~ N is ~~NumMarkers)~~ ~~give~~ ~~marker~~ ~~names,~~ ~~start~~ ~~and~~ ~~end~~ ~~times, a flag for inclusion/exclusion from the SUM covariance, and optionally a name for the covariance (by default the marker name is used). See~~ the examples below.		If NumMarkers is greater than zero, Marker1 through MarkerN should also be specified - see parameter descriptions as well as the examples below.

	Optional parameters are:		Optional parameters are:
Line 49:		Line 49:

	==Diagnostics==		==Diagnostics==
	sam_cov computes the eigenvalue spectrum for each covariance file it generates. The average primary sensor noise is estimated from the eigenvalue spectrum at the rank where its 1st-derivative is minimum. The effective rank and noise are printed as a diagnostic if the -v flag is used. sam_cov also computes the ratio of “effective” samples to the number of primary sensors. The effective sample rate is 2x the bandwidth. Poor beamformer performance will result if the ratio of samples to sensors is less than about 3. In practice, a ratio of 10 or more is preferred. If one or more sensors is dead or there has been preprocessing affecting the rank of the measurements, sam_cov will display an error message that the covariance is degenerate. A degenerate covariance matrix will have a least-significant eigenvalue that is much smaller than the true sensor noise.		sam_cov computes the eigenvalue spectrum for each covariance file it generates. The average primary sensor noise is estimated from the eigenvalue spectrum at the rank where its 1st-derivative is minimum. The effective rank and noise are printed as a diagnostic if the -v flag is used. sam_cov also computes the ratio of “effective” samples to the number of primary sensors. The effective sample rate is 2x the bandwidth. Poor beamformer performance will result if the ratio of samples to sensors is less than about 3. In practice, a ratio of 10 or more is preferred. If one or more sensors is dead or there has been preprocessing affecting the rank of the measurements (such as ICA), sam_cov will display an error message that the covariance is degenerate. A degenerate covariance matrix will have a least-significant eigenvalue that is much smaller than the true sensor noise. If you know what you are doing, this can be overcome by using a pseudo-inverse (see the Pinv param) and regularization. A text listing of the eigenvalue spectrum for each covariance matrix will be found in the same subdirectory as the covariance files. In addition, the samples parsed for each time segment are found in the SAMcov-Segments file. These files may be useful for diagnosing defective datasets or poorly selected parameters.

	A text listing of the eigenvalue spectrum for each covariance matrix will be found in the same subdirectory as the covariance files. In addition, the samples parsed for each time segment are found in the SAMcov-Segments file. These files may be useful for diagnosing defective datasets or poorly selected parameters.

Nugenta: Created page with "=sam_cov= ==Description== sam_cov reads an MEG dataset and a parameter file (with the .param extension) and outputs multiple covariance files in accord with the contents of t..."

2019-03-04T16:42:04Z

Created page with "=sam_cov= ==Description== sam_cov reads an MEG dataset and a parameter file (with the .param extension) and outputs multiple covariance files in accord with the contents of t..."

New page

=sam_cov=

==Description==
sam_cov reads an MEG dataset and a parameter file (with the .param extension) and outputs multiple covariance files in accord with the contents of the parameter file and a set of internal rules. The parameter file is parsed for the frequency passband(s), time windows and markers (if present). It also allows for generation of an optional noise covariance file for determination of individual sensor noise levels. Beamformer weights are generated from data within the specified covariance bandpass. The covariance files are stored in a subdirectory within the SAM/ directory of the dataset. The subdirectory inherits the name of the parameter file concatenated with the covariance bandpass. For example, if the parameter file is MyTest.param and CovBand is 4–50 Hz, the subdirectory will be named MyTest,4-50Hz. The subdirectory name is not influenced by the ImageBand, OrientBand or NoiseBand frequencies. Assuming a dataset named XYZABC.ds, the covariance files will be written to the directory: XYZABC.ds/SAM/MyTest.4-50Hz. Several covariance files will be saved. The Global.cov file contains a covariance matrix defined from the entire dataset. If there are markers, there will be a covariance file for each marker (named MARKERNAME.cov), and there will be a Sum.cov covariance file which is calculated from the data surrounding all the named markers. SAMcov-Segments defines the start and endpoints in the dataset over which each covariance file was created. Eigenvalue files are also created for each named marker, which give the ranked singular values for the covariance matrix.

Note that sam_cov creates the SAM/ subdirectory if it does not exist.

An optional orientation passband can be specified for use by the sam_wts program. The orientation covariance file should be generated from data in a band where the signal-to-noise ratio is high (such as the beta band). The orientation covariance is computed using all data samples, under the assumption that, for any given voxel, the orientation must be stationary over time.

An optional noise covariance file may also be specified. The passband should be as high as possible, where the MEG signal is vanishingly small. The noise covariance accounts for variations in noise among sensors. This becomes important when attempting to image very high frequency activity where the image may contain artifacts due to variations in sensor noise. Without this, all sensors are assigned the average noise estimated from the covariance eigenvalue spectrum.

note: The version 3 .cov covariance files are not compatible with prior versions of SAMcov.
The optional DataSegment time window overrides the active and control time-segments for covariance generation. This option is used when either the active and control time windows are too small to obtain a useful covariance estimate, or when an imaging analysis requires lead-in and -out times such as for entropy analysis.

==Usage==
sam_cov -r <dataset_name> -m <parameter_file_name> [-v] [options]
The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param). The -v option specifies verbose output, else sam_cov works silently. Many of the parameters are also available on the command line, see the output of sam_cov -h.

The required parameters are:

NumMarkers: the number of markers or zero
CovBand: high- and low-pass frequencies (Hz)
ImageBand: high- and low-pass frequencies (Hz) for subsequent analysis
If NumMarkers is greater than zero, Marker1 through MarkerN (where N is NumMarkers) give marker names, start and end times, a flag for inclusion/exclusion from the SUM covariance, and optionally a name for the covariance (by default the marker name is used). See the examples below.

Optional parameters are:

OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation. This defaults to CovBand if OrientBand is not given. It is suggested that orientation is determined by a frequency band for which the signal-to-noise ratio is highest (beta-band is a good choice).
NoiseBand: high- and low-pass frequencies for estimating the SQUID sensor noise (must be far above frequencies where MEG signals are significant).
DataSegment: override the start and end times of all the markers.
The rules are:

A Global.cov file is always generated, by default, regardless of the number of markers or other parameters.

If NumMarkers is greater than zero, then a covariance file is computed for each named marker. In addition, a Sum.cov covariance file is generated by summing over the time segments for all markers flagged as TRUE. For example, assuming a parameter file containing:

NumMarkers 3
Marker1 9r0 -.25 .25 TRUE
Marker2 9r1 -.25 .25 FALSE
Marker3 9r2 -.25 .25 TRUE
sam_cov will generate Global.cov, 9r0.cov, 9r1.cov, 9r2.cov, and Sum.cov. The Sum.cov includes only markers that are flagged as TRUE.

An Orient.cov file is always written, using the frequency bandpass specfied by CovBand, unless OrientBand is specified.

If a noise covariance passband is designated in the parameter file, then an additional noise covariance matrix will be computed. Assuming that a dataset is acquired with a DC–1000 Hz bandwidth:

NoiseBand 900. 1000.
generates a Noise.cov covariance file containing very little MEG brain signal and dominated by the primary SQUID sensor noise. When multiplied by the SAM beamformer coefficients, Noise.cov will yield the most accurate estimate of beamformer projected noise for any given voxel.

==Diagnostics==
sam_cov computes the eigenvalue spectrum for each covariance file it generates. The average primary sensor noise is estimated from the eigenvalue spectrum at the rank where its 1st-derivative is minimum. The effective rank and noise are printed as a diagnostic if the -v flag is used. sam_cov also computes the ratio of “effective” samples to the number of primary sensors. The effective sample rate is 2x the bandwidth. Poor beamformer performance will result if the ratio of samples to sensors is less than about 3. In practice, a ratio of 10 or more is preferred. If one or more sensors is dead or there has been preprocessing affecting the rank of the measurements, sam_cov will display an error message that the covariance is degenerate. A degenerate covariance matrix will have a least-significant eigenvalue that is much smaller than the true sensor noise.

A text listing of the eigenvalue spectrum for each covariance matrix will be found in the same subdirectory as the covariance files. In addition, the samples parsed for each time segment are found in the SAMcov-Segments file. These files may be useful for diagnosing defective datasets or poorly selected parameters.