howto.c

Go to the documentation of this file.

puts("Reading titan volumes using rtitan2");
puts("===================================");
puts("");
puts("");
puts("Quick start ");
puts("-----------");
puts("");
puts("Let's suppose that the data disk is mounted on /mnt/osiris. It contains");
puts("continuous recording from an Osiris family data logger (Osiris, Kephren");
puts("etc.). The steps described below apply in exactly the same way if ");
puts("/mnt/osiris is the target directory of the FTP client running in the");
puts("data logger.");
puts("The file 'timelist' contains the list of times to extract:");
puts("YYYY/MM/DD-HH.MM.SS duration");
puts("...");
puts("To build SAC files for each line of timelist, run:");
puts("rtitan2 -sac -tl timelist -disk /mnt/osiris");
puts("That's all. Each .info file contains information about the associated");
puts("SAC file, including timing accuracy estimation.");
puts("");
puts("If the GPS was running on duty cycle, with a sleep time of one hour, a");
puts("free clock drift of 0.3ppm may lead to a 1ms time error. This is not a");
puts("problem if the time drift is interpolated. To use the complete time");
puts("information contained in the data files before extraction, run the");
puts("following commands:");
puts("rtitan2 -time -disk /mnt/osiris");
puts("This will create one or more .dt and .flt files in the current");
puts("directory. These files can now be used for time drift interpolation,");
puts("just run this command in the same working directory (be sure no SAC");
puts("file is in that directory before):");
puts("rtitan2 -sac -tl timelist -disk /mnt/osiris");
puts("The .info files created now refer to the .dt or .flt file used to");
puts("compute the time drift interpolation.");
puts("");
puts("");
puts("Some advices:");
puts("- if the sampling rate is 500Hz or more with a non continuously running");
puts("  GPS, perform a time pass before the data pass;");
puts("- if possible, do not work on single files, prefer using -disk with a");
puts("  timespec option (rtitan2 proposes a wide range of possibilities to");
puts("  define that);");
puts("- try to keep the directory structure when moving or transporting the");
puts("  data;");
puts("- do not work in the data directory structure.");
puts("");
puts("");
puts("Osiris family vs. Titan timing hardware");
puts("-------------------------------------------");
puts("");
puts("Users of Titan family data loggers may use to process data taking into");
puts("account the 'station time reset/reboot' and 'time shift cycling at +/-");
puts("30 seconds'. Using the Osiris and Kephren hardware, the time shift");
puts("cycling does not occur any more since the external time reference is");
puts("absolute. For Osiris and Kephren, it is normal to observe a time shift");
puts("larger than 30s or smaller than -30s. The 'station time reset/reboot'");
puts("events should not be observed as long as the internal battery of the");
puts("data logger is not empty and the power cable is plugged: the internal");
puts("clock is continuously powered by the internal battery, even if the main");
puts("power source fails (for a reasonable time, however). Please report to");
puts("the Osiris and Kephren user manual for details.");
puts("");
puts("");
puts("Titan time correction");
puts("---------------------");
puts("");
puts("The timing process in the Agecodagis digitizers is based on the");
puts("recording of the occurrence of external time pulses generated by a GPS");
puts("receiver or any other time source (DCF, TeleCode...).");
puts("The digitizer clock used to measure the occurrence is based on a TCXO");
puts("crystal that should have a drift not larger than a few ppm.");
puts("When the absolute time of the samples needs to be known, the delay");
puts("between the external time pulse and the internal digitizer clock must be");
puts("estimated and removed from the uncorrected time.");
puts("The external time pulses are expected at the absolute second 0 of each");
puts("minute. The Titan digitizers are not able to absolutely date the time");
puts("pulses, consequently, the time shift between the internal clock and the");
puts("absolute time will always be less than 30 seconds.");
puts("Osiris and Kephren stations on the contrary use the full NMEA data flow");
puts("and thus provide an absolute time for each time pulse.");
puts("This difference explains the processing difference proposed further.");
puts("");
puts("* dft, flt, and dt files:");
puts("When the absolute time of the first sample of a data segment is");
puts("computed, rtitan2 first looks for a dft file in the current directory");
puts("that matches the station processed. If no dft file can be found, rtitan2");
puts("tries to find a flt file with the same criteria (station and time), and");
puts("then, if a flt file does not match, rtitan2 tries a dt file.");
puts("Finally, if dft/flt/dt file can be found, the closest time pulses are");
puts("used to correct the data. A linear interpolation is performed to get the");
puts("time correction to apply. If the linear interpolation cannot be");
puts("performed, the closest time pulse is used.");
puts("The dft/dt files are named according to the first time pulse of the");
puts("file and the station name.");
puts("");
puts("extra_tcorr:");
puts("For compatibility with existing tools, a file named extra_tcorr may be");
puts("used for extra time correction. The file is open in the working");
puts("directory, the format is:");
puts("================================");
puts("drift_file_name1 delta1");
puts("drift_file_name2 delta2");
puts("#comment");
puts("drift_file_name3 delta3");
puts("...");
puts("================================");
puts("drift_file_name is the name of a drift file (dft, flt, or dt). delta is");
puts("the time, in seconds _added_ to correct the start time of the data files");
puts("that have used drift_file_name for the time correction. This is used");
puts("mainly for Titan1 data with delta=+/-N*60.0");
puts("");
puts("FrameSkip:");
puts("For Titan1 only if the FrameSkip bug occurs and should be corrected. The");
puts("file is named FrameSkip.station. station is the station name (use -sta).");
puts("The format of the file is:");
puts("================================");
puts("date1 shift1");
puts("date2 shift2");
puts("#comment");
puts("date3 shift3");
puts("...");
puts("================================");
puts("date1<date2<date3");
puts("shift1 applies from date1, shift2 applies from date2 etc. The shift is");
puts("the error to correct from, thus, -shift is added to the start time of");
puts("the file.");
puts("");
puts("");
puts("Single pass processing");
puts("----------------------");
puts("");
puts("This is recommended for Osiris and Kephren data with continuous GPS or");
puts("low sampling rates.");
puts("");
puts("Just run the data extraction command on the data input. The time");
puts("correction applied on the beginning of the data segment will be based on");
puts("the closest external time pulse (unless a matching dft/dt file lies in");
puts("the current directory).");
puts("");
puts("");
puts("Simple two-pass processing with filtering");
puts("-----------------------------------------");
puts("");
puts("This is recommended for Osiris and Kephren data when the maximum");
puts("time accuracy must be reached.");
puts("");
puts("The first pass is performed with the '-time' option.");
puts("This pass creates .dt and .flt files containing the occurences of the");
puts("external time pulses (several dt/flt pairs of files may be created if a");
puts("time reset occurs). The 'flt' file is a filtered version of the 'dt'");
puts("file.");
puts("The data extraction performed in the same directory will use the flt");
puts("files in order to interpolate the time correction to apply to the data.");
puts("Note that SAC format stores the times down to the ms only.");
puts("");
puts("");
puts("Two-pass processing with filtering/cleaning/smoothing");
puts("-----------------------------------------------------");
puts("");
puts("This is recommended for Titan and Titan-based Mykerinos/SAGE-PC data");
puts("");
puts("The process is the same as the simple two-pass but after the first pass,");
puts("the dt or flt file is edited/smoothed/filtered with a third party");
puts("program such as xdft in order to add missing pulses or remove the wrong");
puts("ones. The new file should be named dft so that it will get a higher");
puts("priority during the second pass.");
puts("");
puts("");
puts("Station log analysis");
puts("--------------------");
puts("");
puts("The station log is extracted from the Titan stream using the '-log'");
puts("option. The log is sent to the standard output, it can be sent to a file");
puts("using a simple redirection:");
puts("");
puts("rtitan2 -log -disk /disk/data > station.log");
puts("");
puts("The output is a text file that can be easily used with any plotting");
puts("software such as gnuplot:");
puts("");
puts("gnuplot> plot '< grep Vbatt station.log' using 2:5 title 'Vbatt'");
puts("");
puts("Field 2 is the raw time and field 5 is the Vbatt value.");
puts("To use a human readable time, use timefmt:");
puts("");
puts("gnuplot> set timefmt '%Y.%m.%d-%H.%M.%S'");
puts("gnuplot> set xdata time");
puts("gnuplot> plot '< grep Vbatt station.log' using 1:5 title 'Vbatt'");
puts("");
puts("");
puts("Output formats");
puts("--------------");
puts("");
puts("rtitan2 is able to write the data streams in various commonly used");
puts("formats: ");
puts("-asc: human and machine readable format; the fixed length header");
puts(" provide the necessary information to identify and date the seismogram;");
puts(" the signal immediately follows the header;");
puts("-sac: SAC format");
puts("-segy: PASSCAL SEGY files (one trace per file).");
puts("-gif: a single GIF file is generated for each time segment");
puts("-wav: wav (Microsoft WAVE format), the frequency is multiplied by ~176");
puts(" and rounded to the closest multiple of 2000 or 22500Hz.");
puts("-mseed: MiniSeed format, header-less.");
puts("-seg2: SEG-2 format.");
puts("-sis: SISMALP format (signed 32bits)");
puts("");
puts("Output data files are named according to the time of the first sample.");
puts("For each data file written, an information file is created and described the");
puts("content of the data file (station name, sampling rate, time corrections");
puts("etc.).");
puts("");
puts("");
puts("Notes about MiniSeed output");
puts("---------------------------");
puts("");
puts("rtitan2 generates header-less SEED data. Data files include only");
puts("blockettes 1000 and 1001. Refer to rdseed documentation to prepend a");
puts("dataless header to build a SEED volume.");
puts("The signal is stored as 32bits integers without compression, or using");
puts("the Steim1 compression (default). rtitan2 tries to interpolate the time");
puts("drift for each block. If the interpolation is not possible (no file");
puts("available), a warning is issued and the observed shift is used.");
puts("");
puts("");
puts("Channel selection (Titan2 data only)");
puts("------------------------------------");
puts("The channels can be selected using a channel list: i,j,k-l means");
puts("channels i, j and k to l (including k and l). Rtitan2 also accepts to");
puts("check channel names against a stream list: stream1,stream2,... The list");
puts("is coma separated. Inclusive streams are ore'd and streams are evaluated");
puts("in the order of the command line. Examples:");
puts("name    stream list             matches ?");
puts("SHZ     HH?,SH?,BH?             yes");
puts("SHZ     !SHZ                    no");
puts("SHZ     !SHZ,SH?                yes");
puts("SHZ     SH?,!SHZ                no");
puts("");
puts("");
puts("Cache management");
puts("----------------");
puts("");
puts("rtitan2 uses a cache to quickly seek far positions in data inputs.");
puts("When the cache cannot be used, finding a date in a huge data input can");
puts("be very long. When running on a disk or day directory, rtitan2 uses the");
puts("file names to quickly find the required date and time. When running on a");
puts("single huge file or multiple files given with -f, rtitan2 builds a cache");
puts("file when started for the first time and then uses this cache file for");
puts("data extractions. The default cache directory is ~/.titancache");
puts("Note that the cache is not built during data extraction. A first pass");
puts("without data extraction at all or with time shift extraction only should");
puts("be performed:");
puts("rtitan2 [-log] [-time] -f huge_files...");
puts("");
puts("");
puts("Trigger pass");
puts("------------");
puts("");
puts("rtitan2 is able to perform a sta/lta trigger over the data. The");
puts("parameters for the trigger are controlled by the -trig option.");
puts("Data can be low pass and high pass filtered before the trigger. A");
puts("trigger file generated to stdout (unless o= suboption is used). It");
puts("indicates everything about the event (time duration etc.). Using the e=");
puts("suboption, an event file compatible with the -tl option is also");
puts("generated. Thus, after replacing a storage disk in the field, a quick");
puts("analysis of the events recorded by the station can be performed with the");
puts("following commands:");
puts("");
puts("#extract the trigger based on channel 0:");
puts("rtitan2 -chan 0 -trig,e=evtfile,t=5,m=3,s=2 -disk /data/field/disk1");
puts("");
puts("#generate gif images based on the trigger:");
puts("rtitan2 -gif -tl evtfile -disk /data/field/disk1");
puts("");
puts("");
puts("Titan1 data processing");
puts("----------------------");
puts("");
puts("rtitan2 is able to read and process titan1 data.");
puts("Titan1 data are processed just as titan2. rtitan2 includes some basic");
puts("functions for the extraction of usefull data out of a titan1 disk");
puts("containig the siz/ndx/dat files.");
puts("The following command will read the 'data' file and dump the usefull");
puts("data according to the content of 'size.siz' and send the extracted data");
puts("to 'segment.tit':");
puts("rtitan2 -size size.siz -data data.dat > segment.tit");
puts("Note that '-size' must be given _before_ '-data'.");
puts("");
puts("");
puts("In case of data corruption");
puts("--------------------------");
puts("");
puts("When the Titan/Titan2 disk is corrupted and time appears to be non-");
puts("monotonous, rtitan2 does not extract some events when used with -tl.");
puts("");
puts("The local cache must be used:");
puts("0/ remove any local cache in the working directory:");
puts("        rm .LocalTitanCache");
puts("1/ perform a first pass with -localcache");
puts("        rtitan2 -localcache -f /path/to/file1 /path/to/file2");
puts("   (try to use absolute path names)");
puts("2/ perform the data extraction with -localcache");
puts("   rtitan2 -localcache [options] -f /path/to/file1 /path/to/file2");
puts("");
puts("Note that in the case of corrupted disks or files, -sta and -n may be");
puts("usefull.");
puts("");
puts("");
puts("Download and install Titan2Reader");
puts("---------------------------------");
puts("");
puts("The Titan2Reader package can be obtained on the Agecodagis main page, in");
puts("the \"Support and Download/Firmware and software updates\" section. Binary");
puts("linux versions (rpm and static), binary .exe for DOS/Windows and full");
puts("source archive with documentation are available.");
puts("The public CVS server provides the most up-to-date code. The following");
puts("commands can be used to download the code from the CVS server:");
puts("$ cvs -z3 -d:pserver:cvs@agecodagis.com:/home/cvsroot/Ageco login");
puts("press enter on the password prompt.");
puts("$ cvs -z3 -d:pserver:cvs@agecodagis.com:/home/cvsroot/Ageco co Titan2Reader");
puts("");
puts("Any further update from the CVS server is performed by running the");
puts("following command in the Titan2Reader directory:");
puts("$ cvs update");

---