Page History

...

Application Definition (Required)

A JSON file file (see this documentation for more information on JSON format) named appDefinition.json. Specifies inputs and outputs of the application and how the application should be run.

...

• scriptLanguage - name of the scripting language in which the application is written. Currently only one language is available:
  • MATLAB - MATLAB programming language. This applies also to Octave applications 
• executableScriptName - name of the application executable file
• functionName - name of main function used to execute the application
• inputFiles (Optional*) - input files that are needed by the application. For each input file defined here, the application panel will show a button to choose the location of that file. When the application is run, the input files will be read into a MATLAB variable variables and passed as arguments to the main executable function . The in the order in which the inputs are passed to the function is described in Executable Script section. Each they appear here.  Each input file is defined by: 
  • dataType - data type of the input (see Data Types section below)
  • typeLabel (Optional*) - a name distinguishing this input file from others. Allows to have multiple input files with the same data type. Each input file with different type label will be treated as a separate input and be passed to the main function as a separate argument  
  • multiplicity - how many inputs of that type are expected (written as string value). Defines minimum required number and maximum allowed number of inputs. The portal validates if the user selected the minimal required correct number of input files, and if not it will forbid , it will not allow the user to run the application from being run. Depending on what multiplicity is given the input(s) might be passed to the main function in a different way (see Input Multiplicity section). The possible values are:
    • ? -  zero or one. The input is optional, there can be at most one input file
    • * -  zero or more. The input is optional and there is no upper limit of how many input files there can be
    • + - one or more. At least one file is required and there is no upper limit of how many input files there can be
    • n - exactly n input files are expected - no more, no less  
    • [n, m] - there should be at least n input files and at most m input files
• inputParameters (Optional*) - simple input parameters that should be entered by the user. For each parameter defined here, the application panel will show input form where the user can enter the value of the parameter. When the application is run, the parameters' values will be passed as arguments to the main executable function . The in the order in which the parameters are passed to the function is described in Executable Script section. they appear here. The parameter arguments are added after arguments specified by input files (see section Executable Script). When adding a parameter you have to specify what kind of value it should have. The available options are:
  
  • TEXT - a text value
  • BOOLEAN - a true or false value
  • DOUBLE - a real number value
  • INTEGER - an integer value
  • TIME - a date value
    Thats how The figure/screen-shot below shows how the input paramters parameters will look like appear when they are presented as input forms in the application panel:

 Image Modified

• outputs - list of outputs generated by the application. The outputs defined here should be returned as output variables by the main executable function. After the function is run each of these outputs will be saved as a mat file and returned as a result of the application. Each output is defined by:
  • dataType - data type that this output file should have  (see Data Types section below)
  • fileName - name of the file under which this output should be saved
• requiredTools - list of programs or tools that are needed to run the application. At least one value should be present - the script interpreter. Please contact us if you need any other tools, or toolboxes, or if you require a specific version of a Matlab or Octave interpreter. Available options are:
  • matlab - the MATLAB interpreter. By default one of these versions will be used: 2019b or 2021a (this is subject to change)state as of October 2021, the versions might be updated in the future). 
  • matlab-signal_processing_toolbox - signal processing toolbox. Usable only with MATLAB
  • matlab-image_processing_toolbox - image processing toolbox. Usable only with MATLAB
  • octave - the Octave interpreter. By default one of these versions will be used: 3.8.1 or 4.2.1 (this is subject to changestate as of October 2021, the versions might be updated in the future)
• requiredComputationResources (Optional) - a map defining what computational resources should be available to the application. Available options are: 
  • COMPUTATION_TIME - maximum time that an application needs for the computation (in minutes). If not specified it defaults to 30 minutes 
  • MEMORY - maximum memory that an application needs for the computation (in gigabytes). If not specified it defaults to 2GB 
  • CPU_COUNT - number of processors that should be available to the application. If not specified it defaults to 1

* If a field is marked as 'Optional' it means that it doesn't have to be present in the file

Sample file

{
  "scriptLanguage":"MATLAB",
  "executableScriptName":"sampleScriptName.m",
  "functionName":"sampleScriptName",
  "inputFiles":[
    {
      "dataType":"double_vector",
      "multiplicity":"1",
      "typeLabel": "label"
    }
  ],
  "inputParameters":[
    "DOUBLE",
    "TEXT"
  ],
  "outputs":[
    {
      "dataType":"double_vector",
      "fileName":"output.mat"
    }
  ],
  "requiredComputationResources":{
    "COMPUTATION_TIME":5
  },
  "requiredTools":[
    "octave"
  ]
}

Optional Fields

If a field is marked as 'Optional' it means that it doesn't have to be present in the file. For example, the above example without any optional fields would like like this:

{
  "scriptLanguage":"MATLAB",
  "executableScriptName":"sampleScriptName.m",
  "functionName":"sampleScriptName",
  "outputs":[
    {
      "dataType":"double_vector",
      "fileName":"output.mat"
    }
  ],
  "requiredComputationResources":{
    "COMPUTATION_TIME":5
  },
  "requiredTools":[
    "octave"
  ]
}

Data Types

Data Types

The The data type field that is present in input and output definition must contain a name of one of predefined data types. The predefined data types. It is important that the name is written in exactly the same way as it is in the predefined data type. You can check the possible data types in the upload file form in the platform, or you can contact us. The most commons types are: 

• double_vector - a vector of real number values
• time_vector - a vector of date values
• integer_vector - a vector of integer values
• boolean_vector - a vector of boolean values 
• string_vector - a vector of text values
• catalog - a seismic catalogseed
• fullseed - a full- a SEED file fullseed - a (SEED file containing that contains both data records and station information)miniseed - a SEED file that contains only data record
• miniseed - a miniSEED file (SEED file that contains only data record)
• seed - denotes a type that can be either a fullseed or a miniseed. Should be used when it does not matter if the seed file contains the dataless information or not

Executable Script (Required)

...

• intValues - corresponds to the input file with type 'integer_vector'
• stringValues - corresponds to the input file with type 'string_vector'
• text - corresponds to the input parameter with type TEXT
• multiplicator - corresponds to the input parameter with type DOUBLE
• outputDoubleValues - corresponds to the output with type 'double_vector'
• outputBooleanValues - corresponds to the output with type 'boolean_vector'

...

Handling custom multiplicity in input files

Depending on what multiplicity is given the input(s) might be passed to the main function in a different way:

...

is given the input(s) might be passed to the main function in a different way. In the example above, all input files had multiplicity defines as "1" (default) - in such case, each file is read to a MATLAB variable which is passed directly as argument to the main function. If the multiplicity is set to any other value, all the files provided by the user for this input are read to MATLAB variables and packed into a single cell array before being passed as argument to the main function. For example, if the function has one input of type double_vector and multiplicity set to "*" and there are 3 input files, the function will receive a cell array containing three double vectors. If, however there are no input files present, an empty cell array will be passed. The variables in the cell array are not guaranteed to be in any specific order. This is done by design, inputs of the same data type and non-singular multiplicity are undistinguishable from each other. If you need to have a few inputs with the same data type, and you need to be able to distinguish between them use typeLabel instead.  

Application Description (Optional)

A JSON file (see this documentation for more information on JSON format) named appDescription.json. Defines how the application will be described in the Applications page inside the EPISODES platform, and how a workspace directory will be named when the application is created. This file is optional - if it is not present the required fields - shortName and name - will be filled with the name of the repository, and all other fields will be left empty.

...