Changeset 5795

Timestamp:

Oct 10, 2011, 12:08:12 PM (11 years ago)

Author:

Nicklas Nordborg

Message:

References #1590: Documentation cleanup

New and updated screenshots for chapter 8-14.

Location:

trunk

Files:

• doc/src/docbook/figures/annotate.png (modified) (previous)
• doc/src/docbook/figures/annotationtype_categories.png (added)
• doc/src/docbook/figures/annotationtype_items.png (modified) (previous)
• doc/src/docbook/figures/annotationtype_options.png (modified) (previous)
• doc/src/docbook/figures/annotationtype_units.png (modified) (previous)
• doc/src/docbook/figures/edit_annotationtype.png (modified) (previous)
• doc/src/docbook/figures/edit_datafiletype.png (modified) (previous)
• doc/src/docbook/figures/edit_hardware.png (modified) (previous)
• doc/src/docbook/figures/edit_platform.png (modified) (previous)
• doc/src/docbook/figures/edit_platformfiletypes.png (modified) (previous)
• doc/src/docbook/figures/edit_protocol.png (modified) (previous)
• doc/src/docbook/figures/edit_software.png (modified) (previous)
• doc/src/docbook/figures/edit_subtype.png (added)
• doc/src/docbook/figures/edit_subtype_filetypes.png (added)
• doc/src/docbook/figures/inherit_annotations.png (modified) (previous)
• doc/src/docbook/figures/job_properties.png (added)
• doc/src/docbook/figures/protocol_parameters.png (modified) (previous)
• doc/src/docbook/figures/reporter-1.png (modified) (previous)
• doc/src/docbook/figures/reporter-2.png (modified) (previous)
• doc/src/docbook/figures/reporterlist-1.png (modified) (previous)
• doc/src/docbook/figures/reporterlist-merge.png (added)
• doc/src/docbook/figures/reportertype.png (modified) (previous)
• doc/src/docbook/figures/select_files.png (added)
• doc/src/docbook/user/annotations.xml (modified) (8 diffs)
• doc/src/docbook/user/jobs.xml (modified) (10 diffs)
• doc/src/docbook/user/platforms.xml (modified) (5 diffs)
• doc/src/docbook/user/protocols.xml (modified) (2 diffs)
• doc/src/docbook/user/reporters.xml (modified) (12 diffs)
• doc/src/docbook/user/subtypes.xml (modified) (4 diffs)
• doc/src/docbook/user/wares.xml (modified) (1 diff)
• lib/docbook/custom-styles/docbook/plain/admonitions/tip.png (modified) (previous)

trunk/doc/src/docbook/user/annotations.xml

@@ -59 +59 @@
       <emphasis>Protocols</emphasis>
       and
-      <emphasis>Bioassay sets</emphasis>
+      <emphasis>Bioassay sets</emphasis>.
     </para>
 
@@ -138 +138 @@
     <para>
       The <guilabel>Edit annotation type</guilabel> window is opened in a
-      pop-up. It contains four different tabs.
+      pop-up. It contains several tabs.
     </para>
   
@@ -176 +176 @@
             database. This value can be used by tools that
             need to update annotation types in BASE from external
-            sources. The value does not have to be unique.
+            sources. The value does not have to be unique and is not
+            used by BASE.
             </para>
           </listitem>
@@ -224 +225 @@
           <listitem>
             <para>
-              A short textual description of the
+              A short textual description 
               to clarify the usage.
             </para>
@@ -405 +406 @@
           <para>
           If the annotation type has been marked as a 
-          <guilabel>Protocol</guilabel> parameter, these settings are
+          <guilabel>Protocol parameter</guilabel>, these settings are
           ignored, with one exception. If you wish to view parameter
           values in the list view for a specific item type you must select 
@@ -516 +517 @@
       <title>Categories</title>
     
+      <figure
+        id="annotations.figures.annotationtype.categories">
+        <title>Annotation type categories</title>
+        <screenshot>
+          <mediaobject>
+            <imageobject>
+              <imagedata
+                fileref="figures/annotationtype_categories.png" format="PNG" />
+            </imageobject>
+          </mediaobject>
+        </screenshot>
+      </figure>
+      
       <helptext external_id="annotationtype.edit.categories" 
         title="Categories">
