|
|
| (32 intermediate revisions by 3 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. Phenex builds on [http://www.phenote.org/ Phenote] and [http://oboedit.org/ OBO-Edit] from the [http://www.obofoundry.org/ OBO project]. Jim Balhoff is the lead developer of Phenex. | |
| − | | |
| − | ==Download & Installation==
| |
| − | | |
| − | ===System Requirements===
| |
| − | Phenex runs on any system with Java 5 or newer (Java 5 is also called version 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 (check your version of Mac OS X by selecting "About This Mac" under the Apple menu). 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.
| |
| − | | |
| − | ===Direct downloads for Phenex 1.8===
| |
| − | Choose download appropriate for your platform:
| |
| − | * [http://phenoscape.org/downloads/Phenex-1.8-mac.zip Mac OS X]
| |
| − | * [http://phenoscape.org/downloads/Phenex-1.8-win.zip Windows]
| |
| − | * [http://phenoscape.org/downloads/Phenex-1.8-unix.tgz Unix (Linux, Solaris, etc.)]
| |
| − | | |
| − | ===Installation on Mac OS X===
| |
| − | Double-click the downloaded file to unzip it. Copy Phenex.app anywhere you would like to install it. Double-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===
| |
| − | Unzip the downloaded archive using a command such as <code>tar zxvf phenex-1.0-unix.tgz</code>. Change directories into the Phenex folder and run the shell script to launch Phenex. You will need to have Java in your executable <code>PATH</code>.
| |
| − | | |
| − | ==License and Attribution==
| |
| − | | |
| − | Phenex is open source software, released under the [http://www.opensource.org/licenses/mit-license.php MIT license].
| |
| − | | |
| − | If you use Phenex for annotation or extend it for your project, please cite the following publication in your documentation and resulting publications: <br/>
| |
| − | Balhoff JP, Dahdul WM, Kothari CR, Lapp H, Lundberg JG, Mabee P, Midford PE, Westerfield ME, Vision TJ. 2010. ''Phenex: Ontological Annotation of Phenotypic Diversity''. PLoS ONE 5(5): e10500. [http://dx.doi.org/10.1371/journal.pone.0010500 DOI]
| |
| − | | |
| − | ==Source code and support ==
| |
| − | | |
| − | Please join the Phenex users mailing list for software support and discussion of Phenex features:
| |
| − | * https://lists.sourceforge.net/lists/listinfo/phenex-users
| |
| − | | |
| − | The Phenex source code is hosted [https://github.com/phenoscape/Phenex at GitHub]. To make contributions to the project or test the latest in-development code, you should check out a working copy from the Git repository:
| |
| − | * git clone git://phenex.git.sourceforge.net/gitroot/phenex/phenex
| |
| − | The Phenex source includes both an Eclipse project (used for most active development) and an Ant build file (used for making releases). You can browse [https://github.com/phenoscape/phenex Phenex source code on the web].
| |
| − | | |
| − | ==Running Phenex==
| |
| − | After launching Phenex, Java can sometimes be a little slow to start up. If you're running Java 6 or later, you should see a splash screen image shortly after launching. This is followed by a panel informing you that Phenex is checking for ontology updates. If you have not run Phenex before, your computer needs to be online in order for Phenex to download the required ontologies. If you have run Phenex before, Phenex will check for the availability of a newer version of each ontology and download it if necessary. It is okay to work offline if Phenex has previously had a chance to download the ontologies. Phenex performs a check for ontology updates each time it is launched.
| |
| − | | |
| − | === Reporting Bugs and Feature Requests ===
| |
| − | Report any bugs and make feature requests using the [https://github.com/phenoscape/Phenex/issues Phenex issue tracker]. You will need to log in with a GitHub account to submit an issue (just create an account if you don't already have one).
| |
| − | | |
| − | ==Documentation==
| |
| − | ===Ontology configuration===
| |
| − | By default, Phenex comes pre-configured with the ontologies used for the Phenoscape project, but it can be configured to load terms from any OBO ontology from the web or a local file. Configuration of ontologies in Phenex has two components: (1) adding term sources - URLs representing OBO files; and (2) specifying the set of terms which should be available within each kind of entry field - an entry field can allow terms from a subset of a given ontology, or from more than one ontology.
| |
| − | ====Term sources====
| |
| − | To edit the list of terms sources, open the Ontology Sources panel by selecting View > Config > Ontology Sources from the menu. Add a new source by pressing the '+' button. Enter an HTTP or local file URL in the URL column, and an optional label of your choice in the Label column. Press "Apply" to save your list of ontology sources. You will need to relaunch Phenex in order for it to download the given files and load all the terms into its ontology session.
| |
| − | ====Entry field filters====
| |
| − | The set of terms available in a given entry field are determined by term filters. Term filters are just saved search specifications which can be created using the Search Panel. To apply a term filter to a particular type of entry field, save it in one of the standard locations (below).
| |
| − | =====Creating a term filter=====
| |
| − | Open the Search Panel from View > Ontology > Search Panel. Configure the search to specify the needed terms - you can test the result by performing the search with the Search button. Save the filter by pressing the disk icon. An example of a term filter used for the entity field in the Phenoscape configuration is shown [[Phenex term filter|here]].
| |
| − | | |
| − | =====Configuring entry fields=====
| |
| − | To configure a particular entry field, place a filter file with the appropriate name in the Filters folder within the [[#Locating_the_Phenex_settings_folder|Phenex settings folder]]. You may need to create the Filters folder. You will need to relaunch Phenex for the new filters to take effect. The following types of entry fields are available:
| |
| − | * Taxa
| |
| − | ** ''<Phenex settings folder>''/Filters/taxa.xml
| |
| − | ** Used in the Taxa panel: Valid Taxon column
| |
| − | * Museum collections
| |
| − | ** ''<Phenex settings folder>''/Filters/museums.xml
| |
| − | ** Used in the Specimens panel: Collection column
| |
| − | * Entities
| |
| − | ** ''<Phenex settings folder>''/Filters/entities.xml
| |
| − | ** Used in the Phenotypes panel: Entity column, Related Entity column
| |
| − | * Qualities
| |
| − | ** ''<Phenex settings folder>''/Filters/qualities.xml
| |
| − | ** Used in the Phenotypes panel: Quality column
| |
| − | * Units
| |
| − | ** ''<Phenex settings folder>''/Filters/units.xml
| |
| − | ** Used in the Phenotypes panel: Unit column
| |
| − | * Relations
| |
| − | ** ''<Phenex settings folder>''/Filters/relations.xml
| |
| − | ** Specifies the relations available when creating post-compositions
| |
| − | | |
| − | ===Locating the Phenex settings folder===
| |
| − | The Phenex settings folder contains cached copies of downloaded ontology files, entry field filter files, and other settings files. Its location is dependent on the platform on which you're running Phenex.
| |
| − | * '''Mac OS X:''' ''<user's home>''/Library/Application Support/Phenex
| |
| − | ** In Mac OS 10.7+, this folder is hidden but can be made visible by going to Finder> Go > Go to Folder, and typing in "~/Library"
| |
| − | * '''Windows:''' C:\Documents and Settings\''<user's name>''\Phenex
| |
| − | * '''Unix:''' ''<user's home>''/.phenex
| |
| − | | |
| − | ===Importing data from a NEXUS file===
| |
| − | ''TODO''
| |
| − | | |
| − | <!--
| |
| − | ===NeXML file format extensions===
| |
| − | This is out of date and will be updated with the new NeXML metadata scheme soon!
| |
| − | | |
| − | The [http://www.nexml.org/nexml/html/doc/schema-1/ NeXML schema] provides an XML format for saving evolutionary character data. It provides for customization by allowing most elements to be annotated by including a "dict" element containing key-value data. Keys are text while the values can be textual, numeric, or arbitrary XML. Phenex stores ontological annotations and application-specific data in a number of proprietary dict elements. While these dict elements are specific to Phenex, all standard data in the file can still be read and used by other applications that support NeXML.
| |
| − | | |
| − | While these data are currently stored within proprietary Phenex dicts, eventually common needs for such data across applications should be identified and public standards should be established and implemented. While reading and writing files, Phenex attempts to preserve and "round-trip" any unsupported NeXML data or unknown annotation elements.
| |
| − | | |
| − | ====Document metadata====
| |
| − | Document metadata is stored within the root "nexml" element in a dict using the key "phenex-metadata". An "any" element contains custom XML with the elements listed below.
| |
| − | <xml>
| |
| − | <dict>
| |
| − | <key>phenex-metadata</key>
| |
| − | <any>
| |
| − | <curators>W. Dahdul</curators>
| |
| − | <publication>Buckup, 1998</publication>
| |
| − | <publicationNotes>Evidence codes for matrix is IVS</publicationNotes>
| |
| − | </any>
| |
| − | </dict>
| |
| − | </xml>
| |
| − | | |
| − | ====Taxon and specimen data====
| |
| − | An OBO ontology identifier for a taxon is stored within the taxon's "otu" element in a dict using the key "OBO_ID". The value is a string representing the OBO identifier. Specimens for this taxon are also stored within the taxon's "otu" element, within a dict using the key "OBO_specimens". The value for this dict is an "any" element containing custom "specimen' XML elements. The OBO identifier for the museum collection is stored in a "collection" attribute while the specimen accession number is in an "accession" attribute.
| |
| − | <xml>
| |
| − | <otu id="4341922c-a479-4088-b02e-42a0e248a825" label="Acestrorhynchus lacustris">
| |
| − | <dict>
| |
| − | <key>OBO_ID</key>
| |
| − | <string>TTO:1030219</string>
| |
| − | </dict>
| |
| − | <dict>
| |
| − | <key>OBO_specimens</key>
| |
| − | <any>
| |
| − | <specimen collection="COLLECTION:0000403" accession="205830"/>
| |
| − | <specimen collection="COLLECTION:0000403" accession="206997"/>
| |
| − | <specimen collection="COLLECTION:0000403" accession="207388"/>
| |
| − | <specimen collection="COLLECTION:0000403" accession="207768"/>
| |
| − | <specimen collection="COLLECTION:0000403" accession="207850"/>
| |
| − | </any>
| |
| − | </dict>
| |
| − | </otu>
| |
| − | </xml>
| |
| − | | |
| − | ====Phenotype annotations====
| |
| − | Phenotype annotations are stored within the "state" element to which they correspond, within a dict using the key "OBO_phenotype". The value for this dict is an "any" element containing a "phenotype" element. The "phenotype" element and its children are taken from the [http://www.fruitfly.org/~cjm/obd/formats.html PhenoXML schema].
| |
| − | <xml>
| |
| − | <state id="889131fa-7e4d-45f0-b918-14d3ba806c65" label="present" symbol="1">
| |
| − | <dict>
| |
| − | <key>OBO_phenotype</key>
| |
| − | <any>
| |
| − | <phen:phenotype>
| |
| − | <phen:phenotype_character>
| |
| − | <phen:description/>
| |
| − | <phen:bearer>
| |
| − | <phen:typeref about="TAO:0000203"/>
| |
| − | </phen:bearer>
| |
| − | <phen:quality>
| |
| − | <phen:typeref about="PATO:0000467"/>
| |
| − | </phen:quality>
| |
| − | </phen:phenotype_character>
| |
| − | </phen:phenotype>
| |
| − | </any>
| |
| − | </dict>
| |
| − | </state>
| |
| − | </xml>
| |
| − | -->
| |
| − | | |
| − | ===Entering polymorphic or uncertain state values===
| |
| − | The Phenex matrix editor can handle entry of polymorphic or uncertain state values within cells. In order to enter multiple states in a single cell,you must use the matrix "quick editor". Just beneath the matrix view, there is a checkbox titled "Use quick editor". After enabling this setting, when you click to edit a cell, instead of popping up a states menu, the cell will become an editable text field, which operates very much like the matrix cell editor in Mesquite. Here you can simply type the symbol of the state you want to enter. If you want to enter a polymorphism of states 0 and 1, simply enter "0&1" (no spaces). For an uncertainty, use a slash: "0/1".
| |
| − | | |
| − | ===Consistency Review panel===
| |
| − | Phenex includes a Consistency Review panel which reports problematic or missing annotations. The consistency issues currently evaluated are:
| |
| − | | |
| − | * Unannotated state.
| |
| − | * Empty '''entity''' field.
| |
| − | * Empty '''quality''' field.
| |
| − | * Post-composition consisting of more than one differentia (may be okay).
| |
| − | * Relational quality used without a '''related entity'''.
| |
| − | * '''Related entity''' entered without a relational quality.
| |
| − | * Biological process entity not used with a process quality.
| |
| − | * Qualities descending from different attributes used in states for a given character.
| |
| − | | |
| − | ==Troubleshooting Problems==
| |
| − | | |
| − | ===Removing Corrupted Ontology Files===
| |
| − | | |
| − | Local copies of ontology files can become corrupted, causing Phenex to display a warning about "dangling" terms on start-up. Note that the warning about danglers can also indicate a valid ontology change related to merging of terms from a recent ontology update.
| |
| − | | |
| − | To remove local copies of ontologies from your Phenex directory, delete all files within the “Ontology Cache” folder on your computer:
| |
| − | User’s Home/Library/Application Support/Phenex/Ontology Cache/
| |
| − | | |
| − | Phenex will then download new copies of the ontology files on startup.
| |
| − | | |
| − | [[Category:Curation]]
| |
| − | [[Category:Informatics]]
| |
