Examples
TIP
We well know that one example is worth a thousand words, therefore, we present you with a handful of examples illustrating various functionalities that can be used in your custom applications. Each of them can be copied and directly used in your workspace, and, later, modified to better suit your research.
Contents of this guide
This guide contains links to sample ready-to-use applications, that will help you understand different possibilities related to custom applications. Each sample application is described presenting the aspects of configuration it shows. The guide contains also an instruction on how to copy and use the sample applications for yourself.
How to use the examples
Each example contains a link to the sample application within the Application Workbench. After accessing it, you will see a list of its files, where you can browse them (you will not be able to edit them at this point). If you decide you want to test this application in your workspace and later use it as a base for your own codes, use the Fork button in the right upper corner of the page (see Figure 1).
Note that, to access and fork the sample applications you will have to log in to the Application Workbench first.
Upon this action, you will be able to decide on the name under which the application will be copied to your account (Repository Name, marked with (1) in Figure 2). You will be also able to add your custom description (Description, marked with (2) in Figure 2).
After confirming with the Fork Repository button, your copy of the application repository will be created and presented to you. The copied application will have the same contents, therefore, the view will much resemble the original application (Figure 1). However, notice the change of the user name (the repository name may also be changed if you did that in the previous step) and the information that the repository is forked (marked in Figure 3). The button Fork will also be disabled as you cannot create another fork from a repository that already is a fork. You will also have more controls enabling management of your repository and edition of files.
Since this moment you will be able to see the application also within My Apps Management tab in EPISODES Platform.
The above means that you will also be able to use the application and run it in your workspace (see also Running your custom application guide) as it will appear within the Applications list in the EPISODES Platform (note, that it will be visible only as long as you are logged in).
Example 1 (Matlab/Octave)
Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/MatlabSampleApp1
Programming language: the application is written in Octave programming language and configured to be run with Octave interpreter (settings underlined in Figure 6), however, it is also compatible with Matlab programming language and could be run with Matlab interpreter as well.
The application contains a simple code that plots a vector of double-precision numbers and returns it in a form of a PNG file - as demonstrated in Excerpt 1. This, however simple, code, to be correctly interpreted by the EPISODES Platform, requires a configuration, called Application Definition, which will tell the Platform how to transfer the input files to your application and what to do with the output files. Figure 6 shows the configuration used for this application, with input files definition marked with (1): one file of type double_vector, and output files definition marked with (2): one output file of type image_data and name vectorPlot.png, in PNG format. Thanks to this definition the interface of the application within the EPISODES Platform would allow you to add a double_vector file (e.g. a magnitude vector extracted from a Seismic Catalog with Catalog to Vectors converter) as input to the application, and will look for a file vectorPlot.png when the application finishes and transfer it to your workspace, where you will be able to display it - exactly as shown in Figure 7. Note, that if you change your code, so that it produces another file, it will be ignored by the system, unless you add it to the appDefinition.json. Similarly, to add another input to the application, you have to add it both to the application script and to the appDefinition.json file.
Note, that the configuration file presented here is generated by the EPISODES Platform through a dedicated wizard (see also Creating new application guide), therefore, it might be more verbose than necessary, but if you use this wizard, your file will look like this one. In the Application Definition file guide, you can find alternatives to the configuration elements that can make them simpler (and shorter) - an example of this is shown in rectangles in Figure 6 - both of the rectangles represent the same meaning as the part of code marked with (1).
delphi
function sampleApp(inVector)
plot(inVector);
print('-dpng', 'vectorPlot.png');
endExcerpt 1. Content of the MatlabSampleApp1 application script
Example 2 (Matlab/Octave)
Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/MatlabSampleApp2
Programming language: the application is written in Octave programming language and configured to be run with Octave interpreter, however, it is also compatible with Matlab programming language and could be run with Matlab interpreter as well.
The application contains a simple code that multiplies a vector of double-precision numbers by an (integer) multiplier and returns the resulting vector - demonstrated in Excerpt 2. As with the previous application (and, in fact, any application), along the script we need the Application Definition file to be use it within the EPISODES Platform. Figure 8 shows the configuration used for this application, with input files definition marked with (1): one file of type double_vector, input parameter marked with (2): integer named 'Multiplier' and output files definition marked with (3): one output file of type double_vector (the same as input type) that is returned by the function (will be in Matlab data format). For this configuration, the EPISODES Platform will allow you to add a double_vector file (e.g. a magnitude vector extracted from a Seismic Catalog with Catalog to Vectors converter) as input to the application (similarly as in the previous application), and to specify an input paremeter named Multiplier through the application form. It will also look for a file double_vector.mat (the name is derieved from the output data type) when the application finishes and transfer it to your workspace, where you will be able to display it - as shown in Figure 9. Note, that the result file is displayed using the default visualization for double_vector, therefore, the output is presented as a plot, with possibility to also list the values inside.
delphi
function outVector = sampleApp(inVector, multiplier)
outVector = inVector .* multiplier;
endExcerpt 2. Content of the MatlabSampleApp2 application script
Example 3 (Python)
Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/PythonSampleApp
Programming language: the application is written in Python programming language (settings underlined in Figure 10).
The application presents functionality being a combination of the the two previous examples. It takes an array of numbers, multiplies them by another number (integer) and plots them on a figure that is saved to a file. The Application Definition (appDefinition.json) file defines the input (marked with (1) in Figure 10) and output (marked with (3) in Figure 10) in similar way as in Example 1, and input parameter - as in Example 2. The important difference is that with Python, we are responsible for reading the content of the input file ourselves, whereas with Matlab/Octave, the content of the Matlab data file is automatically loaded to the interpreter context. Due to this, the input type is text_data as the code for reading text data in Python is much less complex than for reading a Matlab format file (which, nevertheless, is possible).
py
import numpy as np
import matplotlib.pyplot as plt
def main(numbers_file, multiplier):
numbers = np.genfromtxt(numbers_file, comments="#", delimiter=",", unpack=False)
numbers = numbers[~np.isnan(numbers)]
numbers = np.array(numbers).flatten()
multiplied_numbers = numbers * multiplier
plt.figure()
plt.plot(multiplied_numbers)
plt.savefig('multiplied_numbers_plot.png')Excerpt 3. Content of the PythonSampleApp application script
Example 4 (Python)
Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/PythonSampleAppMultipleFiles
Programming language: the application is written in Python programming language (settings underlined in Figure 12).
The application extends the Example 3 by accepting multiple input files instead of a single one. It takes an arbitrary number of txt files containing arrays of numbers, multiplies each array by a given integer, and overlays all resulting series on a single plot saved to a file. The Application Definition (appDefinition.json) file defines the input (marked in Figure 12) with multiplicity one or more. The important difference is that the input file argument is now passed to the Python main function as a Python list of file paths rather than a single path string. Because of this, we are responsible for iterating over the list ourselves and reading each file in turn - the multiplicity declared in the application definition determines the Python type the script receives (one-> single string; one or more/zero or more/multiple -> list of strings; zero or one-> string or None).
py
import numpy as np
import matplotlib.pyplot as plt
def main(numbers_files, multiplier):
plt.figure()
for numbers_file in numbers_files:
numbers = np.genfromtxt(numbers_file, comments="#", delimiter=",", unpack=False)
numbers = numbers[~np.isnan(numbers)]
numbers = np.array(numbers).flatten()
multiplied_numbers = numbers * multiplier
plt.plot(multiplied_numbers)
plt.savefig('multiplied_numbers_plot.png')Excerpt 4. Content of the PythonSampleAppMultipleInputs application script
Example 5 (Python)
Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/PythonSampleAppEnv
Programming language: the application is written in Python programming language.
The application has exactly the same functionality as Example 3, but different configuration of Python dependencies. While the previous example uses the requiredTools configuration in appDefinition.json file to specify which Python packages will be used (underlined at the bottom of Figure 10), Example 4 uses Environment specification file to configure the packages. For this purpose, appDefinition.json has to contain the two lines marked in Figure 14. The repository also includes environment.yml file with the packages specification (see Figure 15).
The code of the application is identical with the code of Example 3 (see Excerpt 3), the application form and result will also be the same (see Figure 11).