@@ -534 +548 @@
           button to remove the selected categories.
         </para>
-          
+        
+        <tip>
+          <title>Create categories with the same name as item subtypes</title>
+          <para>
+            If you, for example, have defined multiple subtypes of extracts
+            (see <xref linkend="subtypes" />),
+            it usually so that some annotation types are only intended for
+            one subtype while some other annotation types are only intended
+            for the other subtype. If you create categories with the same name
+            as the item subtypes, BASE will automatically select the corresponding
+            category when annotating an extract with a subtype. This makes the interface
+            cleaner and easier to use since irrelevant annotation types are hidden.
+            Note that it is possible for annotations to be part of more than one
+            category so it is also possible to define annotation types that are
+            intended for all types of extracts by including them in both categories.
+          </para>
+        </tip>
+        
         <seeother>
           <other external_id="annotationtype.edit">Properties</other>
@@ -544 +575 @@
   </sect1>
   
-  <sect1 id="annotations.categories">
-    <?dbhtml filename="categories.html" ?>
-    <title>Annotation type categories</title>
-    
-    <para>
-      <guilabel>Annotation Type Categories</guilabel>
-      allow grouping of related Annotation Types, based on
-      users requirements.
-    </para>
-    
-    <para>
-      For managing categories go to 
-      <menuchoice>
-        <guimenu>Administrate</guimenu>
-        <guimenuitem>Types</guimenuitem>
-          <guisubmenu>Annotation Type categories</guisubmenu>
-        </menuchoice>.
-    </para>
-
-    <example id="annotation_types.example.atcategory">
-      <title>Annotation category examples</title>
-      
-      <para>
-        <itemizedlist>
-        <listitem>
-          <para>
-          A category <userinput>Hematology Descriptors</userinput>
-          could be created to group together annotation types such as
-          <userinput>Lymphocyte count</userinput> and 
-          <userinput>Hematocrite</userinput>
-          </para>
-        </listitem>
-        
-        <listitem>
-          <para>
-          A category <userinput>Plasma Clinical Descriptors</userinput>
-          could be created to group together annotation types such as
-          <userinput>ALT activity (UI/mL)</userinput> and 
-          <userinput>LDH activity (UI/mL)</userinput>
-          </para>
-        </listitem>
-        </itemizedlist>
-      </para>
-    </example>
-    
-    <tip>
-      <para>
-      If you use the same name for a category as for an item subtype (see <xref linkend="subtypes" />)
-      the annotations in this category will be selected by default when editing an item item
-      by that subtype. This can be useful when you have two or more subtypes of the same
-      main item type and a different set of annotations that should be used on each subtype.
-      For example, <emphasis>Labeled extract</emphasis> and <emphasis>Library</emphasis>
-      are subtypes of <emphasis>Extract</emphasis>, which probably have different annotation
-      types.
-      </para>
-    </tip>
-    
-  </sect1>
-
   <sect1 id="annotations.annotating">
     <?dbhtml filename="annotating.html" ?>

trunk/doc/src/docbook/user/jobs.xml

@@ -44 +44 @@
   </para>
 
-
-  <sect1 id="jobs.properties">
-    <title>Properties</title>
+  <para>
     Click on
     <menuchoice>
@@ -52 +50 @@
       <guimenuitem>Jobs</guimenuitem>
     </menuchoice>
-    to list your jobs.
-    <para>
+      to list your jobs.
       Details of a single job is displayed in a pop-up window. This window opens either if you
       click on a job's name from the list page of jobs or when a job configuration is
@@ -66 +63 @@
       </para>
     </helptext>
+    
+    <figure id="jobs.figures.properties">
+      <title>Job properties</title>
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="figures/job_properties.png" format="PNG" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+    </figure>
+    
     <helptext external_id="job.view.properties" title="Job properties">
       <para>
@@ -115 +124 @@
           <varlistentry>
             <term>
-              <optional>
                 <guilabel>Description</guilabel>
-              </optional>
             </term>
             <listitem>
