PORTAGE_sharedWhereToFindThings - SamuelLarkin/LizzyConversion GitHub Wiki

Up PortageII Previous: Prerequisites Next: TextProcessing

Getting Started

Before proceeding with this manual, you should read the INSTALL and README files at the root of the PORTAGE shared distribution.

Once PORTAGE shared is installed on your system, you should make sure you source the SETUP.bash or SETUP.tcsh file before you run any software. You need to do this in every shell you open, so we recommend doing it in your .bashrc or .tcshrc file:

source /path/to/PortageII/SETUP.bash

or, for tcsh users:

source /path/to/PortageII/SETUP.tcsh

These files set up the PATH, PERL5LIB, LD_LIBRARY_PATH and PORTAGE variables as required to run PORTAGE shared software.

Where To Find Things

Every path given below is relative to the root PortageII directory.

Documentation

Project documentation can be found in various places.

  • The experimental framework, located in framework, includes a tutorial showing step by step instructions on how to use PORTAGE shared on toy data, following our current recommendations for software settings. This is the recommended starting point for your experiments. See tutorial.pdf in framework for details. If you have done previous work with PORTAGE shared outside the framework, we recommend you try switching to this framework instead, if that's feasible.

  • Installation instructions can be found in INSTALL.

  • Each program in the PORTAGE shared suite will produce useful information when invoked with the -h switch. In some cases, this information is very detailed, in particular for canoe, cow.sh, rat.sh, so it is worth using the -h switch for most programs you use. These usage messages can also be found in doc/usage.html, organized alphabetically and by module.

  • If your PORTAGE shared distro has source code, the src/htmldoc directory has code documentation, automatically generated from the source files. To access this documentation, start at doc/code-documentation.html. You can regenerate it by typing make doxy in the src directory if you have doxygen.

  • The doc directory has PDF documents with in depth (though somewhat out of date) documentation of the decoder and the rescoring program.

  • Most directories have their own README file with additional details.

  • The set of pages you are reading is the a somewhat obsolete user manual, going through the whole process of using PORTAGE shared, but not following the currently recommended practice.

Experimental Framework

The framework directory has a complete experimental framework that can be used both as a tutorial for learning how to use PORTAGE shared, and as a starting point for your own experiments. It uses make to run all the software. It is cluster aware, as long as you can schedule jobs via qsub on your cluster.

We regularly maintain this framework so that its defaults reflect our current recommendations as to how best to use PORTAGE shared, at least for typical use. Your data and use cases may work better with different settings, but we try to make the framework a decent "out of the box" configuration for many situations.

The tutorial included with the framework has recommendations on how you can configure the framework for your own needs and is a must-read for using the framework effectively.

Programs

Unless you have a binary distribution, programs are generated by you when you build PORTAGE shared, and normally end up in the bin sub directory. To use them, you need to set some environment variables, as described in the INSTALL file. For more details on how to build PORTAGE shared, see WritingCode.

Source Code

Source code is in the src directory, if it is included with your distribution.

Test Suites

The test-suite directory contains a few test suites. unit-testing contains several unit test suites meant to validate various parts of the code. regress-small-voc is an out-of-date regression test suite, previously used for assessing the impact of code changes. rescoring-example gives an out-of-date sample use of the rescoring tools in PORTAGE shared. (The new rescore.py rescoring script brings together all the rescoring tools in an single, unified interface.)

Up PortageII Previous: Prerequisites Next: TextProcessing