Changeset 3392
- Timestamp:
- May 28, 2007, 11:21:31 AM (16 years ago)
- Location:
- trunk/doc/src/docbook/userdoc
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/userdoc/annotations.xml
r3382 r3392 405 405 406 406 <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 507 411 </sect1> 508 412 -
trunk/doc/src/docbook/userdoc/experiments.xml
r3362 r3392 694 694 <sect2 id="experiments_analysis.magexport"> 695 695 <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> 697 866 </sect2> 698 699 867 </sect1>
Note: See TracChangeset
for help on using the changeset viewer.