@@ -123 +130 @@
                 A description of the job. Like the name-property it can be set in
                 the job configuration.
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term>
-              <guilabel>Type</guilabel>
-            </term>
-            <listitem>
-              <para>
-                The type of job, which is depending on the plug-in that is used. It
-                can be one of these five:
-                <itemizedlist>
-                  <listitem>Export</listitem>
-                  <listitem>Import</listitem>
-                  <listitem>Analysis</listitem>
-                  <listitem>Intensity</listitem>
-                  <listitem>Other</listitem>
-                </itemizedlist>
               </para>
             </listitem>
@@ -175 +164 @@
                   <listitem>
                     <para>
+                      <emphasis>Preparing</emphasis>
+                      - The job queue is preparing to executed the job.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
                       <emphasis>Executing</emphasis>
                       - The job is being executed.
@@ -191 +186 @@
                     </para>
                   </listitem>
-                  <listitem>
-                    <para>
-                      <emphasis>Preparing</emphasis>
-                      - The job queue is preparing to executed the job.
-                    </para>
-                  </listitem>
-                  <listitem>
+c               <listitem>
                     <para>
                       <emphasis>Aborting</emphasis>
@@ -205 +194 @@
                   </listitem>
                 </itemizedlist>
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term>
-              <guilabel>Status message</guilabel>
-            </term>
-            <listitem>
-              <para>
-                A message, given by the plug-in, with more information about the
-                status.
+                
+                This field will also display any messages from the plug-in while it
+                is running and the final message after it's completion.
               </para>
             </listitem>
@@ -344 +325 @@
         <listitem>
           <para>
-          Retry a failed job with different. This feeture is supported by most but not 
+          Retry a failed job with different parameters. This feeture is supported by most but not 
           all plug-ins. It is very useful when the failure is due to a misconfiguration
           and the job may succeed if it was configured differently.
@@ -374 +355 @@
       
     </helptext>
-  </sect1>
 </chapter>

trunk/doc/src/docbook/user/platforms.xml

@@ -37 +37 @@
       Affymetrix platform (as defined in BASE) uses CEL files for 
       raw data and CDF files for array design information.
-    </para>
-    
-    <para>
       The concept of a platform is also tightly coupled to the
       ability to keep data in files instead of importing it to 
@@ -48 +45 @@
     
     <para>
-      BASE comes pre-installed with two platforms; A generic platform
-      and the Affymetrix platform. Other platforms, such as Illumina,
+      BASE comes pre-installed with three platforms.
+    </para>
+    
+    <itemizedlist>
+      <listitem>
+        <para>
+        A generic platform that can be used with almost any
+        type of data that can be imported into the database from
+        simple column-based text files.
+        </para>
+      </listitem>
+    
+      <listitem>
+        <para>
+        The Affymetrix platform which keep data in CEL and CDF files
+        instead of importing into the database.
+        </para>
+      </listitem>
+      
+      <listitem>
+        <para>
+        A sequencing platform which uses GTF files to define array designs
+        and FPKM counts as raw data.
+        </para>
+      </listitem>
+    
+    </itemizedlist>
+      
+    <para>
+      Other platforms, such as Illumina,
       are available as non-core plug-in packages, see
       <xref linkend="resources.plugins" />. An administrator may
@@ -60 +85 @@
     </seeother>
     </helptext> 
-
-
 
     <para>
@@ -189 +212 @@
         <listitem>
           <para>
-            This checkbox will modify the required flag for the
-            selected file types.
+            Mark this checkbox to indicate that the file is required for
+            the platform.
           </para>
           
           <note>
             <para>
-            The requried flag is not a hard requirement. It is only
-            used for generating warnings when validating an experiment.
+            The requried flag is not enforced when creating items. It is 
+            used for generating warnings when validating an experiment and
+            can be checked by plug-ins that may need the file in order
+            to run.
             </para>
           </note>
           
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Allow multiple files</guilabel></term>
+        <listitem>
+          <para>
+            Mark this checkbox if it is possible to have more than one
+            file of the given type. In most cases, a single file is used,
+            but some platforms (for example Illumina) may split data into
+            multiple files.
+          </para>
         </listitem>
       </varlistentry>
@@ -285 +321 @@
         Make it possible to validate and extract metadata from attached files.
         This is done by extensions. Currently, BASE ships 
