Context Navigation

getting_started.html @ 7982

Visit:

Last change on this file since 7982 was 7982, checked in by Nicklas Nordborg, 22 months ago
Merge BASE 3.18.2 to the trunk
Property svn:eol-style set to `native` Property svn:keywords set to `Id Date`
File size: 24.1 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
3	<!--
4	$Id: getting_started.html 7982 2021-06-14 08:01:21Z nicklas $
5
6	Copyright (C) 2006 Jari H�kkinen
7
8	This file is part of BASE - BioArray Software Environment.
9	Available at http://base.thep.lu.se/
10
11	BASE is free software; you can redistribute it and/or modify it
12	under the terms of the GNU General Public License as published by
13	the Free Software Foundation; either version 3 of the License, or
14	(at your option) any later version.
15
16	BASE is distributed in the hope that it will be useful, but
17	WITHOUT ANY WARRANTY; without even the implied warranty of
18	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	General Public License for more details.
20
21	You should have received a copy of the GNU General Public License
22	along with BASE. If not, see <http://www.gnu.org/licenses/>.
23	-->
24
25	<html>
26	<head>
27	<title>BASE 2.1 - User documentation: Getting started</title>
28	<link rel=stylesheet type="text/css" href="../styles.css">
29	</head>
30	<body>
31
32	<div class="navigation">
33	<a href="../index.html">BASE</a>
34	<img src="../next.gif">
35	<a href="index.html">User documentation</a>
36	<img src="../next.gif">
37	Getting started
38	</div>
39
40	<h1>BASE 2.1 - User documentation: Getting started</h1>
41
42	<div class="abstract">
43
44	<p>
45	This document describes how to get started with your new shiny
46	BASE box.
47	</p>
48
49	<b>Contents</b>
50	<ol>
51	<li><a href="#administative">Administrative tasks</a></li>
52	<li><a href="#user">User tasks</a></li>
53	</ol>
54
55	<p class="authors">
56	<b>Last updated:</b> $Date: 2021-06-14 08:01:21 +0000 (Mon, 14 Jun 2021) $ <br>
57	<b>Copyright ©</b> 2006 The respective authors. All
58	rights reserved.
59	</p>
60
61	</div>
62
63	<p> This description will take you from uploading raw data to
64	running the first analysis plug-ins. Both Affymetrix and Genepix
65	data will be used as examples. </p>
66
67	<ol>
68
69	<li>
70	<a name="administrative"></a>
71	<h2>Administrative tasks</h2>
72
73	<p> Most of the task in this section requires more privileges
74	than the normal user credentials. You should log in as an
75	administrator when you perform these tasks. As always, there
76	are many ways to do things and what is presented here is the
77	path to get going with BASE as fast as possible without
78	creating havoc in future use of the BASE server. </p>
79
80	<ol type=a>
81
82	<li>
83	<p> <b>Create an administrator account</b> <br> Log in as
84	'root' using the password you set during BASE
85	initialization. Create an administrator account. Log out,
86	and use the admin account for all administrative
87	tasks. The root account should not be used as the
88	administrator account. </p>
89	</li>
90
91	<li>
92	<p> <b>Create user accounts</b> <br> Create user accounts
93	using the newly created administrator account. You should
94	give your users appropriate roles, most of them should be
95	assigned to the 'User' role. (Link to role docs?) You can
96	create new roles if the default ones does not fit your
97	needs. </p>
98	</li>
99
100	<li>
101	<p> <b>Create essential plug-in configurations</b> <br>
102	Some plug-ins need to be configured before use, whereas
103	other works out of the box. Some external plug-ins as the
104	<a
105	href="https://baseplugins.thep.lu.se/wiki/thep.lu.se.RMAExpress">RMAExpress
106	plug-in for BASE</a> has to be compiled before including
107	them into your BASE server.</p>
108
109	<p> Core plug-ins are a set of plug-ins that are
110	automatically installed during setup. As pointed out
111	above, these may need a configuration to work. The way to
112	find out which plug-ins need a configuration is to choose
113	Administrate -> Plugins -> Definitions. This will display
114	a list all plug-ins available for your BASE
115	server. Nothing is shown? The reason for this is that your
116	newly created administrator does not own the definitions,
117	change the view/preset to show shared items as well. By
118	clicking on the 'Columns' tab you can select what
119	information should be displayed in the list. Please select
120	'Requires config' in the 'Columns' tab, and move it up in
121	the left panel. Finalize by clicking 'Ok'. The list now
122	has an extra column with yes and no's. Mark the 'true'
123	radio button in the 'Requires config' column to only list
124	plug-ins that need a configuration.
125
126	<p> The exercise above had two important aims. i) To show
127	you what plug-ins already exists, and ii) find three
128	essential plug-ins that needs a configuration each. Before
129	any raw data can be stored in BASE some information has to
130	be available in BASE. The slide design (reporter map) and
131	reporter information (probe set information in Affymetrix
132	vocabulary). For these imports to work for Genepix data we
133	need to create configurations for the "Reporter map
134	importer" and "Reporter importer" respectively, and a
135	configuration is needed for the raw data import plug-in,
136	"Raw data importer", as well. Affymetrix data import works
137	differently and only a "Reporter map importer"
138	configuration is needed.</p>
139
140	<p> The pre-installed plug-in definitions are already
141	shared to group 'Everyone' (all users are members of this
142	group) but the configurations created are not shared by
143	default. The configurations should be shared to the users
144	who should have access to them, normally group
145	'Everyone'. As counterexamples, the reporter importers and
146	reporter map importers do not have to be share to everyone
147	since these imports should only be allowed to be done by a
148	small group of users. Every reporter and reporter map
149	should only be imported once and all users should use the
150	same reporter and reporter map information. The raw data
151	importers should normally be shared to everyone since all
152	users import data into BASE. </p>
153
154	<p> <i>Reporter importer</i> <br> Select the "Reporter
155	importer", and click on the 'New configuration ...'
156	tab. Enter a name in the 'Name' field (Affymetrix probe
157	set importer / Genepix reporter import) and click 'Save
158	and configure' button. The next pop-up expects input of
159	regular expression needed to import reporter data. Here we
160	just give the values to add to the panel, but as of
161	version 2.1 it is possible to use a import format
162	wizard. The wizard is started by clicking on the 'Test
163	with file ...' button. </p>
164
165	<p> Below we tabulate regexps to enter for a few file
166	formats if you prefer to enter the regexp manually. Note
167	1: Here it is assumed that the default
168	<a
169	href="../admin/extended-properties.html">extended-properties.xml</a>
170	is used. Note 2: your browser may break lines in the
171	table cells, treat these line breaks as a ' ' (space)
172	character. Note 3: Depending on your files the values to
173	input may be different.
174	<table cellspacing=3>
175	<tr>
176	<td align=left> <i>Column</i> </td>
177	<td align=left> <i>Affymetrix</i> </td>
178	<td align=left> <i>Genepix .gpr</i> </td>
179	<td align=left> <i>Genepix .txt</i> </td>
180	</tr>
181	<tr>
182	<td> Data Header </td>
183	<td> "Probe Set ID","GeneChip Array",.* </td>
184	<td> "Block"\t"Column"\t"Row"\t"Name"\t"ID"\t.* </td>
185	<td> 384_number\t384_column\t384_row\t384_position\toligo_id.* </td>
186	</tr>
187	<tr>
188	<td> Data splitter </td>
189	<td> (?!"),(?=") </td>
190	<td> \t</td>
191	<td> \t</td>
192	</tr>
193	<tr>
194	<td> Remove quotes </td>
195	<td> true </td>
196	<td> true </td>
197	<td> true </td>
198	</tr>
199	<tr>
200	<td> Name </td>
201	<td> \Probe Set ID\ </td>
202	<td> \Name\</td>
203	<td> \oligo_id\</td>
204	</tr>
205	<tr>
206	<td> Reporter ID </td>
207	<td> \Probe Set ID\ </td>
208	<td> \ID\</td>
209	<td> \oligo_id\ </td>
210	</tr>
211	<tr>
212	<td> Gene symbol </td>
213	<td> \Gene Symbol\ </td>
214	<td> </td>
215	<td> \gene_symbol_Ensembl*\ </td>
216	</tr>
217	<tr>
218	<td> Cluster ID </td>
219	<td> \UniGene ID\ </td>
220	<td> </td>
221	<td> \RefSeq\ </td>
222	</tr>
223	</table>
224	<br> Finalize with clicking 'Next'. You can of course fill
225	the other entries as well. </p>
226
227	<p> <i>Reporter map importer</i> <br> Affymetrix CDF files
228	do not need a configuration since these are not imported
229	to BASE with a plug-in. Genepix data requires a
230	configuration. To configure a plug-in for Genepix reporter
231	map imports select the "Reporter map importer" from the
232	plug-in definition list. Click on the 'New configuration
233	...' tab. Enter a name in the 'Name' field (Affymetrix
234	probe set importer / Genepix reporter map importer) and
235	click 'Save and configure' button. The next pop-up expects
236	input of regular expression needed to import reporter map
237	data. Here we just give the values to add to the panel,
238	but as of version 2.1 it is possible to use a import
239	format wizard. The wizard is started by clicking on the
240	'Test with file ...' button. Below we tabulate regexps to
241	enter if you prefer to enter the regexp manually:
242	<table cellspacing=3>
243	<tr>
244	<td align=left> <i>Column</i> </td>
245	<td align=left> <i>Genepix .gpr</i> </td>
246	</tr>
247	<tr>
248	<td> Data Header </td>
249	<td> "Block"\t"Column"\t"Row"\t"Name"\t"ID"\t.* </td>
250	</tr>
251	<tr>
252	<td> Data splitter </td>
253	<td> \t</td>
254	</tr>
255	<tr>
256	<td> Remove quotes </td>
257	<td> true </td>
258	</tr>
259	<tr>
260	<td> Reporter ID </td>
261	<td> \ID\</td>
262	</tr>
263	<tr>
264	<td> Block </td>
265	<td> \Block\ </td>
266	</tr>
267	<tr>
268	<td> Column </td>
269	<td> \Column\ </td>
270	</tr>
271	<tr>
272	<td> Row </td>
273	<td> \Row\ </td>
274	</tr>
275	</table>
276	<br> Finalize with clicking 'Next'. You can of course fill
277	the other entries as well. </p>
278
279	<p> <i>Raw data importer</i> <br> Affymetrix CEL files do
280	not need a configuration since these are not imported to
281	BASE with a plug-in. Genepix data requires a
282	configuration. Create a configuration for Genepix raw data
283	import by selecting the "Raw data importer" from the
284	plug-in definition list. Click on the 'New configuration
285	...' tab. Enter a name in the 'Name' field (Genepix raw
286	data importer) and click 'Save and configure' button. The
287	next pop-up expects input of regular expression needed to
288	import raw data. Here we just give the values to add to
289	the panel, but as of version 2.1 it is possible to use a
290	import format wizard. The wizard is started by clicking on
291	the 'Test with file ...' button. Below we tabulate
292	regexps to enter if you prefer to enter the regexp
293	manually:
294
295	<table cellspacing=3>
296	<tr>
297	<td align=left> <i>Column</i> </td>
298	<td align=left> <i>Genepix .gpr</i> </td>
299	</tr>
300	<tr>
301	<td>Raw data type</td>
302	<td>Genepix</td>
303	</tr>
304	<tr>
305	<td>Header</td>
306	<td>"(.+)=(.*)"</td>
307	</tr>
308	<tr>
309	<td>Data header</td>
310	<td>"Block"\t"Column"\t"Row"\t"Name"\t"ID"\t."Ratio of Medians $532\/635$".</td>
311	</tr>
312	<tr>
313	<td>Data splitter</td>
314	<td>\t</td>
315	</tr>
316	<tr>
317	<td>Min data columns</td>
318	<td>48</td>
319	</tr>
320	<tr>
321	<td>Max data columns</td>
322	<td>48</td>
323	</tr>
324	<tr>
325	<td>Block</td>
326	<td>\Block\</td>
327	</tr>
328	<tr>
329	<td>Column</td>
330	<td>\Column\</td>
331	</tr>
332	<tr>
333	<td>Row</td>
334	<td>\Row\</td>
335	</tr>
336	<tr>
337	<td>X</td>
338	<td>\X\</td>
339	</tr>
340	<tr>
341	<td>Y</td>
342	<td>\Y\</td>
343	</tr>
344	<tr>
345	<td>Reporter ID</td>
346	<td>\ID\</td>
347	</tr>
348	<tr>
349	<td>Spot diameter</td>
350	<td>\Dia.\</td>
351	</tr>
352	<tr>
353	<td>Channel 1 foreground median</td>
354	<td>\F635 Median\</td>
355	</tr>
356	<tr>
357	<td>Channel 1 foreground mean</td>
358	<td>\F635 Mean\</td>
359	</tr>
360	<tr>
361	<td>Channel 1 foreground standard deviation</td>
362	<td>\F635 SD\</td>
363	</tr>
364	<tr>
365	<td>Channel 1 background median</td>
366	<td>\B635 Median\</td>
367	</tr>
368	<tr>
369	<td>Channel 1 background mean</td>
370	<td>\B635 Mean\</td>
371	</tr>
372	<tr>
373	<td>Channel 1 background standard deviation</td>
374	<td>\B635 SD\</td>
375	</tr>
376	<tr>
377	<td>Percent pixels within 1 standard deviation</td>
378	<td>\% > B635+1SD\</td>
379	</tr>
380	<tr>
381	<td>Percent pixels within 2 standard deviations</td>
382	<td>\% > B635+2SD\</td>
383	</tr>
384	<tr>
385	<td>Percent saturated pixels</td>
386	<td>\F635 % Sat.\</td>
387	</tr>
388	<tr>
389	<td>Channel 2 foreground median</td>
390	<td>\F532 Median\</td>
391	</tr>
392	<tr>
393	<td>Channel 2 foreground mean</td>
394	<td>\F532 Mean\</td>
395	</tr>
396	<tr>
397	<td>Channel 2 foreground standard deviation</td>
398	<td>\F532 SD\</td>
399	</tr>
400	<tr>
401	<td>Channel 2 background median</td>
402	<td>\B532 Median\</td>
403	</tr>
404	<tr>
405	<td>Channel 2 background mean</td>
406	<td>\B532 Mean\</td>
407	</tr>
408	<tr>
409	<td>Channel 2 background standard deviation</td>
410	<td>\B532 SD\</td>
411	</tr>
412	<tr>
413	<td>Percent pixels within 1 standard deviation</td>
414	<td>\% > B532+1SD\</td>
415	</tr>
416	<tr>
417	<td>Percent pixels within 2 standard deviations</td>
418	<td>\% > B532+2SD\</td>
419	</tr>
420	<tr>
421	<td>Percent saturated pixels</td>
422	<td>\F532 % Sat.\</td>
423	</tr>
424	<tr>
425	<td>Foreground pixels</td>
426	<td>\F Pixels\</td>
427	</tr>
428	<tr>
429	<td>Background pixels</td>
430	<td>\B Pixels\</td>
431	</tr>
432	<tr>
433	<td>Flags</td>
434	<td>\Flags\</td>
435	</tr>
436	</table>
437	<br> Finalize with clicking 'Next'. You can of course fill
438	the other entries as well. </p>
439	</li>
440
441	<li>
442	<p> (Affymetrix only) <b>Install
443	<a name=RMAExpressInstall
444	href="https://baseplugins.thep.lu.se/wiki/thep.lu.se.RMAExpress">RMAExpress
445	plug-in for BASE</a></b> <br> This plug-in is required for
446	Affymetrix data. The plug-in will create a bioassay set,
447	i.e., to be able to analyse the data in BASE.</p>
448	</li>
449
450	<li>
451	<p> <b>Upload files</b> <br> Before import you can upload
452	files to the server, or if preferred, files to be imported
453	can be uploaded at import time. To upload files, choose
454	'View' -> 'Files' and click in the 'Upload file...'
455	button. At upload time you assign a type to the file (can
456	be changed later if needed), and batch upload of files is
457	possible in a zip-file or tar archive. </p>
458
459	<p> As administrator you need to upload the reporter map
460	(array design) files and corresponding reporter files. For
461	Affymetrix this translates to Affydesign.cdf files and
462	Affydesign_annot.csv files. </p>
463	</li>
464
465	<li>
466	<p> <b> Reporter import </b> <br> Choose 'View' ->
467	'Reporters' and click on the 'Import...' tab. Click 'Next'
468	in the pop-up without changing anything. Select the file
469	with reporter information and click 'Next'. In the panel
470	you can choose to update reporter information for already
471	stored reporters. Click 'Next'. Set the job name and click
472	'Finish' to start the import. A progress report will be
473	displayed. It is safe to close this page, the job
474	will finish anyway. </p>
475
476	<p>In some cases the reporter annotation file from
477	Affymetrix fails to describe all probe sets on the chip,
478	you may get a message like <i>Error: Unable to import root
479	bioassay. Item not found:
480	Reporter[externalId=AFFX-2315060]</i>. In this case you
481	have to fall back to importing the probe set information
482	using the CDF file, simply do</p>
483
484	<p>Import the reporters by choosing 'View' -> 'Reporters'
485	and the clicking on 'Import...'. Click 'Next' without
486	changing the 'auto detect' settings. Supply the CDF file
487	name in the next dialog, click 'Next'. Start the import by
488	clicking 'Next' in the parameter dialog. This will add the
489	missing probe sets without changing existing probe
490	sets. The new probe sets will not have any annotations
491	associated with them since the CDFs do not contain such
492	information.</p>
493	</li>
494
495	<li>
496	<p> <b> Import reporter maps </b> <br> Performing an
497	import of array designs is only needed once for every
498	design added into BASE. Remember to share your designs
499	(normally to group 'Everyone'). </p>
500
501	<p> To create a new design, choose 'Array LIMS' -> 'Array
502	designs' and click on the 'New...' tab. Select a name for
503	the design. If it is an Affymetrix design, mark the 'Affy
504	chip' box and select a 'CDF file' (make sure that also the
505	CDF file is shared). Hint: For Affymetrix design you
506	should choose the name to be the same as the cdf file
507	name. If you are importing something else than Affymetrix
508	designs make sure that you unmark the 'Affy chip'
509	box. Finalize with 'Save'. For Affymetrix the import is
510	done, whereas Genepix have to perform reporter map
511	import. </p>
512
513	<p> <i>Genepix reporter map import</i> <br> Click on the
514	newly created array design, and click on the 'Import...'
515	tab. In the pop up, click 'Next'. Browse for the reporter
516	map file and click 'Next'. In the following dialogue you
517	can specify how to treat errors encountered. The default
518	is 'fail' which may be too restrictive, trial and error is
519	the way to go here for now. If you have trouble importing
520	try 'skip' for 'Default error handling' and 'Reporter not
521	found'. You can safely leave the 'Character set' as it
522	is. </p>
523	</li>
524
525	</ol>
526	</li>
527
528	<li>
529	<a name="user"></a>
530	<h2>User tasks</h2>
531	</li>
532
533	<p> A normal user is not allowed to add array design, reporter
534	information, and a lot of other information to BASE. The reason
535	for this is that a lot of information should only exist as one
536	copy in the database. For example, reporters should only exist in
537	one copy because everyone uses the same reporters. There is no
538	need to store several copies of the same array design. </p>
539
540	<p> A user will normally upload experimental data to BASE for
541	import into the database. To be able to import the data, the
542	array design used must be available in BASE at import time. If
543	the array design is not available, a user with the proper
544	credential must add the array design to BASE. </p>
545
546	<ol type=a>
547
548	<li>
549	<p> <b> Create a new Project </b> <br> Go to 'View' ->
550	'Projects' and click on the 'New...' tab. Name the project and
551	save. In the projects listing page, click 'Set active' for the
552	new project. The selected project should be displayed on top
553	right as 'Active project'. Selecting an active project will
554	influence the behaviour of BASE. Only information related to
555	the active project will be displayed and items created will
556	automatically be shared to the active project. </p>
557
558	<p> The display of items shared to the active project only
559	requires that the 'view/presets' pull-down menu options are
560	properly set. In 'view/preset' you can select what should be
561	displayed, and if only 'In current project' is selected then
562	only information shared to a project will be shown. </p>
563	</li>
564
565	<li>
566	<p> <b>Create raw bioassays</b> <br> Upload your raw data
567	files. Go to 'View' -> 'Raw bioassays' and click on the
568	'New...' tab. Name the raw bioassay. Select 'Raw data
569	type'. Select the 'Array design', if you cannot see see
570	designs in the pop-up the make sure that the 'view/presets'
571	pull-down menu has 'Shared to me' marked and select appropriate
572	design. Select 'CEL file' if you create an Affymetrix raw
573	bioassay. You can leave the rest untouched. Redo for all raw
574	data files. (Yes a batch creator would be nice.) </p>
575	</li>
576
577	<li>
578	<p> <b>Create a new experiment</b> <br> Go to 'View' ->
579	'Experiments' and click on the 'New...' tab. Name the
580	experiment. Click 'Add raw bioassays...' button and mark the
581	raw bioassays to add to the experiment and click
582	'Ok'. Finalize with clicking the 'Save' button. </p>
583	</li>
584
585	<li>
586	<p> <b>Analysing an experiment step I</b> <br> Select the
587	newly created experiment and in the the experiment window
588	select the 'Bioassay sets' tab. There are no bioassay sets and
589	you must create a root bioassay set. This step is different
590	depending on what data is used in the experiment but note that
591	this paragraph ends with information valid for all type of
592	data. </p>
593
594	<p> <i>Affymetrix</i> <br> Click on the 'New root bioassay set
595	...' tab and select the RMAExpress plug-in in the pop up. (If
596	the plug-in does not appear as an option, the installation of
597	the plug-in has failed. Please refer
598	to <a href=#RMAExpressInstall>Installing RMAExpress plug-in
599	for BASE</a>.) Click on the 'Next' button and in the new
600	window set the name for the bioassay set and select the
601	bioassays you want to include for this analysis. Click
602	'Next'. In the next pop up you can change information if you
603	like but it is not necessary, when done click on 'Finish' to
604	add the analysis job to the job queue. The job will start
605	automatically when the server as an open slot for it. The last
606	pop up window will report progress on the job. </p>
607
608	<p> <i>All flavours</i> <br> You can safely close the job
609	progress window, the server will run the job anyway. If you
610	want to monitor the progress of the job after closing the job
611	window just go to 'View' -> 'Jobs' and locate your job in the
612	list and select it. When the job is done the new bioassay set
613	will be added to the list of bioassay set for the
614	experiment. Unfortunately the list does not auto update so you
615	need to click on the 'Properties' tab and the on the 'Bioassay
616	sets' tab to refresh the list of bioassay sets. </p>
617	</li>
618
619	<li>
620	<p> <b>Analysing an experiment step II</b> <br> Now you should
621	have the first bioassay set. In the list of bioassay sets you
622	will have a number of icons attached that will start
623	tools. The set of tools available for bioassay sets is context
624	sensitive, <i>i.e.</i>, only tools that can handle the
625	bioassay sets are shown. At the time of writing of this
626	document there are four icons available; A simple plot tool,
627	experiment explorer, a filtering tool, and a plug-in
628	runner. You have to try these on your own. The aim with this
629	paragraph is to highlight the fact that you can export the
630	bioassay set data for use outside BASE. </p>
631
632	<p> To export bioassay set data select a bioassay set. In the
633	bioassay set presentation window you will have an export
634	button just below the tabs on the top. (There is also an
635	export button for the Sub analysis tree which may be confusing
636	at first, but his button will export information about the
637	analysis tree.) So, assuming you select the proper export
638	button you will be given a list of different export
639	formats. The list of supported exports depends on what plug-ins
640	are added to the server, but there should at least be an
641	export to <a href=http://www.tm4.org/mev.html>MultiExperiment
642	Viewer</a> maintained by the Dana Farber Cancer Institute. </p>
643	</li>
644
645	</ol>
646
647	</ol>
648
649	<p> This concludes this short document on how to get going with
650	BASE. We have not covered how to use the LIMS part of BASE, nor
651	annotations, and much more. We are creating documentation, please
652	browse <a href="https://base.thep.lu.se/">BASE web site</a> for the
653	latest available documents. </p>
654
655	</body>
656	</html>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/doc/historical/user/getting_started.html @ 7982

Download in other formats: