Changeset 3392


Ignore:
Timestamp:
May 28, 2007, 11:21:31 AM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #534 and #546. Moved info about Tab2Mage to Experiments and analysis chapter.

Location:
trunk/doc/src/docbook/userdoc
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/userdoc/annotations.xml

    r3382 r3392  
    405405
    406406    <sect1 id="annotations.bestpractices">
    407         <title>Annotation Type Best Practices and Tab2mage Export Function functionality</title>
    408         <sect2 id="annotations.bestpractices.whattab2mage">
    409             <title>What is Tab2mage format ?</title>
    410             <para>
    411                 <ulink url="http://tab2mage.sourceforge.net/">Tab2mage format</ulink> is a
    412                 tab-delimited format veted by <ulink url="http://www.ebi.ac.uk/microarray/">EBI's
    413                     ArrayExpress</ulink> repository for submission microarray data.</para>
    414             <para>tab2mage format has been chosen by BASE2 to provide an easy way for data
    415                 deposition to public repository when submitting a manuscript and publishing
    416                 experimental data.</para>
    417             <para>BASE2 can export microarray experiments in tab2mage format thanks to a dedicated
    418                 export plugin, for more information see <xref
    419                     linkend="experiments_analysis.magexport"/></para>
    420             <para>However, it is important to understand that for the plugin to work, information
    421                 recorded in BASE2 should be formatted following a small number of rules. Failing to
    422                 do so may impair the possibility of exporting to ArrayExpress.</para>
    423         </sect2>
    424         <sect2 id="annotations.bestpractices.howtab2mage">
    425             <title>How tab2mage format specifications affect data annotation in BASE2 ?</title>
    426             <para>BASE2 has been engineered to closely map the MIAME concepts and a number of BASE2
    427                 entities can be mapped directly to tab2mage elements. However, since MIAME is
    428                 focused on microarray processing workflow, information about the biological sample
    429                 is down to the user. To accomodate the annotation needs of users, BASE2 provides a
    430                 mechanism that allows annotation customization to meet user specific requirements.
    431                 BASE allows to create annotation type for quantitative annotation and qualitative
    432                 annotation </para>
    433 
    434             <sect3 id="annotations.bestpractices.howtab2mage.characs">
    435                 <title>Biomaterial annotation in Tab2mage format</title>
    436                 <para>Tab2mage specifications only allow "BioSource" items to be annotated with
    437                     "BioMaterialCharacteristics".</para>
    438                 <warning>
    439                     <para>All BASE2 Annotation Types used to annotate at the level of "Sample" and
    440                         "Extract" items will be lost during the export in tab2mage format in order
    441                         to comply with ArrayExpress Tab2mage parser. </para>
    442                 </warning>
    443                 <note>
    444                     <para> In the context of data exchange between BASE2 instances, the export
    445                         function can be altered to allow attachement of Characteristics to items
    446                         other than <guilabel>BioSource</guilabel>, therefore avoiding loss of
    447                         information. </para>
    448                 </note>
    449                 <para/>
    450             </sect3>
    451             <sect3 id="annotations.bestpractices.howtab2mage.units">
    452                 <title>Reporting Units in Tab2mage Format</title>
    453                 <para>To associate Unit to BASE2 Annotation Types and remain compatible with
    454                     Tab2mage specifications, users need to adhere to the following convention:</para>
    455                 <para>annotation_type_name(unit_name) as in "body mass(kg)" or
    456                     "concentration(mg/ml)"</para>
    457                 <warning>
    458                     <para>Only one unit can be specified at any one time for any given Annotation
    459                         Type. In order to enable tab2mage support, it might be necessary to declare
    460                         several related Annotation Type in order to report similar kind of
    461                         information but expressed in a different unit. Specifying Age for instance
    462                         is a good example on how to deal with such cases: One should create several
    463                         related Annotation Types e.g. Age(week), Age(year) or Age(month) as those
    464                         variations maybe be necessary when reporting the age of a mouse or the age
    465                         of a human volunteer. </para>
    466                 </warning>
    467                 <para/>
    468             </sect3>
    469             <sect3 id="annotations.bestpractices.howtab2mage.parameters">
    470                 <title>Declaring Protocol Parameters</title>
    471                 <para>In order to ensure MIAME compliance, Tab2mage specifications cater for
    472                     reporting Parameters attached to Protocols and all parameters attached to a
    473                     protocol should be declared in the protocol section of a tab2mage file.</para>
    474                 <para>In BASE2 terms, Tab2mage elements such as 'BioMaterialCharacteristics',
    475                     'Parameter' or 'FactorValues' are all AnnotationTypes. But, it is necessary to
    476                     flag those Annotations Types meant to be used as Protocol Paramaters as such so
    477                     that they can identified by the Tab2mage exporter and handled appropriately.</para>
    478                 <para>Note that doing so restricts their use to Protocol only.</para>
    479                 <warning>
    480                     <para>It is not possible to use the same AnnotationType Temperature for
    481                         reporting a patient body temperature (which is a 'Biomaterial
    482                         Characteristic' ) and hybridization temperature (which is a Protocol
    483                         Parameter). Hence it will be necessary to declare 2 distinct annotation
    484                         types: </para>
    485                 </warning>
    486                 <para>-Annotation Type to be used as 'BioSource characteristics': body temperature
    487                     (degree_C)</para>
    488                 <para>-Annotation Type to be used as 'Protocol Parameter': hybridization
    489                     temperature(degree_C)</para>
    490                 <para/>
    491 
    492             </sect3>
    493             <sect3 id="annotations.bestpractices.howtab2mage.expfact">
    494                 <title>Declaring Experimental Factors </title>
    495                 <para>It is a MIAME requirement to identify 'Experimental Variables' when submitting
    496                     data to ArrayExpress (provided the study is an intervention study). Therefore,
    497                     BASE2 users willing to use the tab2mage export function will have to declare
    498                     Experimental Factors using the Annotation Types, the inherited annotation
    499                     mechanisms and the Experimental Factor Tag available from the
    500                         <guilabel>Experiment</guilabel> section. For more information about
    501                         <guilabel>inherited annotation</guilabel> please refer to <xref
    502                         linkend="annotations.inherited"/> and to the Experiment section <xref
    503                         linkend="experiments_analysis"/></para>
    504                 <para/>
    505             </sect3>
    506         </sect2>
     407        <title>Best Practices and Tab2Mage Export functionality</title>
     408       
     409        See <xref linkend="experiments_analysis.magexport" />.
     410       
    507411    </sect1>
    508412

  • trunk/doc/src/docbook/userdoc/experiments.xml

    r3362 r3392  
    694694  <sect2 id="experiments_analysis.magexport">
    695695    <title>Tab2Mage export</title>
    696     <para>TODO</para>
     696    <para>
     697      <ulink url="http://tab2mage.sourceforge.net/"
     698      >Tab2Mage format</ulink> is a tab-delimited format veted by
     699      <ulink url="http://www.ebi.ac.uk/microarray/"
     700      >EBI's ArrayExpress</ulink>
     701      repository for submission microarray data.
     702      Tab2Mage format has been chosen by BASE to provide an
     703      easy way for data deposition to public repository when
     704      submitting a manuscript and publishing experimental
     705      data.
     706    </para>
     707     
     708    <para>
     709      BASE2 has been engineered to closely map the MIAME
     710      concepts and a number of BASE2 entities can be mapped
     711      directly to Tab2Mage elements. However, since MIAME is
     712      focused on microarray processing workflow, information
     713      about the biological sample is down to the user. To
     714      accomodate the annotation needs of users, BASE2 provides
     715      a mechanism that allows annotation customization to meet
     716      user specific requirements. BASE allows to create
     717      annotation type for quantitative annotation and
     718      qualitative annotation
     719    </para>     
     720
     721    <para>
     722      BASE2 can export an experiment to Tab2Mage
     723      format thanks to a dedicated export plug-in.
     724      For the plug-in to work, it is important to understand that
     725      information recorded in BASE should be
     726      formatted following a small number of rules. Failing to
     727      do so may impair the possibility of exporting to
     728      ArrayExpress.
     729    </para>
     730   
     731    <note>
     732      <para>
     733      The Tab2Mage export plug-in has not yet been included in the main
     734      distribution. Hopefully, it will appear in the next (2.4) release.
     735      </para>
     736    </note>
     737
     738    <sect3 id="experiments_analysis.magexport.annotations">
     739      <title>Biomaterial annotations</title>
     740      <para>
     741        Tab2Mage specifications only allow <emphasis>BioSource</emphasis>
     742        items to be annotated with <emphasis>BioMaterialCharacteristics</emphasis>.
     743      </para>
     744      <warning>
     745        <para>
     746          All BASE2 Annotation Types used to annotate at
     747          the level of <emphasis>Sample</emphasis> and
     748          <emphasis>Extract</emphasis> items will
     749          be lost during the export in Tab2Mage format in
     750          order to comply with the ArrayExpress Tab2Mage
     751          parser.
     752        </para>
     753      </warning>
     754      <note>
     755        <para>
     756          In the context of data exchange between BASE
     757          instances, the export function can be altered to
     758          allow attachement of annotations to items
     759          other than biosources, therefore avoiding loss of
     760          information.
     761        </para>
     762      </note>
     763    </sect3>
     764
     765    <sect3 id="experiments_analysis.magexport.units">
     766      <title>Annotation units</title>
     767      <para>
     768        To associate units to BASE2 annotation types and
     769        remain compatible with Tab2Mage specifications,
     770        users need to adhere to the following convention:
     771      </para>
     772      <para>
     773        <userinput>annotation_type_name(unit_name)</userinput> as in
     774        <userinput>body mass(kg)</userinput> or <userinput>concentration(mg/ml)</userinput>
     775      </para>
     776      <warning>
     777        <para>
     778          Only one unit can be specified at any one time
     779          for any given annotation type. In order to
     780          enable Tab2Mage support, it might be necessary
     781          to declare several related Annotation Type in
     782          order to report similar kind of information but
     783          expressed in a different unit. Specifying Age
     784          for instance is a good example on how to deal
     785          with such cases: One should create several
     786          related annotation types e.g. <userinput>Age(week)</userinput>,
     787          <userinput>Age(year)</userinput> or <userinput>Age(month)</userinput>
     788          as those variations maybe be necessary when reporting the age of a
     789          mouse or the age of a human volunteer.
     790        </para>
     791      </warning>
     792    </sect3>
     793    <sect3
     794      id="experiments_analysis.magexport.parameters">
     795      <title>Protocol parameters</title>
     796      <para>
     797        In order to ensure MIAME compliance, Tab2Mage
     798        specifications cater for reporting parameters
     799        attached to protocols and all parameters attached to
     800        a protocol should be declared in the protocol
     801        section of a Tab2Mage file.
     802      </para>
     803     
     804      <para>
     805        In BASE2 terms, Tab2Mage elements such as
     806        <emphasis>BioMaterialCharacteristics</emphasis>,
     807        <emphasis>Parameter</emphasis> or
     808        <emphasis>FactorValues</emphasis> are all annotation
     809        types. But, it is necessary to flag those annotations types meant to
     810        be used as protocol parameters as such so that they
     811        can identified by the Tab2Mage exporter and handled
     812        appropriately.
     813      </para>
     814
     815      <warning>
     816        <para>
     817          It is not possible to use the same
     818          annotation type <emphasis>Temperature</emphasis> for reporting a
     819          patient body temperature (which is a
     820          <emphasis>Biomaterial Characteristic</emphasis>) and hybridization
     821          temperature (which is a protocol parameter).
     822          Hence it will be necessary to declare 2 distinct
     823          annotation types:
     824        </para>
     825      </warning>
     826     
     827      <itemizedlist>
     828      <listitem>
     829        <para>
     830        Annotation type to be used as <emphasis>BioSource
     831          characteristics</emphasis>: <userinput>body temperature (degree_C)</userinput>
     832        </para>
     833      </listitem>
     834      <listitem>
     835        <para>
     836        Annotation type to be used as <emphasis>protocol parameter</emphasis>:
     837        <userinput>hybridization temperature (degree_C)</userinput>
     838        </para>
     839      </listitem>
     840      </itemizedlist>
     841    </sect3>
     842         
     843    <sect3 id="experiments_analysis.magexport.factors">
     844      <title>Experimental factors</title>
     845      <para>
     846        It is a MIAME requirement to identify <emphasis>Experimental
     847        Variables</emphasis> when submitting data to ArrayExpress
     848        (provided the study is an intervention study).
     849        Therefore, BASE2 users willing to use the Tab2Mage
     850        export function will have to declare <emphasis>Experimental
     851        Factors</emphasis> using the the <guilabel>Experimental Factor</guilabel>
     852        tab available when editing experiments. See
     853        <xref linkend="experiments_analysis.experiment.factors" /> for more information.
     854      </para>
     855     
     856      <para>
     857        Values for the experimental factors are take from annotations.
     858        The annotation must exist at the raw bioassay level, which
     859        probably means that you have to inherit the annotation from
     860        some other item, for example, a biosource or a sample.
     861        It is also possible to use a protocol parameter as
     862        experimental factor. See <xref linkend="annotations" /> for
     863        more information about annotations.
     864      </para>
     865    </sect3>
    697866  </sect2>
    698 
    699867</sect1>
Note: See TracChangeset for help on using the changeset viewer.