Masterarbeit, Heidi Lischer

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PGDSpider Manual ======
{{splashscreen.png|}}\\
PGDSpider version 2.0.1.6 (May 2012)

\\
**[[http://www.cmpg.unibe.ch/software/PGDSpider/#Download_and_Installation_Instructions|PGDSpider download]]**
\\
[[http://www.cmpg.unibe.ch/software/PGDSpider/changelog.txt|PGDSpider - changelog]]
\\
\\
[[PGDSpider|PGDSpider program description]]
\\
[[PGD|Definition of PGD fileformat]]
\\
\\




===== System requirements: =====
PGDSpider is written in Java and therefore platform independent, but SUN Java 1.6 RE (or a newer version) has to be installed. Java6 RE can be downloaded under following link:[[http://www.oracle.com/technetwork/java/javase/downloads/index.html]]\\
 
\\

===== Java Web Start: =====
Additionally we provide the possibility to download and run PGDSpider from the web by the Java Web Start software. Java Web Start provides an easy, one-click activation of PGDSpider and it guarantees that you are always running the latest version.

\\



==== Launch PGDSpider ====
Java Web Start is included in the [[http://www.oracle.com/technetwork/java/javase/downloads/index.html|Java Runtime Environment]].\\
\\
Launch PGDSpider using Java Web Start from:
  * **Browser:** Click on following PGDSpider Web Start icon: [[http://www.cmpg.unibe.ch/software/PGDSpider/jnlp/PGDSpider2.jnlp|{{webstart_btn_3.png}}]]
  * **Java Cache Viewer:** To launch the PGDSpider Web Start a second time, you do not need to return to the web page where you first launched it; instead you can launch it from the Java Cache Viewer. To open the Java Cache Viewer execute following command in the console: ''javaws -viewer''. To run PGDSpider Web Start, select it and click the Run button or double click the PGDSpider application.
  * **Desktop:** You can add a desktop shortcut to the PGDSpider Web Start application. Select the application in the Java Cache Viewer (see above how to open it), then right-click and select “Install Shortcuts” or click the Install button. A shortcut is added to the desktop and you can launch the PGDSpider Web Start application just as you would launch any native application.

\\

==== Limitations ====
Starting PGDSpider from Java Web Start it is not possible to change the amount of memory PGDSpider is allowed to use (by default it is set to 1 GB). If you need to change the amount of memory (e.g.: if you have large files to convert), download the PGDSpider application as described in the 2nd step of the [[http://www.cmpg.unibe.ch/software/PGDSpider/#Download_and_Installation_Instructions|Installation Instructions]] on the web page.

\\









===== Execute PGDSpider GUI=====
The graphical user interface of the PGDSpider program is available in four different languages (English, French, German and Italian) and looks like: \\
{{pgdspider.png?600|PGDSpider GUI}}

\\
Execute PGDSpider GUI:
  * **Windows:** execute the file ''PGDSpider2.exe'' to start the program.
  * **Linux:** execute the command ''./PGDSpider2.sh'' to start the program.
  * **Mac and others:** execute the command ''java -Xmx1024m -Xms512M -jar PGDSpider2.jar'' to start the program.

\\





==== How to use the program ====
  * **Select the input file format to be translated:** First the format of the input file has to be selected. Use the putt down menu (to the left of the text “File format” in the Input File area) to select the input file format.
  * **Select the input file:** Click on the button “Select input file” and choose the file to be translated with the specified file format. Note that PGDSpider does not check if the selected file is of the right format.
  * **View the input file:** To have a look at the selected input file click on the “view file” button in the Input File area
  * **Select the output format:** Choose the desired file format of the output file. To do this select the output file format in the drop down menu to the left of the text “File format” in the Output File area 
  * **Select the output file:** Click on the button “Select output file” and choose the place where the output file should be saved.
  * **Select a SPID file:** Click on the button “Select SPID file” to select a SPID file which contains the answers for the Parser and the Writer Questions.
  * **Drop SPID file:** Click on the button “Drop SPID file” to remove the selected SPID file.
  * **Create/Edit SPID file:** Click on the button “Create/Edit SPID file” to open a window with the SPID editor to create or edit a SPID file.
  * **Convert file format:** To convert the specified input file to the desired output format, press the “Convert” button. If no SPID file was selected a window appear with Parser and Writer questions (SPID editor). When the questions are answered, the user has the possibility to save the answers in a SPID file. Afterwards the answers are applied in the conversion process. A progress bar at the bottom of the graphical user interface shows the progress of the parsing action. After conversion, the user should control the output file (mistakes in the input file could lead to mistakes in the output file)! 
  * **View the output file:** If conversion is over, one can have a look at the generated output file if the button “view file” in the Output File area is clicked.
  * **Create/Edit SPID file:** Click in the “Convert Menu” on “Create/Edit SPID file” to create a new SPID file or to edit an existing one (selected SPID file in the GUI). A window is opened with the SPID editor, where the user can specify the input and output format and answer the corresponding questions. Afterwards the “SPID file” can be saved and applied (it is inserted in the “SPID conversion script” area in the PGDSpider GUI).
  * **Quit program:** To quit the program push the “Quit” button or the red button with the cross in the top right edge of the window.

\\





==== SPID Editor ====
{{spid_editor.png?500|SPID Editor}}

\\
The SPID Editor is a tool to answer the Writer and Parser questions. It also allows to save these answers in a SPID file, which can then be reused to convert other files with the same format (use the same answers). The SPID Editor can be opened by clicking in the PGDSpider "Convert" menu on "Create/Edit SPID file".

\\
=== How to use the SPID Editor ===
  * **Select/ change input format:** Use the put down menu to the right of the text "Input format to select or change the input format. Afterwards press the "Apply" button to apply the input format (Parser questions will change).
  * **Select/ change output format:** Use the put down menu to the right of the text "Output format to select or change the output format. Afterwards press the "Apply" button to apply the output format (Writer questions will change).
  * **Answer Parser Questions:** Click on the "Parser Question" tab. Afterwards the Parser questions appearing below the tab can be answered. Some of the questions do not need to be answered in every situation, because they are questions of special cases (all possible questions are listed. For more detail have a look at the corresponding data format description part).
  * **Answer Writer Questions:** Click on the "Writer Question" tab. Afterwards the Writer questions appearing below the tab can be answered. Some of the questions do not need to be answered in every situation, because they are questions of special cases (all possible questions are listed. For more detail have a look at the corresponding data format description part).
  * **Save and Apply:** Click on the "Save and Apply" button to save the answers in a SPID file and to apply the answers in the actual conversion process.
  * **Save and Close:** Click on the "Save and Apply" button to save the answers in a SPID file and to close the SPID Editor.
  * **Cancel:** Click on the "Cancel" button to close the SPID Editor without saving.

\\
=== SPID file ===
The SPID file contains the Parser and Writer format and the answers to the corresponding questions. It is a plain text file encoded with UTF_8 and the ".spid" file extension.

\\





==== PGDSpider Menus ====
=== File Menu: ===
  * **Select input file:** Opens a dialog box to select an input file.
  * **Select output file:** Opens a dialog box to select the place where the output file should be saved.
  * **View input file:** Opens a window with the input file.
  * **View output file:** Opens a window with the output file. 
  * **Quit:** Quit the PGDSpider program.

\\
=== Convert Menu: ===
  * **Convert:** convert the specified input file into the chosen output file format and saves it.
  * **Create/Edit SPID file:** opens a window with the SPID editor to create or edit a SPID file.

\\
=== Config Menu: ===
  * **Options:** opens a window with option settings:
    * **Language option:** In the drop down menu one can select the language of the graphical user interface and the menus. One can choose between four languages: English, French, German and Italian. 
    * **Window option:** If “Window resizable” box is checked, the PGDSpider window can be resized. In order to reset the window size to the default, press the “Reset window size” button. 
    * **External Tools:**
      * **Select Path to Samtools:** Click on the button "Select path to Samtools" and give the path to the samtools.exe program (The Samtools distribution can be downloaded from [[http://samtools.sourceforge.net]]). Samtools is needed in the conversion process of the formats SAM, BAM, VCF and BCF.
      * **Select Path to Bcftools:** Click on the button "Select path to Bcftools" and give the path to the bcftools.exe program (The Samtools distribution can be downloaded from [[http://samtools.sourceforge.net]]). Bcftools is needed in the conversion process of the formats SAM, BAM, VCF and BCF.      
    * **Cancel/ Apply button:** Apply or cancel the changed options
  * **Help:** opens a window with a help file
  * **About PGD Spider:** opens a window with short information about the PGDSpider:

\\

==== SPID Editor Menus ====
=== File Menu ===
  * **Save and Close:** Saves the SPID file and close the SPID Editor. 
  * **Cancel:** Cancel the SPID editor without saving. 

\\
=== Info Menu ===
  * **About PGD Spider:** Opens a window with short information about the PGDSpider program.

\\



==== Shortcuts - PGDSpider ====
=== Menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + F | Open 'File' menu. ||
|| Alt + V | Open 'Convert' menu. ||
|| Alt + N | Open 'Config' menu. ||
\\

=== File menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + I | Select an existing input file. ||
|| Alt + O | Select an output file. ||
|| Ctrl + I | View the input file. ||
|| Ctrl + O | View the output file. ||
|| Ctrl + X | Quit PGDSpider application. ||
\\

=== Convert menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + C | Convert selected input file. ||
|| Alt + S | Create or edit the SPID file. ||
\\

=== Config menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + Z | Show PGDSpider options panel. ||
|| Alt + 1 | Show PGDSpider help. ||
|| Alt + A | Show some information about PGDSpider. ||

\\

==== Shortcuts - SPID Editor ====
=== Menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + F | Open 'File' menu. ||
|| Alt + I | Open 'Info' menu. ||
\\

=== File menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + S | Save and Close SPID editor. ||
|| Ctrl + X | Cancel SPID editor. ||
\\

=== Info menu - Shortcuts ===
^ Shortcut ^ Action ^^
|| Alt + A | Show some information about PGDSpider. ||

\\


==== Log Output ====
The “Log Output” is an area of the graphical user interface which is used to print program messages for the user. These messages consist of 3 types:
  * INFO: These are normal program messages with the actions the user performed (e.g.: “Opening input file”, “convert...”, etc.)
  * WARN (yellow marked): Warning messages are written if something is missing or small error occurs but the program is able to deal with it.
  * ERROR (red marked): If a severe error occurs during the parsing or writing of a file, the program stops and an error message is written (none or an incomplete output file is written).

\\








===== Execute PGDSpider cli =====
Execute PGDSpider-cli (command line)
  * **Windows:** execute the command ''PGDSpider2-cli.exe''
  * **Linux:** execute the command ''java -Xmx1024m -Xms512m -jar PGDSpider2-cli.jar''
  * **Mac and others:** execute the command ''java -Xmx1024m -Xms512m -jar PGDSpider2-cli.jar''

\\
The command line version of the PGDSpider program can be executed with following options (the order does not matter): 
  * **-?** or **-h**: To show a help text with the different options
  * **-inputfile <file>** (mandatory): Specify the input file for the conversion process.
  * **-inputformat <format>**: 
    * Specify the format of the input file. This option is mandatory if the input format is not defined in the answer (SPID) file.
    * Possible input formats are: PGD, ARLEQUIN, BAM, BAPS, BATWING, BCF, CONVERT, FASTA, FASTQ, FSTAT, GDA, GENELAND, GENEPOP, GENETIX, HGDP_CEPH, IMMANC, IM, MEGA, MIGRATE, MSA, NEWHYBRIDS, NEXUS, PED, PHYLIP, SAM, STRUCTURE, VCF
  * **-outputfile <file>** (mandatory): Specify the output file for the conversion process.
  * **-outputformat <format>**:
    * Specify the format of the output file. This option is mandatory if the output format is not defined in the answer (SPID) file.
    * Possible output formats are: PGD, ARLEQUIN, BAM, BAPS, BATWING, BCF, FASTA, FASTQ, FDIST2, FSTAT, GDA, GENELAND, GENEPOP, GENETIX, GESTE_BAYE_SCAN, IMMANC, IM, KML, MEGA, MIGRATE, MSA, MSVAR, NEWHYBRIDS, NEXUS, PED, PHYLIP, SAM, STRUCTURE, VCF
  * **-spid <file>** (mandatory): Specify the SPID file containing the preanswered conversion questions. The SPID file can be generated with the help of the SPID Editor integrated in the PGDSpider GUI.

\\



==== Examples ====
  * call help: ''PGDSpiderCli -?'' or ''PGDSpiderCli -h''
  * convert a [[STRUCTURE]] file to an [[Arlequin]] file: ''PGDSpider2-cli -inputfile examples\example_Structure.txt -inputformat STRUCTURE -outputfile examples\output_Arlequin.arp -outputformat ARLEQUIN -spid examples\Structure_Arlequin.spid''
  * Execute the jar file itself and convert a [[STRUCTURE]] file to an [[Arlequin]] file: ''java -Xmx1024m -Xms512m -jar PGDSpider2-cli.jar -inputfile examples\example_Structure.txt -inputformat STRUCTURE
-outputfile examples\output_Arlequin.arp -outputformat ARLEQUIN -spid examples\Structure_Arlequin.spid''

\\









===== Conversion examples =====
The PGDSpider distribution contains following simple example files ({{examples.zip|}}) to do some trial format conversion with PGDSpider:
  * “example_Arlequin.arp”:
    * Data: DNA, haploid
    * Convert to: [[http://phd.chnebu.ch/index.php/SAMtools#BAM_format|BAM]], [[BAPS]], [[http://phd.chnebu.ch/index.php/Variant_Call_Format_(VCF)#Binary_variant_Call_Format_.28BCF.29|BCF]], [[FASTA]], [[FDist2]], [[GENELAND]], [[MEGA]], [[MIGRATE]], [[NEXUS]], [[PGD]], [[PHYLIP]], [[http://phd.chnebu.ch/index.php/SAMtools|SAM]], [[http://phd.chnebu.ch/index.php/Variant_Call_Format_(VCF)|VCF]]
  * “example_Genepop.txt”:
    * Data: Microsat, diploid
    * Convert to: [[Arlequin]], [[BAPS]], [[BATWING]], [[FDist2]], [[FSTAT]], [[GDA]], [[GENELAND]], [[GENETIX]], [[GESTE/BayeScan]], [[Immanc]], [[IM]] (IMa), [[MIGRATE]], [[MSA]], [[NewHybrids]], [[MSVar]], [[PGD]], [[STRUCTURE]]
  * “example_MEGA.meg”:
    * Data: DNA, haploid
    * Convert to: [[Arlequin]], [[http://phd.chnebu.ch/index.php/SAMtools#BAM_format|BAM]], [[BAPS]], [[http://phd.chnebu.ch/index.php/Variant_Call_Format_(VCF)#Binary_variant_Call_Format_.28BCF.29|BCF]], [[FASTA]], [[FDist2]], [[GENELAND]], [[MIGRATE]], [[NEXUS]], [[PGD]], [[PHYLIP]], [[http://phd.chnebu.ch/index.php/SAMtools|SAM]], [[http://phd.chnebu.ch/index.php/Variant_Call_Format_(VCF)|VCF]]
  * “example_PGD.xml” (can be displayed in a nice way with any browser by using the stylesheet_PGD.xsl):
    * Data: standard (multi-allelic), diploid, with distance matrix
    * Convert to: [[Arlequin]], [[BAPS]], [[FDist2]], [[FSTAT]], [[GDA]], [[GENELAND]], [[GENEPOP]], [[GENETIX]], [[GESTE/BayeScan]], [[Immanc]], [[MIGRATE]], [[NewHybrids]]
  * “example_SAM.sam” and its reference file “example_SAM_references.fasta”:
    * Data: NGS, diploid
    * Convert to: [[Arlequin]], [[http://phd.chnebu.ch/index.php/SAMtools#BAM_format|BAM]], [[BAPS]], [[http://phd.chnebu.ch/index.php/Variant_Call_Format_(VCF)#Binary_variant_Call_Format_.28BCF.29|BCF]], [[FASTA]], [[FASTQ]], [[FDist2]], [[GENELAND]], [[MEGA]], [[MIGRATE]], [[NEXUS]], [[PGD]], [[PHYLIP]], [[http://phd.chnebu.ch/index.php/SAMtools|SAM]], [[http://phd.chnebu.ch/index.php/Variant_Call_Format_(VCF)|VCF]]
  * “example_Structure.txt”:
    * Data: Microsat (as number of repeats), diploid (on two consecutive rows), “Phase Information” row is not present, Missing value code = -9, “Locus names” are present, “individual labels” are present, “PopData” column is present, “Recessive Alleles/Inter-Marker Distance” rows are not present.
    * Convert to: [[Arlequin]], [[BAPS]], [[BATWING]], [[FDist2]], [[FSTAT]], [[GDA]], [[GENELAND]], [[GENEPOP]], [[GENETIX]], [[GESTE/BayeScan]], [[Immanc]], [[IM]] (IMa), [[MIGRATE]], [[MSA]], [[NewHybrids]], [[MSVar]], [[PGD]]
    * The spid file “Structure_Arlequin.spid” can be used for the conversion to the Arlequin format.

\\

===== Reporting bugs and comments =====
If there are any bugs, send me an e-mail. Please give me a short description of the bug and tell me the input and output file format. If it is possible also attach the input file which caused the problem.\\
PGDSpider is an ongoing project. For any comments or suggestions of further file formats, please send me an e-mail.

\\
e-mail address: heidi.lischer(at)iee.unibe.ch