-        with extensions for CEL and CDF files, but the administrator may have installed
+        with extensions for CEL, CDF and GTF files, but the administrator may have installed
         extensions for other file types. See <xref linkend="extensions_developer.fileset_validator"/> 
         for more information about creating extensions.

trunk/doc/src/docbook/user/protocols.xml

@@ -124 +124 @@
         <seeother>
           <other external_id="protocol.edit.parameters">Protocol parameters</other>
+          <other external_id="annotations.edit">Annotations</other>
         </seeother>
       </helptext>
@@ -191 +192 @@
         <seeother>
           <other external_id="protocol.edit">Edit protocol</other>
-          <other external_id="annotations.edit">Annotations &amp; parameters</other>
+          <other external_id="annotations.edit">Annotations</other>
         </seeother>
       
       </helptext>
+      
+      <para>
+        The <guilabel>Annotations</guilabel> tab allows BASE users to use 
+        annotation types to refine protocol description. More about annotating items 
+        can be read in <xref linkend="annotations.annotating" />.
+      </para>
   </sect1>
 </chapter>

trunk/doc/src/docbook/user/reporters.xml

@@ -27 +27 @@
 <chapter id="reporters" chunked="0">
   <title>Reporters</title>
-  <sect1 id="reporters.introduction">
-    <title>Introduction</title>
+  
     <helptext external_id="reporter.view.properties" 
       title="About reporters">
@@ -45 +44 @@
     </para>
     </helptext>
-  </sect1>
   
   <sect1 id="reportertypes">
@@ -57 +55 @@
       and qualification defined during the array design
       specification.
-    </para>
-    </helptext>
-    
-    <para>
+      <nohelp>
       You can manage the reporter types by going to
       <menuchoice>
@@ -67 +62 @@
         <guisubmenu>Reporter types</guisubmenu>
       </menuchoice>.
+      </nohelp>
     </para>
+    </helptext>
     
     <figure
@@ -122 +119 @@
       <menuchoice>
         <guimenu>View</guimenu>
-        <guimenuitem>Reporter</guimenuitem>
+        <guimenuitem>Reporters</guimenuitem>
       </menuchoice> to view and manage the reporters.
     </para>
@@ -178 +175 @@
       </para>
       
-      <sect3 id="reporters.properties">
-        <title>Reporter properties</title>
-        
         <figure id="reporters.figures.properties">
           <title>Reporter properties</title>
@@ -245 +239 @@
           </seeother>
         </helptext>
-      </sect3>
-      
-      <sect3 id="reporters.extended_properties">
-        <title>Extended properties</title>
-        
+
         <figure id="reporters.figures.extended_properties">
           <title>Extended reporter properties</title>
@@ -295 +285 @@
           </seeother>
         </helptext>
-      </sect3>
     </sect2>
  
@@ -302 +291 @@
       <title>Deleting reporters</title>
       
-      <important>
+      <caution>
         <title>Deleted reporters cannot be restored</title>
         <para>
@@ -313 +302 @@
           confirm before the reporters are deleted.
         </para>
-      </important>
+      </caution>
       
       <para>
@@ -463 +452 @@
             should be included in the list. This option is only available
             when creating a new reporter list, not when editing an existing
-            list.
+            list. The default is to create a list with <emphasis>all</emphasis>
+            reporters that are in the current list. 
             </para>
           </listitem>
@@ -490 +480 @@
       </helptext>
 
