Difference between revisions of "Phenex"

From phenoscape
(Installation on Windows)
m
 
(160 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Image:Phenex-small.png|right]]
+
''Phenex is being [https://github.com/phenoscape/Phenex maintained on Github]. [https://github.com/phenoscape/Phenex/releases Releases] and [https://github.com/phenoscape/Phenex/issues known issues] can be found there, and [https://github.com/phenoscape/Phenex/wiki documentation about using Phenex] has now been moved to a Github-hosted wiki.''
Phenex is an application for annotating character matrix files with ontology terms.  Character states can be annotated using the Entity-Quality syntax for ontologically describing phenotypes.  In addition, taxon entries can be annotated with identifiers from a taxonomy ontology.  Phenex saves ontology annotations alongside traditional character matrix data using the new [http://www.nexml.org NeXML] format standard for evolutionary data.
 
 
 
==System Requirements==
 
Phenex runs on any system with Java 5 or newer (Java 5 is also called 1.5).  Java 5 comes pre-installed on Mac OS X 10.4 and later.  Phenex can't be used on older releases of Mac OS X.  For Windows, you can check your version of Java, and install if necessary, at http://www.java.com/.  Phenex runs on Linux - just make sure you have Java 5 installed.
 
 
 
==Download & Installation==
 
The latest version of Phenex can be obtained from [http://sourceforge.net/projects/obo/ OBO's Sourceforge project site].  Until the release of Phenex 1.0, only in-development "beta" downloads are available.  Download the file appropriate for your system ("mac" or "win").  The "src" download contains the sourcecode for the current release of Phenex.
 
* [http://sourceforge.net/project/showfiles.php?group_id=76834&package_id=295042 Phenex beta downloads]
 
===Installation on Mac OS X===
 
Double-click the downloaded file to unzip it.  Copy Phenex.app anywhere you would like to install it.  Doublie-click Phenex.app to launch the application.
 
 
 
===Installation on Windows===
 
On Windows you must be sure to extract the Phenex folder from the zip archive - Phenex will not function properly if run from within the zip archive.  Right-click on the downloaded zip file and choose "Extract All...".  Use the Extraction Wizard to copy Phenex to a folder on your desktop.  You can then move the Phenex folder anywhere you like.  Within the Phenex folder, double-click the file "Phenex.bat" to launch the application.
 
 
 
===Installation on Linux/Unix===
 
 
 
==Menu choices for opening files==
 
* File > Open...
 
** Open an existing NeXML file (native Phenex format), replacing all existing data.
 
* File > Import NEXUS...
 
** Open an existing NEXUS file, replacing all existing data.  Changes must be saved to a new NeXML file.
 
* File > Merge > Tab-delimited Taxa...
 
** Merge data from a Phenote taxon list file into your existing data.
 
* File > Merge > Tab-delimited Characters...
 
** Merge data from a Phenote character EQ list file into your existing data.
 
* File > Merge > NEXUS Matrix...
 
** Merge data from an existing NEXUS file into your existing data.
 
 
 
==Double-checking Taxon Lists for omissions and errors==
 
 
 
#Open the taxon file in Excel and print the taxon list.  Compare the printed copy against the publication's materials list, and use Phenote+ to add missing taxa or make other corrections to the file. Remember to upload the corrected file to the fileshare, and use the corrected file to merge in Phenex.
 
 
 
==Importing matrix files and taxon lists into Phenex==
 
# In order to combine a taxon list created in Phenote with matrix data stored in a NEXUS file, both files need to use identical taxon names.  For the Phenote file, this is the value in "Publication Taxon" (NOT "Valid Taxon").  For the NEXUS file, this is the ordinary taxon name you can see and edit in Mesquite.  It is much easier if all the taxon names are made identical before you do the merge.
 
# First, open the  taxon list in Phenote and the NEXUS file in Mesquite.  Make sure all the taxon names you want to match are identical.  It is okay if the files don't have the same number of taxa - if there are more in the taxon list, the extra taxa will be added.  If there are fewer, you will just have some that don't get matched.
 
# Next, make sure that the character description field has some content (more than numerical).  If it is blank, it leads to an import error in current Phenex (1.0-beta4; 25 Aug 08).  Copying the free text character name from the publication pdf works well.  Pasting in the character state free text, however, works better in Phenex than Mesquite (because Mesquite doesn't return to next character in list after entering character states from previous character).
 
# While the NEXUS file is open in Mesquite, choose "File > Save File As..." and save a new copy of the NEXUS file. Make sure you have the most recent copy of Mesquite.  This will ensure that Mesquite re-writes the NEXUS file using a modern format which is more likely to be successfully opened by Phenex.  Use this new copy of the NEXUS file for all subsequent steps.
 
# Launch Phenex.  Choose "File > Import NEXUS...".  Select your NEXUS file and open it.  Verify that all the data is imported as expected, including the matrix.
 
# Now choose "File > Merge > Tab-delimited Taxa...".  Select your taxon list file and open it.  The import will seem a little slow.  Verify that the taxa you loaded from your NEXUS file now have TTO terms associated with them under "Valid Taxon", and specimens in the specimens panel (assuming you had this data in your taxon list).
 
# If some taxa from the Phenote taxon list were not matched to existing taxa in Phenex, you will see them at the end of the list.  Also, these taxa would have only empty cell values in the matrix panel.  If you expected these taxa to match existing taxa, check the taxon names and start over.
 
# Save your Phenex data to a new file using "File > Save".  It is recommended to append ".xml" to the file name.
 
# NOTE: If your publication does not include a character X taxon matrix, you can Merge Tab-delimited Taxa to import the taxon list and then save as a .xml Phenex file. A matrix can be entered at some later point, either in Phenex or Jim is developing a matrix import feature (the first version of this is available now in 1.0-beta5).
 
 
 
==Merging EQ annotations from a tab-delimited file==
 
Using the menu item "File > Merge Tab-delimited Characters...", you can merge EQ annotations from a tab file into an existing data set. The "Character Number" and "State Number" columns are used to match a character (by index) and state (by symbol) in the existing data set.  If the index falls outside the current range of characters, a new character is appended to the existing data set.  If a state with the given symbol does not exist, a new state is appended to the given character.  The character and state labels in the tab file will overwrite any labels in the existing data set.  If a "Count" value is not a basic number, it will be appended to the Notes field instead of Count.
 
 
 
==Merging matrix data (taxon by character state associations) from a NEXUS file==
 
Using the menu item "File > Merge NEXUS Matrix...", you can merge matrix values into an existing data set.  Characters are matched via their index. Extra characters are appended to the existing data. Values are matched by comparing the symbol - if a state with that symbol is not available for the character in the existing data set, a new state with that symbol is added to the character. Taxa are matched via their Publication Name.  Matrix values for unmatched taxa are unaltered.
 
 
 
[[Category:Curation]]
 
[[Category:Informatics]]
 

Latest revision as of 16:37, 12 December 2017

Phenex is being maintained on Github. Releases and known issues can be found there, and documentation about using Phenex has now been moved to a Github-hosted wiki.