source: trunk/doc/src/docbook/user/itemlists.xml @ 6811

Last change on this file since 6811 was 6811, checked in by Nicklas Nordborg, 7 years ago

References #1325: Lists of items

Added documentation about item lists.

File size: 19.5 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id$
7 
8  Copyright (C) 2015 Nicklas Nordborg
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<chapter id="itemlists" chunked="0">
28  <title>Item lists</title>
29 
30
31  <helptext external_id="itemlist.view.properties" title="Item lists">
32
33    <para>
34      Item lists are used for grouping items that are somehow related
35      (or not) into a single entity. Some typical use cases are to keep
36      track of biomaterial that is going to be processed in the lab or
37      to find raw data sets that are suitable to use in an experiment.
38    </para>
39   
40    <para>
41      A list may only contain members of a single type. The list below show
42      the item types that are currently supported. Support for other item types
43      may be added in the future.
44    </para>
45   
46    <itemizedlist>
47      <listitem><simpara>Biosource</simpara></listitem>
48      <listitem><simpara>Sample</simpara></listitem>
49      <listitem><simpara>Extract</simpara></listitem>
50      <listitem><simpara>Physical bioassay</simpara></listitem>
51      <listitem><simpara>Derived bioassay</simpara></listitem>
52      <listitem><simpara>Raw bioassay</simpara></listitem>
53    </itemizedlist>
54 
55    <para>
56      List membership is typically managed either manually, or with
57      the help of synchronization filters.
58    </para>
59
60    <seeother>
61      <other external_id="itemlist.edit">Edit item list</other>
62      <other external_id="itemlist.members">Manage list members manually</other>
63      <other external_id="itemlist.merge">Merge item lists</other>
64      <other external_id="itemlist.syncfilters">Synchronization filters overview</other>
65    </seeother>
66
67  </helptext>
68
69  <para>
70    To begin working with item lists go to the
71    <menuchoice>
72      <guimenu>View</guimenu>
73      <guimenuitem>Item lists</guimenuitem>
74    </menuchoice>. Click on &gbNew; to create a new item list.
75  </para>
76
77    <figure
78      id="itemlists.figures.editlist">
79      <title>Item list properties</title>
80      <screenshot>
81        <mediaobject>
82          <imageobject>
83            <imagedata
84              fileref="figures/edit_itemlist.png" format="PNG" />
85          </imageobject>
86        </mediaobject>
87      </screenshot>
88    </figure>
89   
90  <helptext external_id="itemlist.edit" 
91    title="Edit item list">
92   
93    <variablelist>
94      <varlistentry>
95        <term><guilabel>Name</guilabel></term>
96        <listitem>
97          <para>
98            The name of the item list.
99          </para>
100        </listitem>
101      </varlistentry>
102      <varlistentry>
103        <term><guilabel>Member type</guilabel></term>
104        <listitem>
105          <para>
106            The type of the list member items. This must be set
107            when the list is created and can't be changed later.
108          </para>
109        </listitem>
110      </varlistentry>
111      <varlistentry>
112        <term><guilabel>Subtype</guilabel> (or <guilabel>Raw data type</guilabel>)</term>
113        <listitem>
114          <para>
115            The suptype of items that are expected to be found
116            in the list. This is not enforced but should only
117            be considered as a hint to developers for
118            creating a better user experince. For example,
119            prefilling filters when selecting items. For item lists
120            containing raw bioassays a raw data type can be selected instead
121            of a subtype.
122          </para>
123        </listitem>
124      </varlistentry>
125      <varlistentry>
126        <term><guilabel>External ID</guilabel></term>
127        <listitem>
128          <para>
129            An external reference that may or may not be unique. Not used by BASE.
130          </para>
131        </listitem>
132      </varlistentry>
133      <varlistentry>
134        <term><guilabel>Modify members</guilabel></term>
135        <listitem>
136          <para>
137            If the <guilabel>Disable manual</guilabel> checkbox is selected, members can't
138            be manually added to or removed from the list. This also includes using the
139            merge functionality for creating unions, intersections, etc.
140          </para>
141          <para>
142            If the <guilabel>Disable synchronization filters</guilabel> checkbox is marked, members
143            can't be modified by synhronization filters. If both options are marked the
144            list is effectively locked for modifications.
145          </para>
146        </listitem>
147      </varlistentry>
148      <varlistentry>
149        <term><guilabel>Description</guilabel></term>
150        <listitem>
151          <para>
152            A description of the item list.
153          </para>
154        </listitem>
155      </varlistentry>
156   
157    </variablelist>
158   
159    <para>
160      Click on &gbSave; to save the item list.
161    </para>
162   
163    <note>
164      <title>Creating an item list from other list pages</title>
165
166      <para>
167        It is also possible to create a new item list directly from several other list pages.
168        For example, from the samples list page. Click on the <guibutton>New item list&hellip;</guibutton>
169        button. In this case, the popup dialog has an extra option:
170      </para>
171     
172      <variablelist>
173        <varlistentry>
174          <term><guilabel>Source items</guilabel></term>
175          <listitem>
176            <para>
177              Select one of the options to decide which items that should be
178              added as members to list. You can choose to either add only
179              the <guilabel>selected</guilabel> items, items on the
180              <guilabel>current page</guilabel> or <guilabel>all items</guilabel>
181              matching the current filter. In the latter case, the current filter
182              may also be saved as a synchronization filter.
183            </para>
184          </listitem>
185        </varlistentry>
186      </variablelist>
187     
188    </note>
189   
190    <seeother>
191      <other external_id="itemlist.view.properties">Item lists overview</other>
192    </seeother>
193
194  </helptext>
195
196  <sect1 id="itemlists.members">
197    <title>Manage list members manually</title>
198   
199    <helptext external_id="itemlist.members" title="Manage list members manually">
200    <para>
201      To manually manage the members go to the <guilabel>Members</guilabel> tab
202      on the single-item view page for the item list. Use the <guibutton>Add&hellip;</guibutton>
203      button to start adding members. This will open a regular list view in a popup
204      window. The only difference is that there are extra buttons at the bottom
205      of the page.
206    </para>
207   
208    <variablelist>
209      <varlistentry>
210        <term><guilabel>Add selected</guilabel></term>
211        <listitem>
212          <para>
213            This button will add all selected items in the popup to the
214            item list.
215          </para>
216        </listitem>
217      </varlistentry>
218      <varlistentry>
219        <term><guilabel>Add current page</guilabel></term>
220        <listitem>
221          <para>
222            This button will add all items that are displayed on the current
223            page to the item list.
224          </para>
225        </listitem>
226      </varlistentry>
227      <varlistentry>
228        <term><guilabel>Add all</guilabel></term>
229        <listitem>
230          <para>
231            This button will add all items that are matching the current
232            filter to the item list. If there is no filter on the table, all
233            items will be added to the item list.
234          </para>
235        </listitem>
236      </varlistentry>
237      <varlistentry>
238        <term><guilabel>Close</guilabel></term>
239        <listitem>
240          <para>
241            Closes the popup without adding any members to the item list.
242          </para>
243        </listitem>
244      </varlistentry>
245    </variablelist>
246   
247    <para>
248      Back on the members page for the item list, the new members should now appear
249      in the table. To remove members use the <guibutton>Remove&hellip;</guibutton> button.
250      This button will only remove members that has been selected.
251    </para>
252   
253    <seeother>
254      <other external_id="itemlist.view.properties">Item lists overview</other>
255    </seeother>
256   
257    </helptext>
258  </sect1>
259
260  <sect1 id="itemlists.merge">
261    <title>Merging lists</title>
262   
263    <helptext external_id="itemlist.merge" title="Merging lists">
264    <para>
265      From the <guilabel>Properties</guilabel> tab it is possible to
266      access the merge functions that can be used to add and/or remove
267      members with the help of other item lists. There
268      are three basic operations that all open the same popup dialog, but
269      with different options pre-selected.
270    </para>
271   
272    <variablelist>
273      <varlistentry>
274        <term><guibutton>Union&hellip;</guibutton></term>
275        <listitem>
276          <para>
277            For creating a list that is a union of the members in
278            several other lists.
279          </para>
280        </listitem>
281      </varlistentry>
282      <varlistentry>
283        <term><guibutton>Intersection&hellip;</guibutton></term>
284        <listitem>
285          <para>
286            For creating a list that is the intersection of members
287            of this list and several other list.
288          </para>
289        </listitem>
290      </varlistentry>
291      <varlistentry>
292        <term><guibutton>Complement&hellip;</guibutton></term>
293        <listitem>
294          <para>
295            For removing members from this list that
296            are not members in other lists.
297          </para>
298        </listitem>
299      </varlistentry>
300    </variablelist>
301   
302    <para>
303      In the popup dialog it is possible to create other combinations as well.
304      They are all illustrated with a figure to make it easier to understand
305      what the final result is going to be.
306    </para>
307
308    <nohelp>
309    <figure
310      id="itemlists.figures.merge">
311      <title>Merging lists</title>
312      <screenshot>
313        <mediaobject>
314          <imageobject>
315            <imagedata
316              fileref="figures/itemlist_merge.png" format="PNG" />
317          </imageobject>
318        </mediaobject>
319      </screenshot>
320    </figure>
321    </nohelp>
322   
323    <variablelist>
324      <varlistentry>
325        <term><guilabel>What to do</guilabel></term>
326        <listitem>
327          <para>
328            There are two selection lists that are used to describe how the
329            selected item lists should be merged. The illustration to the right
330            is automatically updated to give a schematic overview of the effects
331            of the current selection.
332            The first selection list have three options.
333          </para>
334          <para>
335            The <guilabel>Add items</guilabel> option will only add members to
336            this list. This creates a union-like merge operation.
337          </para>
338          <para>
339            The <guilabel>Keep items</guilabel> option will remove members
340            from this list depending on if they are members of the
341            other lists or not. This creates an intersection-like merge operation.
342          </para>
343          <para>
344            The <guilabel>Remove item</guilabel> option also remove members
345            from this list depending of if they are members of the other
346            lists or not. This creates a complement-like merge operation.
347          </para>
348        </listitem>
349      </varlistentry>
350   
351      <varlistentry>
352        <term><guilabel>Other lists</guilabel></term>
353        <listitem>
354          <para>
355            Before the merge operation can take place, you must select at
356            least one other item list containing members of the same type
357            as this item list.
358          </para>
359        </listitem>
360      </varlistentry>
361      </variablelist>
362     
363      <para>
364        Click on &gbOk; to perform the merge.
365      </para>
366     
367      <seeother>
368        <other external_id="itemlist.view.properties">Item lists overview</other>
369      </seeother>
370    </helptext>
371  </sect1>
372
373
374  <sect1 id="itemlists.syncfilters">
375    <title>Synchronization filters</title>
376
377
378    <helptext external_id="itemlist.syncfilters" title="Synchronization filters">
379      <para>
380        Synchronization filters are a powerful way of keeping an
381        item list synchronized with a predefined set of filter conditions.
382        It is possible to apply filters on any level in the parent/child chain
383        going from biosource to physical bioassays to raw bioassays.
384        For example:
385      </para>
386     
387      <itemizedlist>
388        <listitem>
389          <para>
390          Start by creating an empty item list that should contain
391          samples with subtype <emphasis>Blood</emphasis>.
392          </para>
393        </listitem>
394        <listitem>
395          <para>
396          Then add a filter that says that the parent biosource, which is
397          of subtype <emphasis>Patient</emphasis>, must have an annotation
398          <emphasis>Consent = Yes</emphasis>. This should make sure that you
399          only work with samples that you know you have permission to use.
400          </para>
401        </listitem>
402        <listitem>
403          <para>
404          Add another filter that says that a child extract, which is
405          of subtype <emphasis>RNA</emphasis>, must have an annotation
406          <emphasis>Quality &gt; 8</emphasis>. This should make sure that you
407          only work with samples that you know are of good quality.
408          </para>
409        </listitem>
410        <listitem>
411          <para>
412          Finally, add a filter that says that a child raw bioassay
413          must have an annotation <emphasis>Aligned &gt; 10,000,000</emphasis>.
414          This should make sure that you only work with samples that you
415          have good sequencing data from.
416          </para>
417        </listitem>
418       
419      </itemizedlist>
420     
421      <seeother>
422        <other external_id="syncfilter.edit">Edit synchronization filter</other>
423        <other external_id="itemlist.resync">Synchronizing the list</other>
424        <other external_id="itemlist.view.properties">Item lists overview</other>
425      </seeother>
426     
427    </helptext>
428   
429    <para>
430      To create a synchronization filter use the
431      <guibutton>Add filter&hellip;</guibutton> button on the item list view page.
432    </para>
433
434    <figure
435      id="itemlists.figures.syncfilter">
436      <title>Edit synchronization filter</title>
437      <screenshot>
438        <mediaobject>
439          <imageobject>
440            <imagedata
441              fileref="figures/edit_syncfilter.png" format="PNG" />
442          </imageobject>
443        </mediaobject>
444      </screenshot>
445    </figure>
446   
447    <helptext external_id="syncfilter.edit"
448      title="Edit synchronization filter">
449   
450      <variablelist>
451      <varlistentry>
452        <term><guilabel>Name</guilabel></term>
453        <listitem>
454          <para>
455            Give the filter a descriptive name to make it easier to know what it does.
456          </para>
457        </listitem>
458      </varlistentry>
459      <varlistentry>
460        <term><guilabel>Disabled</guilabel></term>
461        <listitem>
462          <para>
463            A disabled filter is not used when synchronizing the list members.
464            This feature is useful when searching for problems.
465          </para>
466        </listitem>
467      </varlistentry>
468      <varlistentry>
469        <term><guilabel>Filter</guilabel></term>
470        <listitem>
471          <para>
472            This section defines the filter. In the first row you must select
473            if the filter should be used for finding items on the
474            <guilabel>same level</guilabel> as the members in the list
475            or for finding <guilabel>Parent items</guilabel> or <guilabel>Child items</guilabel>.
476            Note that some options may be missing if the item list should contain members
477            that are already at the top or bottom of the parent/child chain.
478          </para>
479          <para>
480            If the parent or child item option is selected from the first list,
481            a second list allows you to specify the type of the parent or child
482            item. This list should only contain item types that are relevant as
483            seen from the starting point. For example, if the item list contain samples
484            the only types of parent items are other samples or biosources.
485          </para>
486          <para>
487            The last option allows you specify if a parent or child
488            <guilabel>must exist</guilabel> or if it <guilabel>must not exist</guilabel>.
489            The latter option is usful when searching for samples that has failed in some
490            step in the processing (so that no child item has been registered).
491          </para>
492          <para>
493            The actual filter is displayed below the selection list. It is
494            typically empty to begin with. Use the icon to the right to open
495            a popup dialog containing a list view listing the items that you
496            want to filter on. Manipulate this list view by adding filters
497            and then click on <guibutton>Ok</guibutton> when you are done. The
498            current list filter is saved to the synchronization filter and is
499            displayed in the dialog.
500          </para>
501        </listitem>
502      </varlistentry>
503      <varlistentry>
504        <term><guilabel>Description</guilabel></term>
505        <listitem>
506          <para>
507            You may want to add a more detailed description of what the
508            filter does.
509          </para>
510        </listitem>
511      </varlistentry>
512      </variablelist>
513   
514      <para>
515        Click on &gbSave; to save the filter. The view page should automatically
516        be updated and will most likely display a warning that the list is out of
517        sync. You can ignore this warning and add more synchronization filters.
518      </para>
519   
520      <seeother>
521        <other external_id="itemlist.syncfilters">Synchronization filters overview</other>
522        <other external_id="itemlist.resync">Synchronizing the list</other>
523        <other external_id="itemlist.view.properties">Item lists overview</other>
524      </seeother>
525    </helptext>
526   
527    <para>
528      When all filters has been created click on the <guibutton>Re-sync&hellip;</guibutton> button
529      to start the synchronization process.
530    </para>
531   
532    <figure
533      id="itemlists.figures.resync">
534      <title>Synchronizing the list</title>
535      <screenshot>
536        <mediaobject>
537          <imageobject>
538            <imagedata
539              fileref="figures/itemlist_resync.png" format="PNG" />
540          </imageobject>
541        </mediaobject>
542      </screenshot>
543    </figure>
544   
545    <helptext external_id="itemlist.resync"
546      title="Synchronizing the item list">
547   
548      <variablelist>
549      <varlistentry>
550        <term><guilabel>Sync options</guilabel></term>
551        <listitem>
552          <para>
553            The <guilabel>Full</guilabel> option will both add members to and remove
554            members from the list so that all items are matching the current filters.
555          </para>
556          <para>
557            The <guilabel>Add only</guilabel> option will only add members to
558            the list. The new members are those matching the current filters that
559            are not already in the list. Existing members that doesn't match
560            the filters are not removed.
561          </para>
562          <para>
563            The <guilabel>Remove only</guilabel> option will only remove members from
564            the list. The removed members are those that no longer match the filters.
565            New items that are found to match the filters are not added to the list.
566          </para>
567        </listitem>
568      </varlistentry>
569      <varlistentry>
570        <term><guilabel>Subtype</guilabel> (or <guilabel>Raw data type</guilabel>)</term>
571        <listitem>
572          <para>
573            This option is only enabled if a subtype or raw data type has been selected for
574            the list. It adds an extra "virtual" synchronization filter
575            that only matches items of the specified type.
576          </para>
577        </listitem>
578      </varlistentry>
579      </variablelist>
580 
581      <para>
582        Click on &gbOk; to start the synchronization process. It is started in the
583        background and a progress bar will show the ongoing progress. Note that
584        closing the progress window will not abort the synchronization.
585      </para> 
586     
587      <seeother>
588        <other external_id="itemlist.syncfilters">Synchronization filters overview</other>
589        <other external_id="itemlist.view.properties">Item lists overview</other>
590      </seeother>
591    </helptext>
592   
593  </sect1>
594 
595 
596</chapter>
Note: See TracBrowser for help on using the repository browser.