Running CAT Cosinor
Examples of calling CAT can be found on the Vignettes page, and associated instructions.
Instructions for Calling the Chronomics Analysis Toolkit (CATkit) Cosinor
After installing R and RStudio:
1. Download the Installing CATkit pdf
2. Open Installing CAT from tar with a text editor (or R)
3. Following the directions, open Vignette.r and modify it to run a vignette
4. To run the vignette, double click on Vignette.r;
or, if you have Vignette.r open in R or RStudio, you can run it by selecting shift-cmd-S; or from the Menu, select Code-->Source
5. After the program completes running, it will give you the name of the output file (in the same folder as the input was found).
Instructions for Calling the Chronomics Analysis Toolkit (CATkit) Cosinor
After installing R and RStudio:
1. Download the Installing CATkit pdf
2. Open Installing CAT from tar with a text editor (or R)
3. Following the directions, open Vignette.r and modify it to run a vignette
4. To run the vignette, double click on Vignette.r;
or, if you have Vignette.r open in R or RStudio, you can run it by selecting shift-cmd-S; or from the Menu, select Code-->Source
5. After the program completes running, it will give you the name of the output file (in the same folder as the input was found).
Parameterization
Each parameter has default values that will be used if not explicitly set. The call to CATCosinor, with defaults is:
CATCosinor (TimeCol=1,Y=2, Components=1, window="noTaper", RefDateTime=NA, timeFormat="%Y%m%d%H%M", RangeDateTime=list(Start=NA, End=NA), Units="hour", Progressive=list(Interval=0, Increment=0), Period=list(Set=0,Start=0,Increment=1,End=0),header=FALSE, Skip=0, Colors="BW",Graphics="pdf",Output=list(Txt=FALSE,Dat=TRUE, Doc=TRUE,Graphs=FALSE,bySubject=FALSE),yLabel="",Console=FALSE,Debug=FALSE,IDcol="fileName",fileName=fileName,functionName="")
TimeCol: Column number where time is found. Format of TimeCol is given by the timeFormat Parameter. Time is read to the minute. Seconds are discarded. Date and Time can be in any column, in any of three formats (seconds are discarded):
1) numeric (in number of hours from starting time);
2) a one column date/time format, where the format is specified by the parameter timeFormat; or
3) a two column format consisting of Date in the first of the 2 columns specified, and Time in the second: c(3,6); where the format is specified by the parameter timeFormat
Y: Column number of data to be analyzed. This is a numeric, either scalar or vector. May use any valid R expression, such as c(4,5) or a single number.
Components: Default=1. Indicates if this is a single or multiple component cosinor analysis, where the number of components is specified (>0). If doing a single component cosinor, set Components=1. If doing a multiple components model, set Components equal to the number of frequencies in the model.
RefDateTime: Date used as reference, and subtracted from all data dates, to make the number smaller. **Must be in the same time zone!!!!!**
if RefDateTime = NA, uses the 1st date of the data as the RefDateTime
if RefDateTime = 0, uses midnight of the same day as the data starts
timeFormat: Can be "numeric" or any valid R format. Ex: "%Y%m%d%H%M". See strptime for conversion specifications.
If timeFormat= "numeric", time column in data file can be simple numbers (0 - 99999...) in Units from a reference time.
If timeFormat= "numeric", the data it is sorted by time to be sure they are ordered ascending. First must be smallest , and last largest.
Time can also be in two columns (indicate in TimeCol Ex: c(1,2)); timeFormat is ignored when time is in two columns -- the format use is %d/%m/%y in the first of the two columns, and %H:%M:%S or %H:%M in the second of the two
RangeDateTime: specify in the form of a list: RangeDateTime=list(Start=12, End=0)
$Start: Analysis is started at this date/time. May be before 1st data date.
if Start = 0, use the Midnight at the start of the 1st date of the data as the StartDate
if Start = NA, uses the 1st data point as the StartDate
$End: Analysis ends at this date/time. May be after last data date.
if End = 0, use the midnight at the end of the last date of the data as the EndDate
if End = NA, uses the last data point as the EndDate
Units: Units (Hour, Year, Week or Day) used by Span and Increment arguments, as well as Period arguments (Note: only Hour is currently implemented.)
window: Valid windows are: "noTaper","Hanning","Hamming","Bartlett","Blackman". Defaults to "noTaper"
header: TRUE/FALSE to indicate if the file has a header. Headers are used as variable names.
Skip: How many lines to skip at the top of the file (before the header). The header will be read next, after Skip lines are skipped (if header=TRUE).
Progressive: specify in the form of a list: Progressive=list(Interval=0, Increment=0)
$Interval : length of the time span being analyzed (in Units) -- multiple spans calculated
If 0, assumes no progression, Interval is set to the full dataset length, and Increment = full data set
$Increment: number of Days, Wks or Yrs (uses same unit as set for Interval) to shift forward for each successive Interval analyses
If 0, assumes no progression, Interval is set to the full dataset length, and Increment = full data set
Period: specify in the form of a list: Period=list(Set=0,Start=0,Increment=1,End=0)
$Start : [only used if $Set=0] First (and largest) period to calculate, in units of Days, Wks or Yrs (as set by Units); (Interval/1)
0 is Default: the full time range of the data file is analyzed [in hours] (RangeDateTime$End-RangeDateTime$Start)= MyData_length; or if progressive, Interval/1;
Important: It is normally best if the user sets $Start to a multiple of the largest period of interest -- Fourier frequencies calculated will be closest to period of interest this way.
So if one is interested in a weekly period, use a multiple of 1 week as $Start
$Increment : [only used if $Set=0] Increment to starting period, in units of Days, Wks or Yrs (as set by Units)
Defaults to 1; 0 is invalid -- default will be used
$End : [only used if $Set=0] Last (and smallest) period to calculate, in units of Days, Wks or Yrs (as set by Units) EXCLUSIVE.
Defaults to 2*dt or 4; (1 is too small) 0 is invalid -- default will be used
$Set : If Set=0, a series of periods are analyzed (spectrum) according to Period$Start, $Increment, $End (or their default value, if not specified)
If not equal to 0, Overrides Period$Start and $Increment, to completely specify an exact set of periods to analyze (as set by Units).
Can be in the format of a single number, or an array: c(1,2,3) or c(8,12:24)
When Components=1, each period specified in the vector will be assessed by cosinor independently.
When parameter Components is >1, Period$Set must have a corresponding number of components, which assessed together in a multiple component cosinor.
When 0, only the maximum period, or the maximum period per Interval, from a spectrum is listed on p1 of the graphics file.
Otherwise, all periods are displayed on the graphic
Colors Colors for the heatmap. "Heat" renders the heat map in colors; "BW" renders the heatmap in grayscale
Graphics Default file output type is "pdf". The main results of CATCosinor are sent to a graphic file when Console=F. Possible values: "jpg, pdf, tiff, png".
Output Specify in the form of a list: list(Txt=F,Dat=T, Doc=T,Graphs=F).
$Txt=TRUE will capture the console output to a .txt file.
$Dat=TRUE will generate a .txt computer-readable file of tab delimited cosinor results: MESOR, Amplitude, Phase, standard error values, and others. It is useful for subsequent processing (by CAT, or excel, for example).
$Doc=TRUE will generate a nicely-formatted .rtf file, also readable by Word.
$Graphs=TRUE will enable a set of graphs plotting Data, Model, MESOR, Amplitude, Acrophase over time, or a heatmap. The exact files generated will vary with the functions performed. Heatmaps are only created when a progressive analysis of (single component) multiple frequencies is performed. $Graphs=FALSE will disable printing of graphs for faster processing, if you do not need the files.
$bySubject=TRUE is used when IDcol is a subject ID (not==filename); an additional output file is created (.txt) from the .dat file, where output is re-sorted by subject ID (from IDcol). Default is FALSE.
yLabel: Label for the Y axis on data graphs. If this is left blank (the default="") then the column headers are used for Y axis label.
dt When equidistant data, dt indicates the sampling interval. If dt =0, no periodogram is done.
Data is assumed to be equidistant when this is nonzero
Console: Default is FALSE. When Console=TRUE, output will be redirected to the RStudio Console, instead of an output file. Otherwise, sent to file type indicated in Graphics parameter.
Debug Turn on when you want to see more diagnostic output for programming debug purposes
IDcol: What to use as a unique identifier for grouping analyses: either "fileName" or a column number. Normally used to do do analysis by subject. Default = "fileName"
fileName The path to a data file to be processed. If this is blank, CATCosinor will solicit a file from the user by a dialogue box. [The path must be specified differently for Mac or PC -- see Vignette documentation.
functionName: Brief user-defined name for this run, used to help distinguish it from other runs. Name is printed in output files.
Data requirements: There is no need for data to be equidistant for the Cosinor. Data is expected to be numeric. An error will occur if non-numeric elements are in the file.
Data File format: Comma delimited file with the following columns:
[optional ID], Date-Time, y1, y2, y3, etc…
Sample output file: Sample graphics output file can be found in the Output section on the CAT web site for a sample of a full output file. All graphs contain the input data filename to clearly identify the data file under analysis, and a timestamp to show the time of analysis. Each graph also lists the column name being analyzed (or averaged), as well as the starting and ending times of analysis, as they vary slightly from the full data set.
Graphic output files can be in JPG, PDF, TIFF or PNG. TIFF and PNG are higher resolution than jpeg and PDF. Plots in PNG and JPEG formats can easily be converted to many other bitmap formats, and both can be displayed in modern web browsers. The PNG format is lossless and is best for line diagrams and blocks of color. The JPEG format is lossy, but may be useful for image plots, for example. It is most often used in html web pages. TIFF is a meta-format: the default format written by tiff is lossless and stores RGB (and alpha where appropriate) values uncompressed-such files are widely accepted, which is their main virtue over PNG.
CATCosinor (TimeCol=1,Y=2, Components=1, window="noTaper", RefDateTime=NA, timeFormat="%Y%m%d%H%M", RangeDateTime=list(Start=NA, End=NA), Units="hour", Progressive=list(Interval=0, Increment=0), Period=list(Set=0,Start=0,Increment=1,End=0),header=FALSE, Skip=0, Colors="BW",Graphics="pdf",Output=list(Txt=FALSE,Dat=TRUE, Doc=TRUE,Graphs=FALSE,bySubject=FALSE),yLabel="",Console=FALSE,Debug=FALSE,IDcol="fileName",fileName=fileName,functionName="")
TimeCol: Column number where time is found. Format of TimeCol is given by the timeFormat Parameter. Time is read to the minute. Seconds are discarded. Date and Time can be in any column, in any of three formats (seconds are discarded):
1) numeric (in number of hours from starting time);
2) a one column date/time format, where the format is specified by the parameter timeFormat; or
3) a two column format consisting of Date in the first of the 2 columns specified, and Time in the second: c(3,6); where the format is specified by the parameter timeFormat
Y: Column number of data to be analyzed. This is a numeric, either scalar or vector. May use any valid R expression, such as c(4,5) or a single number.
Components: Default=1. Indicates if this is a single or multiple component cosinor analysis, where the number of components is specified (>0). If doing a single component cosinor, set Components=1. If doing a multiple components model, set Components equal to the number of frequencies in the model.
RefDateTime: Date used as reference, and subtracted from all data dates, to make the number smaller. **Must be in the same time zone!!!!!**
if RefDateTime = NA, uses the 1st date of the data as the RefDateTime
if RefDateTime = 0, uses midnight of the same day as the data starts
timeFormat: Can be "numeric" or any valid R format. Ex: "%Y%m%d%H%M". See strptime for conversion specifications.
If timeFormat= "numeric", time column in data file can be simple numbers (0 - 99999...) in Units from a reference time.
If timeFormat= "numeric", the data it is sorted by time to be sure they are ordered ascending. First must be smallest , and last largest.
Time can also be in two columns (indicate in TimeCol Ex: c(1,2)); timeFormat is ignored when time is in two columns -- the format use is %d/%m/%y in the first of the two columns, and %H:%M:%S or %H:%M in the second of the two
RangeDateTime: specify in the form of a list: RangeDateTime=list(Start=12, End=0)
$Start: Analysis is started at this date/time. May be before 1st data date.
if Start = 0, use the Midnight at the start of the 1st date of the data as the StartDate
if Start = NA, uses the 1st data point as the StartDate
$End: Analysis ends at this date/time. May be after last data date.
if End = 0, use the midnight at the end of the last date of the data as the EndDate
if End = NA, uses the last data point as the EndDate
Units: Units (Hour, Year, Week or Day) used by Span and Increment arguments, as well as Period arguments (Note: only Hour is currently implemented.)
window: Valid windows are: "noTaper","Hanning","Hamming","Bartlett","Blackman". Defaults to "noTaper"
header: TRUE/FALSE to indicate if the file has a header. Headers are used as variable names.
Skip: How many lines to skip at the top of the file (before the header). The header will be read next, after Skip lines are skipped (if header=TRUE).
Progressive: specify in the form of a list: Progressive=list(Interval=0, Increment=0)
$Interval : length of the time span being analyzed (in Units) -- multiple spans calculated
If 0, assumes no progression, Interval is set to the full dataset length, and Increment = full data set
$Increment: number of Days, Wks or Yrs (uses same unit as set for Interval) to shift forward for each successive Interval analyses
If 0, assumes no progression, Interval is set to the full dataset length, and Increment = full data set
Period: specify in the form of a list: Period=list(Set=0,Start=0,Increment=1,End=0)
$Start : [only used if $Set=0] First (and largest) period to calculate, in units of Days, Wks or Yrs (as set by Units); (Interval/1)
0 is Default: the full time range of the data file is analyzed [in hours] (RangeDateTime$End-RangeDateTime$Start)= MyData_length; or if progressive, Interval/1;
Important: It is normally best if the user sets $Start to a multiple of the largest period of interest -- Fourier frequencies calculated will be closest to period of interest this way.
So if one is interested in a weekly period, use a multiple of 1 week as $Start
$Increment : [only used if $Set=0] Increment to starting period, in units of Days, Wks or Yrs (as set by Units)
Defaults to 1; 0 is invalid -- default will be used
$End : [only used if $Set=0] Last (and smallest) period to calculate, in units of Days, Wks or Yrs (as set by Units) EXCLUSIVE.
Defaults to 2*dt or 4; (1 is too small) 0 is invalid -- default will be used
$Set : If Set=0, a series of periods are analyzed (spectrum) according to Period$Start, $Increment, $End (or their default value, if not specified)
If not equal to 0, Overrides Period$Start and $Increment, to completely specify an exact set of periods to analyze (as set by Units).
Can be in the format of a single number, or an array: c(1,2,3) or c(8,12:24)
When Components=1, each period specified in the vector will be assessed by cosinor independently.
When parameter Components is >1, Period$Set must have a corresponding number of components, which assessed together in a multiple component cosinor.
When 0, only the maximum period, or the maximum period per Interval, from a spectrum is listed on p1 of the graphics file.
Otherwise, all periods are displayed on the graphic
Colors Colors for the heatmap. "Heat" renders the heat map in colors; "BW" renders the heatmap in grayscale
Graphics Default file output type is "pdf". The main results of CATCosinor are sent to a graphic file when Console=F. Possible values: "jpg, pdf, tiff, png".
Output Specify in the form of a list: list(Txt=F,Dat=T, Doc=T,Graphs=F).
$Txt=TRUE will capture the console output to a .txt file.
$Dat=TRUE will generate a .txt computer-readable file of tab delimited cosinor results: MESOR, Amplitude, Phase, standard error values, and others. It is useful for subsequent processing (by CAT, or excel, for example).
$Doc=TRUE will generate a nicely-formatted .rtf file, also readable by Word.
$Graphs=TRUE will enable a set of graphs plotting Data, Model, MESOR, Amplitude, Acrophase over time, or a heatmap. The exact files generated will vary with the functions performed. Heatmaps are only created when a progressive analysis of (single component) multiple frequencies is performed. $Graphs=FALSE will disable printing of graphs for faster processing, if you do not need the files.
$bySubject=TRUE is used when IDcol is a subject ID (not==filename); an additional output file is created (.txt) from the .dat file, where output is re-sorted by subject ID (from IDcol). Default is FALSE.
yLabel: Label for the Y axis on data graphs. If this is left blank (the default="") then the column headers are used for Y axis label.
dt When equidistant data, dt indicates the sampling interval. If dt =0, no periodogram is done.
Data is assumed to be equidistant when this is nonzero
Console: Default is FALSE. When Console=TRUE, output will be redirected to the RStudio Console, instead of an output file. Otherwise, sent to file type indicated in Graphics parameter.
Debug Turn on when you want to see more diagnostic output for programming debug purposes
IDcol: What to use as a unique identifier for grouping analyses: either "fileName" or a column number. Normally used to do do analysis by subject. Default = "fileName"
fileName The path to a data file to be processed. If this is blank, CATCosinor will solicit a file from the user by a dialogue box. [The path must be specified differently for Mac or PC -- see Vignette documentation.
functionName: Brief user-defined name for this run, used to help distinguish it from other runs. Name is printed in output files.
Data requirements: There is no need for data to be equidistant for the Cosinor. Data is expected to be numeric. An error will occur if non-numeric elements are in the file.
Data File format: Comma delimited file with the following columns:
[optional ID], Date-Time, y1, y2, y3, etc…
Sample output file: Sample graphics output file can be found in the Output section on the CAT web site for a sample of a full output file. All graphs contain the input data filename to clearly identify the data file under analysis, and a timestamp to show the time of analysis. Each graph also lists the column name being analyzed (or averaged), as well as the starting and ending times of analysis, as they vary slightly from the full data set.
Graphic output files can be in JPG, PDF, TIFF or PNG. TIFF and PNG are higher resolution than jpeg and PDF. Plots in PNG and JPEG formats can easily be converted to many other bitmap formats, and both can be displayed in modern web browsers. The PNG format is lossless and is best for line diagrams and blocks of color. The JPEG format is lossy, but may be useful for image plots, for example. It is most often used in html web pages. TIFF is a meta-format: the default format written by tiff is lossless and stores RGB (and alpha where appropriate) values uncompressed-such files are widely accepted, which is their main virtue over PNG.