Difference between revisions of "Geopsy: Waveform Scripting Language"

From GeopsyWiki
Jump to navigation Jump to search
 
(93 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
The scripting language is based on the ECMAScript scripting language, as defined in standard [http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-262.pdf ECMA-262]. Basic structures, variables,... are described in this document. Other references:
+
The scripting language is Javascript ([http://www.w3schools.com/js a comprehensive tutorial])
−
* [http://doc.trolltech.com/4.5/ecmascript.html A quick reference guide]
 
−
* [http://www.davidflanagan.com/javascript5 A more comprehensive tutorial] (JavaScript which is also an ECMAScript)
 
  
−
Geopsy provides several additional functions for processing signals details here below
+
Geopsy provides several additional functions for processing signals details here below. If the description is incomplete hereinafter, run the function in the graphical user interface and check the generated code in the waveform console.
  
 
== Categories ==
 
== Categories ==
 +
* Header data: [[#header|header]], [[#setHeader|setHeader]]
 +
* Signal transformations: [[#cut|cut]], [[#shift|shift]]
 +
* Input/ouput: [[#exportFile|exportFile]]
 +
* Time: [[#addSeconds|addSeconds]], [[#addDays|addDays]], [[#addMonths|addMonths]], [[#addYears|addYears]], [[#elapsedSeconds|elapsedSeconds]], [[#startTime|startTime]], [[#endTime|endTime]], [[#setStartTime|setStartTime]]
 +
* Miscelaneous: [[#signalCount|signalCount]], [[#saveStep|saveStep]], [[#restoreStep|restoreStep]]
  
 +
== addDays ==
 +
=== Syntax ===
 +
  string addDays(string '''dateTime''', integer '''days''');
 +
 +
=== Description ===
 +
From a string containing an absolute time '''dateTime''' (format: yyyyMMddhhmmssz), adds '''days''' and returns a modified absolute time. '''days''' must by an integer.
 +
=== Examples ===
 +
  print(addDays("20240829160235.540000", 1));
 +
 +
== addMonths ==
 +
=== Syntax ===
 +
  string addMonths(string '''dateTime''', integer '''months''');
 +
 +
=== Description ===
 +
From a string containing an absolute time '''dateTime''' (format: yyyyMMddhhmmssz), adds '''months''' and returns a modified absolute time. '''months''' must by an integer.
 +
=== Examples ===
 +
  print(addMonths("20240829160235.540000", 1));
 +
 +
== addSeconds ==
 +
=== Syntax ===
 +
  string addSeconds(string '''dateTime''', number '''seconds''');
  
−
== Alphabetical list ==
+
=== Description ===
 +
From a string containing an absolute time '''dateTime''' (format: yyyyMMddhhmmssz), adds '''seconds''' and returns a modified absolute time.
 +
=== Examples ===
 +
  print(addSeconds("20240829160235.540000", 86401.06));
  
−
== save ==
+
== addYears ==
 
=== Syntax ===
 
=== Syntax ===
−
   save(string tag);
+
   string addYears(string '''dateTime''', integer '''years''']]]);
 +
 
 
=== Description ===
 
=== Description ===
−
Saves the current signals onto the stack under '''tag'''. '''tag''' is an arbitrary string used to [[#restore|restore()]] previously saved signals.
+
From a string containing an absolute time '''dateTime''' (format: yyyyMMddhhmmssz), adds '''years''' and returns a modified absolute time. '''years''' must by an integer.
−
This function is systematically produced when using the [[Geopsy:Waveform Menu|waveform menu]] items.  
 
 
=== Examples ===
 
=== Examples ===
−
   filter();
+
   print(addYears("20240829160235.540000", 1));
−
  save("Low pass 10 Hz");
+
 
−
  whiten();
+
== agc ==
−
  save("Whiten");
+
 
−
  restore("Low pass 10 Hz");
+
== correlations ==
−
  clipStddev();
+
 
 +
== cut ==
 +
=== Syntax ===
 +
cut( [[Geopsy: Time range specification]] );
 +
=== Description ===
 +
Cut the signal between two time specifications
  
−
== restore ==
+
== decimateAmplitude ==
 +
== decimateTime ==
 +
== elapsedSeconds ==
 
=== Syntax ===
 
=== Syntax ===
−
   restore(string tag);
+
   elapsedSeconds(string '''dateTime1''', string '''dateTime2''');
 +
 
 
=== Description ===
 
=== Description ===
−
Restore signals previously saved onto the stack under '''tag'''.  
+
Returns the number of seconds between '''dateTime1''' and '''dateTime2''' (format: yyyyMMddhhmmssz).
 
=== Examples ===
 
=== Examples ===
−
   see [[#save|save()]]
+
   print(elapsedSeconds("20240829160235.540000", "20240830160236.6"));
 +
 
 +
== discreteFourierTransform ==
 +
 
 +
== endTime ==
 +
=== Syntax ===
 +
  string endTime(integer '''index''');
 +
=== Description ===
 +
  Returns the ending time of signal '''index''' with format yyyyMMddhhmmssz. See also [[#startTime|startTime]].
  
 
== exportFile ==
 
== exportFile ==
−
== signalCount ==
 
 
=== Syntax ===
 
=== Syntax ===
−
   integer signalCount();
+
   exportFile(string '''filePath'''[, bool '''useOriginalBaseName'''[, string '''format'''[, number '''pickNumber''']]]);
 +
 
 +
=== Description ===
 +
Export signal(s) to '''filePath'''. '''format''' is one of the string returned by:
 +
  geopsy -export-formats
 +
=== Examples ===
 +
Export the signal (assumed to have only one) to a SAC file (big endian).
 +
  exportFile("myfolder/mysignal.sac", false, "SacBigEndian");
 +
 
 +
== fastFourierTransfrom ==
 +
== filter==
 +
 
 +
== header ==
 +
=== Syntax ===
 +
  header(number '''signalIndex''', string '''dataName''', [string '''dataIndex''']);
 +
 
 
=== Description ===
 
=== Description ===
−
Returns the number of signals to process.
+
Returns the value of '''dataName''' from signal having '''signalIndex'''. All header data related to signal file are not valid, because the process is always applied to a temporary copy of the original signal. Hence, a property like "ShortFileName" is useless in this environment.
 +
 
 
=== Examples ===
 
=== Examples ===
−
Sets the sampling frequency to 100 Hz for all signals
+
Removes the first and the last sample of all signals
 
   n=signalCount();
 
   n=signalCount();
 
   for(i=0;i<n;i++) {
 
   for(i=0;i<n;i++) {
−
     setHeader(i, "DeltaT", 0, 0.01);
+
    dt=header(i, "DeltaT");
 +
     setHeader(i, "TimePick", "t1", header(i, "T0")+dt);
 +
    setHeader(i, "TimePick", "t2", header(i, "EndTime")-dt);
 +
  }
 +
  cut("Pick", "t1", "Pick", "t2");
 +
 
 +
== leftJustified ==
 +
=== Syntax ===
 +
  leftJustified(string '''text''', integer '''nChars''', string '''fillChar''');
 +
=== Description ===
 +
  Add '''fillChar''' at the end of '''text''' so that its length is '''nChars'''. '''text''' is not modified. Returned value: the modified text. It does nothing if the length of '''text''' is greater or equal to '''nChars'''.
 +
 
 +
=== Examples ===
 +
  see [[#rightJustified|rightJustified]]
 +
 
 +
== merge ==
 +
 
 +
== mergeStations ==
 +
== multiply==
 +
 
 +
== newGroup ==
 +
=== Syntax ===
 +
  newGroup(string '''path''', string '''name''', number '''start''', number '''end''');
 +
 
 +
=== Description ===
 +
Creates a new group with signals from '''start''' to '''end'''. If '''path''' is empty, it adds the group at the root level. If not, it adds it in the tree at '''path'''.
 +
 
 +
=== Examples ===
 +
Divides the current viewer in three groups
 +
 
 +
  path="ISTerre/SmartSolo/Z"
 +
  newGroup(path, "low gain", 0, 65);
 +
  newGroup(path, "mid gain", 66, 131);
 +
  newGroup(path, "high gain", 132, 219);
 +
 
 +
== overSample ==
 +
 
 +
== print ==
 +
===Syntax===
 +
print(string '''text''')
 +
 
 +
===Description===
 +
Prints a message to the log console. It is mainly used for debug.
 +
 
 +
===Examples===
 +
 
 +
print("Hello "+2024+" world!");
 +
 
 +
== restoreStep ==
 +
=== Syntax ===
 +
  restoreStep(string '''tag''');
 +
=== Description ===
 +
Restore signals previously saved onto the stack under '''tag'''.
 +
=== Examples ===
 +
  see [[#saveStep|saveStep()]]
 +
 
 +
== rightJustified ==
 +
=== Syntax ===
 +
  rightJustified(string '''text''', integer '''nChars''', string '''fillChar''');
 +
=== Description ===
 +
  Add '''fillChar''' at the beginning of '''text''' so that its length is '''nChars'''. '''text''' is not modified. The result is returned by the function. It does nothing if the length of '''text''' is greater or equal to '''nChars'''.
 +
=== Examples ===
 +
  print(rightJustified(2, 4, "0"));
 +
 
 +
== rotateComponents ==
 +
 
 +
== saveStep ==
 +
=== Syntax ===
 +
  saveStep(string '''tag''');
 +
 
 +
=== Description ===
 +
Saves the current signals onto the stack under '''tag'''. '''tag''' is an arbitrary string used to [[#restoreStep|restoreStep()]] previously saved signals.
 +
This function is systematically produced when using the [[Geopsy: Waveform Menu|waveform menu]] items.
 +
 
 +
=== Examples ===
 +
  filter();
 +
  saveStep("Low pass 10 Hz");
 +
  whiten();
 +
  saveStep("Whiten");
 +
  restoreStep("Low pass 10 Hz");
 +
  clipStddev();
 +
 
 +
== selectSignals ==
 +
=== Syntax ===
 +
  selectSignals(number '''start''', number '''end''');
 +
 
 +
=== Description ===
 +
Restrict the current list of signals to indexes ranging from '''start''' to '''end'''.
 +
=== Examples ===
 +
Rotate horizontal components to get north components parallel to the tangent of a circular array. Rotated components are exported.
 +
 
 +
  n=signalCount()/3;
 +
  cx=2000;
 +
  cy=2000;
 +
  for(i=0; i<n;i++) {
 +
    restoreStep("original");
 +
    name=header(i*3, "Name");
 +
    x=header(i*3, "ReceiverX");
 +
    y=header(i*3, "ReceiverY");
 +
    a=Math.atan2(y-cy,x-cx)*180/3.141592;
 +
    if(a<0) a+=360;
 +
    selectSignals(i*3, i*3+2);
 +
    rotateComponents(true, a, false, 0, false, 0);
 +
    exportFile("/my/path/"+name+"_0001.sac");
 +
    print("Station "+name+" rotated by "+ a+" deg.");
 
   }
 
   }
−
== header ==
+
 
 +
== setHeader ==
 +
=== Syntax ===
 +
  setHeader(number '''signalIndex''', string '''dataName''', [string '''dataIndex''',] '''value''');
 +
 
 +
=== Description ===
 +
set '''dataName''' of signal having '''signalIndex''' to '''value'''. '''dataName''' may have an additional '''dataIndex''' for vectorial data (e.g. TimePick). For vectorial header data, '''dataIndex''' is mandatory.
 +
 
 +
Waveform processes described here are always applied to a temporary copy of the original signal. Hence, this function is not appropriate to modify signal header attributes of the original signal. The correct method is through ''Set header'' in menu ''Edit''.
 +
 
 +
=== Examples ===
 +
See [[#signalCount|signalCount()]] or [[#header|header()]]
 +
 
 +
== setStartTime ==
 +
=== Syntax ===
 +
  string setStartTime(integer '''index''', string '''dateTime''');
 +
=== Description ===
 +
  Sets the starting time of signal '''index''' with format yyyyMMddhhmmssz. See also [[#startTime|startTime]], [[#endTime|endTime]].
 +
 
 +
== shift ==
 +
=== Syntax ===
 +
  shift(number '''s''');
 +
 
 +
=== Description ===
 +
Shift signals by '''s''' seconds. '''s''' can a floating-point number and preferably a fraction a sampling period. The shift is made in frequency domain by altering only the phase of the signal.
 +
=== Examples ===
 +
Align samples to a round second for a signal sampled at 100 Hz. Current group of signal is supposed to contain only one signal (index=0).
 +
  t0=header(0, "T0");
 +
  t0rounded=Math.floor(t0*100)*0.01;
 +
  shift(t0rounded-t0);
 +
  setHeader(0, "T0", t0rounded);
 +
 
 +
== signalCount ==
 
=== Syntax ===
 
=== Syntax ===
−
   ;
+
   integer signalCount();
 
=== Description ===
 
=== Description ===
 
Returns the number of signals to process.
 
Returns the number of signals to process.
Line 53: Line 247:
 
   n=signalCount();
 
   n=signalCount();
 
   for(i=0;i<n;i++) {
 
   for(i=0;i<n;i++) {
−
     setHeader(i, "DeltaT", 0, 0.01);
+
     setHeader(i, "DeltaT", 0.01);
 
   }
 
   }
−
QString("setHeader(%1, \"%2\", %3, %4);\n")
 
−
              .arg( signalIndex )
 
−
              .arg( SignalData::dataIndex2Name( dataIndex ) )
 
−
              .arg( dataIndex._index )
 
−
              .arg( value.toString() )
 
  
−
== setHeader ==
 
−
== fastFourierTransfrom ==
 
−
== subtractValue ==
 
 
== subtractSignal ==
 
== subtractSignal ==
 
== subtractSignals ==
 
== subtractSignals ==
−
== multiply==
+
== subtractValue ==
−
== filter==
+
== stalta ==
−
== agc ==
+
 
−
== whiten ==
+
== startTime ==
−
== stddevClip ==
+
=== Syntax ===
−
== shift ==
+
  string startTime(integer '''index''');
−
== overSample ==
+
=== Description ===
 +
  Returns the starting time of signal '''index''' with format yyyyMMddhhmmssz. See also [[#endTime|endTime]].
 +
 
 +
== system ==
 +
=== Syntax ===
 +
  system(string '''command''');
 +
 
 +
=== Description ===
 +
Executes any system command with its arguments.
 +
 
 +
=== Examples ===
 +
Removes file to exported right after to avoid confusion and warnings.
 +
  system("rm -f myfolder/mysignal.sac");
 +
  exportFile("myfolder/mysignal.sac", false, "SacBigEndian");
 +
 
 
== taper ==
 
== taper ==
−
== cut ==
+
=== Syntax ===
−
== merge ==
+
  taper( [[Geopsy: Time range specification]], number '''width''');
−
== mergeStations ==
+
=== Description ===
−
== decimateAmplitude ==
+
Multiply signal in time domain by a window function.
−
== decimateTime ==
+
 
 
== waveletTransform ==
 
== waveletTransform ==
−
== stalta ==
+
== whiten ==
−
== discreteFourierTransform ==
 
−
== rotateComponents ==
 
−
== correlations ==
 

Latest revision as of 14:38, 29 August 2024

The scripting language is Javascript (a comprehensive tutorial)

Geopsy provides several additional functions for processing signals details here below. If the description is incomplete hereinafter, run the function in the graphical user interface and check the generated code in the waveform console.

Contents

Categories

addDays

Syntax

 string addDays(string dateTime, integer days);

Description

From a string containing an absolute time dateTime (format: yyyyMMddhhmmssz), adds days and returns a modified absolute time. days must by an integer.

Examples

 print(addDays("20240829160235.540000", 1));

addMonths

Syntax

 string addMonths(string dateTime, integer months);

Description

From a string containing an absolute time dateTime (format: yyyyMMddhhmmssz), adds months and returns a modified absolute time. months must by an integer.

Examples

 print(addMonths("20240829160235.540000", 1));

addSeconds

Syntax

 string addSeconds(string dateTime, number seconds);

Description

From a string containing an absolute time dateTime (format: yyyyMMddhhmmssz), adds seconds and returns a modified absolute time.

Examples

 print(addSeconds("20240829160235.540000", 86401.06));

addYears

Syntax

 string addYears(string dateTime, integer years]]]);

Description

From a string containing an absolute time dateTime (format: yyyyMMddhhmmssz), adds years and returns a modified absolute time. years must by an integer.

Examples

 print(addYears("20240829160235.540000", 1));

agc

correlations

cut

Syntax

cut( Geopsy: Time range specification );

Description

Cut the signal between two time specifications

decimateAmplitude

decimateTime

elapsedSeconds

Syntax

 elapsedSeconds(string dateTime1, string dateTime2);

Description

Returns the number of seconds between dateTime1 and dateTime2 (format: yyyyMMddhhmmssz).

Examples

 print(elapsedSeconds("20240829160235.540000", "20240830160236.6"));

discreteFourierTransform

endTime

Syntax

 string endTime(integer index);

Description

 Returns the ending time of signal index with format yyyyMMddhhmmssz. See also startTime.

exportFile

Syntax

 exportFile(string filePath[, bool useOriginalBaseName[, string format[, number pickNumber]]]);

Description

Export signal(s) to filePath. format is one of the string returned by: 

 geopsy -export-formats

Examples

Export the signal (assumed to have only one) to a SAC file (big endian). 

 exportFile("myfolder/mysignal.sac", false, "SacBigEndian");

fastFourierTransfrom

filter

header

Syntax

 header(number signalIndex, string dataName, [string dataIndex]);

Description

Returns the value of dataName from signal having signalIndex. All header data related to signal file are not valid, because the process is always applied to a temporary copy of the original signal. Hence, a property like "ShortFileName" is useless in this environment.

Examples

Removes the first and the last sample of all signals 

 n=signalCount();
 for(i=0;i<n;i++) {
   dt=header(i, "DeltaT");
   setHeader(i, "TimePick", "t1", header(i, "T0")+dt);
   setHeader(i, "TimePick", "t2", header(i, "EndTime")-dt);
 }
 cut("Pick", "t1", "Pick", "t2");

leftJustified

Syntax

 leftJustified(string text, integer nChars, string fillChar);

Description

 Add fillChar at the end of text so that its length is nChars. text is not modified. Returned value: the modified text. It does nothing if the length of text is greater or equal to nChars.

Examples

 see rightJustified

merge

mergeStations

multiply

newGroup

Syntax

 newGroup(string path, string name, number start, number end);

Description

Creates a new group with signals from start to end. If path is empty, it adds the group at the root level. If not, it adds it in the tree at path.

Examples

Divides the current viewer in three groups 

 path="ISTerre/SmartSolo/Z"
 newGroup(path, "low gain", 0, 65);
 newGroup(path, "mid gain", 66, 131);
 newGroup(path, "high gain", 132, 219);

overSample

print

Syntax

print(string text)

Description

Prints a message to the log console. It is mainly used for debug.

Examples

print("Hello "+2024+" world!");

restoreStep

Syntax

 restoreStep(string tag);

Description

Restore signals previously saved onto the stack under tag.

Examples

 see saveStep()

rightJustified

Syntax

 rightJustified(string text, integer nChars, string fillChar);

Description

 Add fillChar at the beginning of text so that its length is nChars. text is not modified. The result is returned by the function. It does nothing if the length of text is greater or equal to nChars.

Examples

 print(rightJustified(2, 4, "0"));

rotateComponents

saveStep

Syntax

 saveStep(string tag);

Description

Saves the current signals onto the stack under tag. tag is an arbitrary string used to restoreStep() previously saved signals. This function is systematically produced when using the waveform menu items.

Examples

 filter();
 saveStep("Low pass 10 Hz");
 whiten();
 saveStep("Whiten");
 restoreStep("Low pass 10 Hz");
 clipStddev();

selectSignals

Syntax

 selectSignals(number start, number end);

Description

Restrict the current list of signals to indexes ranging from start to end.

Examples

Rotate horizontal components to get north components parallel to the tangent of a circular array. Rotated components are exported. 

 n=signalCount()/3;
 cx=2000;
 cy=2000;
 for(i=0; i<n;i++) {
   restoreStep("original");
   name=header(i*3, "Name");
   x=header(i*3, "ReceiverX");
   y=header(i*3, "ReceiverY");
   a=Math.atan2(y-cy,x-cx)*180/3.141592;
   if(a<0) a+=360;
   selectSignals(i*3, i*3+2);
   rotateComponents(true, a, false, 0, false, 0);
   exportFile("/my/path/"+name+"_0001.sac");
   print("Station "+name+" rotated by "+ a+" deg.");
 }

setHeader

Syntax

 setHeader(number signalIndex, string dataName, [string dataIndex,] value);

Description

set dataName of signal having signalIndex to value. dataName may have an additional dataIndex for vectorial data (e.g. TimePick). For vectorial header data, dataIndex is mandatory.

Waveform processes described here are always applied to a temporary copy of the original signal. Hence, this function is not appropriate to modify signal header attributes of the original signal. The correct method is through Set header in menu Edit.

Examples

See signalCount() or header()

setStartTime

Syntax

 string setStartTime(integer index, string dateTime);

Description

 Sets the starting time of signal index with format yyyyMMddhhmmssz. See also startTime, endTime.

shift

Syntax

 shift(number s);

Description

Shift signals by s seconds. s can a floating-point number and preferably a fraction a sampling period. The shift is made in frequency domain by altering only the phase of the signal.

Examples

Align samples to a round second for a signal sampled at 100 Hz. Current group of signal is supposed to contain only one signal (index=0). 

 t0=header(0, "T0");
 t0rounded=Math.floor(t0*100)*0.01;
 shift(t0rounded-t0);
 setHeader(0, "T0", t0rounded);

signalCount

Syntax

 integer signalCount();

Description

Returns the number of signals to process.

Examples

Sets the sampling frequency to 100 Hz for all signals 

 n=signalCount();
 for(i=0;i<n;i++) {
   setHeader(i, "DeltaT", 0.01);
 }

subtractSignal

subtractSignals

subtractValue

stalta

startTime

Syntax

 string startTime(integer index);

Description

 Returns the starting time of signal index with format yyyyMMddhhmmssz. See also endTime.

system

Syntax

 system(string command);

Description

Executes any system command with its arguments.

Examples

Removes file to exported right after to avoid confusion and warnings. 

 system("rm -f myfolder/mysignal.sac");
 exportFile("myfolder/mysignal.sac", false, "SacBigEndian");

taper

Syntax

 taper( Geopsy: Time range specification, number width);

Description

Multiply signal in time domain by a window function.

waveletTransform

whiten

Retrieved from "https://www.geopsy.org/wiki/index.php?title=Geopsy:_Waveform_Scripting_Language&oldid=4367"