+
+    <sect2 id="reporterlists.merge">
+      <title>Merging reporter lists</title>
+
+      <para>
+        It is possible to modify a reporter list by merging it with other reporter
+        lists. Go to the single-item view page for a reporter list. There should be
+        three buttons in the toolbar corresponding to three main merge variants:
+      </para>
+      
+      <itemizedlist>
+        <listitem>
+          <para>
+            <guilabel>Union:</guilabel> Add all reporters from 
+            the source lists to the destination list.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <guilabel>Intersection:</guilabel> Keep only reporters
+            that are present in all selected lists.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <guilabel>Complement:</guilabel> Keep only reporters that
+            are unique for the destination list.
+          </para>
+        </listitem>
+      </itemizedlist>
+      
+      <para>
+        All three buttons open up the same dialog with different default selections.
+      </para>
+
+      <figure
+        id="reporterlists.figures.merge">
+        <title>Merge reporter lists</title>
+        <screenshot>
+          <mediaobject>
+            <imageobject>
+              <imagedata fileref="figures/reporterlist-merge.png" format="PNG" />
+            </imageobject>
+          </mediaobject>
+        </screenshot>
+      </figure>
+
+      <helptext external_id="reporterlist.merge" 
+        title="Merge reporter lists">
+      
+        
+        <variablelist>
+          <varlistentry>
+            <term><guilabel>This list</guilabel></term>
+            <listitem>
+              <para>Shows the name of the current reporter list.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><guilabel>What to do</guilabel></term>
+            <listitem>
+              <para>
+                In this drop-down list you can select if you want to
+                <emphasis>add</emphasis>, <emphasis>keep</emphasis>
+                or <emphasis>remove</emphasis> reporters from the
+                selected list based on if a reporter is present in one
+                or all of some other reporter lists (selected below). 
+                The image to the right gives an overview what will 
+                happen for the currently selected alternatives. The
+                red-colored areas indicate which reporters that are
+                included in the final list. The white-colored areas 
+                indicate reporters that doesn't pass the filter and
+                are excluded from the final list.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><guilabel>Reporter lists</guilabel></term>
+            <listitem>
+              <para>
+                You will need to select at least one more list
+                to merge with.
+              </para>
+            </listitem>
+          </varlistentry>
+        
+        </variablelist>
+      
+
+      </helptext>
+    </sect2>
+
+
+
   </sect1>
 </chapter>

trunk/doc/src/docbook/user/subtypes.xml

@@ -53 +53 @@
       This feature can be a real time-saver when used together with project default items
       (see <xref linkend="project_permissions.project.defaults" />).
-      When creating new items (eg a biomaterial) BASE will search among the 
+      When creating new items (eg. a biomaterial) BASE will search among the 
       default items in the active project for protocols, hardware, software, 
       etc. and automatically select the best match based on the subtype of the new 
@@ -123 +123 @@
           the current subtype. The possible options depend on the which the
           main item type is. For example, for <emphasis>biosource</emphasis>
-          there are no other related subtypes, but <emphasis>physical bioassay</emphasis>
-          can have a related protocol and hardware subtype as well as a
-          related extract subtype.
+          there are no other related subtypes, but a <emphasis>derived bioassay</emphasis>
+          can have a related physical bioassay and extract as well as protocol, hardware and
+          software subtypes.
           </para>
         </listitem>
@@ -157 +157 @@
     <helptext external_id="itemsubtype.filetypes" title="File types">
       <para>
-        If the main item type for a subtype is a <emphasis>physical bioassay</emphasis>
-        or <emphasis>derived bioassay</emphasis> (which has support for linking
-        of data files) it is possible to select data file types 
+        If the main item type for a subtype is a <emphasis>derived bioassay</emphasis> 
+        (which has support for linking of data files) it is possible to select data file types 
         <nohelp>(see <xref linkend="platforms.datafiletypes"/>)</nohelp>
         that can be used for items of the given subtype. This is very similar to how
@@ -176 +175 @@
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><guilabel>Required</guilabel></term>
+        <listitem>
+          <para>
+            Mark this checkbox to indicate that the file is required for
+            all items of the given subtype.
+          </para>
+          
+          <note>
+            <para>
+            The requried flag is not enforced when creating items. It is 
+            used for generating warnings when validating an experiment and
+            can be checked by plug-ins that may need the file in order
+            to run.
+            </para>
+          </note>
+          
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Allow multiple files</guilabel></term>
+        <listitem>
+          <para>
+            Mark this checkbox if it is possible to have more than one
+            file of the given type. In most cases, a single file is used,
+            but some subtypes, for example Scan, may generate multiple images.
+          </para>
+        </listitem>
+      </varlistentry>
       
       <varlistentry>

trunk/doc/src/docbook/user/wares.xml

@@ -104 +104 @@
     
     <para>
-      A hardware is used in BASE to represent the software that is used to
+      A software item is used in BASE to represent the software that is used to
       process and analyze data outside of BASE. Analysis that is done inside
       BASE is usually represented as plug-ins.