-
Notifications
You must be signed in to change notification settings - Fork 0
/
15-apps.Rmd
185 lines (116 loc) · 9.35 KB
/
15-apps.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
# Apps (i.e. plug-ins) {#apps}
Lets say a researcher begins a brand new research project and requires to analyze many RNAseq measurements. The researcher opens Tercen and proceeds to browse the Tercen library for a relevant workflow and eventually discovers a workflow template called "RNAseq" and installs it and voilà the research can begin. This is the concept of an __app__. An __app__ is a sort of plug-in, just like an iPhone app.
There are currently three types of apps: __template app__ (e.g. RNAseq), __workflow app__ (e.g. two group comparison, PCA), and __operator app__ (e.g. mean, PCA, t-test). Each __app__ has an __app version__ and is located in an __app library__.
The three types of __apps__ including some examples are:
A __template app__ is a type of template data analysis pipeline and it allows a researcher to start a complete standard analysis defined by the template (e.g. a RNAseq workflow, or a bioconductor workflow). The researcher would install a RNAseq workflow app from the Tercen library.
A __workflow app__ is a mini workflow and allows a researcher to perform a set of computations and/or visualizations e.g. the researcher requires to perform a PCA including some automated visuals of the results. The researcher would install a PCA step app from the Tercen library.
A __operator app__ performs a computation on the projection views in the cross-tab window (e.g. a PCA function) e.g. the researcher requires to perform a simple PCA without any automated visuals. The researcher would install a PCA operator app from the Tercen library.
For a complete list of operators go to the [operator catalog](https://tercen.github.io/operator_catalog/).
Typically a there is a hierarchy of apps where a __template app__ contains __workflow app__ and a __workflow app__ contains __operator app__.
As an example, think of an RNAseq app __template app__ in which there is a PCA __workflow app__ and this in turn contains a PCA __operator app__.
## App libraries {-}
There is more than one app library. However the main publicly available library is called the __Tercen app library__. The other app libraries have different location and permission levels.
Library | Location|Permission level |
:----- | :------- |:------- |
Tercen app library | tercen github| Public |
Site app library | tercen server| Site only|
Team app library | tercen team area| Team only |
A __site__ is a Tercen server installed on a machine at an installation site.
A library consists of a set of __apps__ and their __versions__.
__Tercen app library:__
All public Tercen operators and apps are found on the (tercen github)[https://github.com/tercen].
The contents of the public Tercen app library are found in a json file in [github app library](https://github.com/tercen/app-library)
The public operators and apps are also found on the Tercen area, see (https://github.com/tercen)
## Installing apps {-}
A researcher installs an app by sourcing it from any of the libraries (tercen app library, site library, team library) or from a git repository.
## Structure of an operator app {-}
A Tercen operator is composed of three main activities:
* Getting the data
* Operating on the data
* Returning the results
A Tercen operator requires a Tercen __data step__ in order to work. The operator is defined in a __data step__ and the __data step__ contains all that is necessary for the operator, namely structure data. The structure of the data becomes clear when you explore the table data structure of a __data step__. Go ahead and open a __data step__ and you will notice three vertical tabs on the left of the window. The first tab is the default view is called the __cross tab__ view. The other two are associated with data tables. For each __data step__ there are two tables tabs:
* __Tables tab__ (i.e. the data input to the operator)
* __Computed tables tab__ (i.e. the data output of the operator)
Note: the __Computed tables tab__ only appears when the data step has been computed (i.e. the __data step__ has a green executed status)
Each table contains data as a result of the definition of the cross-tab view.
The __Tables tab__ contain the following three tables:
* __Main table__
* __Row table__
* __Col table__
The __Main table__ contains the data to be used to compute in __long format__. Each row represents a value and the column names are a mixture of the the original table names and Tercen system column names. The Tercen system table names are there for the correct operation of Tercen and are automatically added by Tercen. They usually begin with a dot `.`, examples are:
``.ri`` row index of data, represented by an integer
``.ci`` col index of data, represented by an integer
Using these table column names you can see the structure of Tercen and how Tercen 'thinks'.
The __Computed tables__ only appears when the data step is computed. It contains the following the results of the computation.
If you are familiar with reading code then take some time to look at the operator code on the public tercen github. It gives a good outline on how operators are structured. Look at the file called `main.R` file. This is the key code for performing the operator.
## Tercen R package {-}
There is currently an R package in the tercen repository to help in creating R operators called [teRcen](https://github.com/tercen/teRcen).
If you wish to use other programming languages then it is possible by using the Tercen API directly. The tercen R package is purely a wrapper package for the Tercen API.
## Creating an operator app {-}
The ability to create a new Tercen operator requires basic programming skills.
Here is the top-level development process to create an __operator app__:
* Download and setup tercen studio
* Write the operator (with tercen studio)
* Deploy the operator (with tercen studio)
For further documentation regarding building operators. Please go the [app builders guide](https://tercen.github.io/appbuilders-guide/).
## Creating a workflow app {-}
It is easy to create a __workflow app__. The first step is to create a Tercen workflow and the second step is to deploy it. There are two main methods of deployment.
The first method to deploy:
* Make a workflow first
* Save the workflow
* Clone the workflow into the `apps` folder for your team
* It is now available to your team members
The second method to deploy:
* Make a workflow first
* Save the workflow
* Download the workflow (as zip) of the __step app__
* Unzip the folder
* Add `README.md` file
* Add `.gitignore` file
* Choose a repository name and add a suffice `_app`.
* Create a git repository for the new __workflow app__
* Upload the files to the new __workflow app__ git repository
The __workflow app__ can now be installed as any other operator from github.
## Creating a template app {-}
It is easy to create a __template app__. The first step is to create a Tercen workflow and the second step is to deploy it. There are two main methods of deployment. The first method makes it for you team members. The second method allows your template for any team wishing to use it.
The first is:
* Make a workflow first
* Save the workflow
* Clone the worfklow into the `templates` folder for your team
* It is now available to your team members
The workflow is now available for use for your Team.
The second is:
* Make a workflow first
* Save the workflow
It is straight forward to create a __template app__. The first step is to create a Tercen workflow and the second step is to deploy it. There are two main methods of deployment. The first method makes it for you team members. The second method allows your template for any team wishing to use it.
The first method to deploy:
* Make a workflow first
* Save the workflow
* Clone the workflow into the `templates` folder for your team
* It is now available to your team members
The __template app__ is now available for use for your Team.
The second method to deploy is:
* Make a workflow first
* Save the workflow
* Download the workflow (it downloads as .zip)
* Unzip the folder
* Add `README.md` file
* Add `.gitignore` file
* Choose a repository name and add a suffice `_tmpl`.
* Create a git repository for the new __template__ git repository
* Upload the files to the new __template__ git repository
* Tag your repository
The __template app__ is now available for installation for any Team.
The __template app__ can now be installed as any other operator from github.
## App examples {-}
__Operator app examples:__
An __operator app__ which performs computation follows either one of the following computing pattern :
* per row
* per col
* per row and per col (i.e. per cell)
## App versioning {-}
In science, it is essential to reproduce the complete analysis you may have published many years ago. Tercen manages versions very tightly. This is particular important when you consider the three app layers in Tercen. Each layer requires versioning.
Tercen manages the __workflow__ and __workflow apps__ using the metadata associated with both those apps. For __operator apps__ written in R, it uses the `renv` package. `renv` makes sure when the researchers chooses to use an operators from the __app library__ it uses exactly the same version of R packages used by the developer who developed the operator and uploaded it in the __app library__.
# Developers guide
For further documentation regarding building apps. Please go the [Developers guide](https://tercen.github.io/developers_guide/).
<center>![](images/app.png)</center>