############################################# # jPAP - Pedigree Analysis Package For Java # # Version 1.5.0 Dec 5, 2006 # # Copyright 1992-2006, University of Utah. # ############################################# System Requirements ------------------- The base requirement of the target system is that a working installation of a J2SE v1.4.x or later Java runtime is present. Some additional requirements are imposed by the fact that jPAP, in its current transitional phase, includes a non-Java or "native binary" component: (1) Some native platforms are not currently supported by us at the binary level. Those for which we do provide distribution bundles containing pre-compiled binaries are listed on the jPAP web page at http://hasstedt.genetics.utah.edu/jpap/. However, note that we also offer a generic unix bundle, dubbed "etcix", which, rather than binaries, contains Fortran sources for the native components. Besides extending the reach of jPAP to unixish platforms not specifically supported, this bundle may, of course, be chosen in place of a platform-specific bundle, so as to obtain full control over the native-engine build and implementation. (2) The native binary component shipped with jPAP makes some fairly rigid demands on system memory. At least 1GB of physical RAM is recommended. Installation ------------ ** All bundles ** Extract the contents of the download-bundle to your chosen installation location, preserving the directory structure contained in the bundle. The installed files should function identically whether installed in a system or user area, though it's recommended to start with a local installation for testing purposes. Please note that the installed 'doc' subdirectory contains a local copy of the jPAP Manual available for browsing on our website. ** The "etcix" bundle ** (1) Follow the "all bundles" steps above. (2) At this point, to complete the installation, jPAP's native components must be built. There are two scenarios for building and installing the binaries: (a) Automatic. Go to the "Start jPAP" section below, and follow the instructions to run jPAP. The program will attempt a JIT ("just in time") build/install of its native tools the first time they are needed. However, this will only succeed under certain conditions, and even when it does, the default build may not be what you want. (For instance, you may wish to use a Fortran compiler other than 'f77' or link a global search module other than GEMINI.) Hence, for any number of reasons, you may decide on a command-line install instead. (b) Command line. If jPAP's native autobuild process fails without informing you of an easily-remedied reason, or you simply do not want a default build, a conventional unix build set-up is at your disposal in the 'src/0native' branch of the jPAP installation tree. The details are best provided in context, so change to that directory and issue "make help" for a quick overview of build options. Additional information is available in the Makefile comments. Start jPAP ---------- Running jPAP is just a matter of providing the location of the jPAP JAR file to the runtime's 'java' (or 'javaw') executable. For instance, from the command line: Linux/Unix: java -jar {jpap directory/}jpap.jar [startup options] Windows java -jar {jpap directory\}jpap.jar [startup options] where the {...} is replaced with the path to the actual location where you installed jPAP, unless the latter is the working directory. Normally one would make an alias or other shortcut to avoid all that typing. Also, in a well-configured desktop environment, a mouse gesture such as double-clicking on the JAR file (or shortcut/link thereto) will yield the same result as entering the above command. The first time jPAP is run on a given system by a given user, it prompts for a folder in the user's area under which it may install a demo project folder. Having thereby installed some example *.xpas files, it will proceed to start the Project Window with one of them loaded. Even if you do not take jPAP up on this friendly offer, you will not receive the startup prompt again unless one of the following is the case: (1) installation was requested but failed due to a file system error (such as inadequate permissions) (2) first-use behavior is expressly requested (-redux startup option) (3) all user preferences are cleared (-unset startup option) Startup Options --------------- When you start jPAP as outlined above, the program may be passed space-separated option identifiers following the jar file name. At present the following options are officially recognized: -redux Reactivates the first-use behavior, which presently consists of offering to install an examples project folder, and, having done so, loading one of the *.xpas (PA Settings) files therein. -unset Attempts to clear user preferences (described in the next section) and then exits with a report of success or failure. Any other options are ignored. Uninstall / Clearing Preferences -------------------------------- jPAP makes no persistent background system modifications, with the exception of storing various user settings (e.g., last project directory, GUI component dimensions, and so on). The settings are stored in the OS-specific standard location. To remove these traces left by jPAP in the environment, either as part of jPAP uninstallation or simply to restore the default settings, run jPAP with the -unset startup option (see previous section). If you run jPAP and it exits abnormally, some files may also remain in the system's "temp" directory. When jPAP is not running, any such temp files may simply be deleted. Known Issues In This Release ---------------------------- ** (1) ** On the Windows platform, the demo-installation prompt will pop up with the user's home folder, which contains the My Documents folder, pre-selected. If you then select My Documents itself, the installation may fail. However, selecting the default location (by simply pressing select), or navigating to a subfolder of My Documents, should work. ** (2) ** The frequency of updates to the Progress Log pane in PAReporter is system dependant. In particular, on some systems the initial wait may be longer than subsequent updates. ** (3) ** jPAP implements all the functionality of PAP 5.0, with the exception of a few relatively minor features, listed below. These items are a high priority for implementation in upcoming releases. *The genotype/phenotype correspondence feature for markers (formerly defined in the PAP file popln.dat) is limited to a functional mapping. That is, each phenotype must correspond to exactly one genotype. *Variance component parameters are not automatically constrained to a sum of one. There is another way to achieve the same results - feel free to ask us about it. *Single-allele loci are not definable in the model editor. Again, there is a work-around. ** (4) ** There are some issues related to migrating data from PAP 5.0 (or earlier). Due to the more flexible and information-rich nature of jPAP's metadata representation, as compared to the header.dat/popln.dat system it replaces, full meaning cannot always be given to the variables, since the intended types and relationships are not contained in the legacy files. Thus some manual setup is unavoidable in certain cases, primarily: *The PAP file popln.dat contains trait data (as opposed to marker data). *Some of the header.dat variables are used as environmental IDs (for variance components analysis). If your legacy data meets either of these conditions you will have to modify the converted xmet file using MetEd before importing a model that refers to the variables in question. We will be happy to walk you through the required procedures, pending inclusion of more detailed documentation in the package. The jPAP system is designed to provide for dynamic inter-document validation under the demands of arbitrary future extension; we appreciate your patience in making the required adjustments. One other issue that may arise involves the fact that jPAP's emulation of Fortran 77's fixed-format text IO is more strict than the code produced by some Fortran compilers. Careful attention must be paid to field width, including trailing whitespace. (A reference to legacy formats is available in Appendix B of the PAP 5.0 manual, available on our website). Also, a trailing field containing a zero is not treated as equivalent to a non-existent field. ** (5) ** Contextual help in jPAP is still sketchy. While we now have an integrated PAM reference, the present information is based on that provided by the PAP 5.0 model-creation program and does not contain all the material in Appendix C of the PAP 5.0 manual. Hence, for the time being, the latter remains useful as a supplement. (It is available for download as a PDF in the PAP 5.0 section of our website. The PAP libraries correspond exactly to the current jPAP rosters, and subroutines to modules.) ** (6) ** The Java source code will be included in a later, more stable release. It will definitely be included in the first all-Java release (either jPAP 2.0 or 3.0, depending on whether we opt for a JNI stage in the transition), along with full API documentation to support user-written or adapted PAMs, metadata attributes, global optimizers, parameter constraints, and other pluggable extensions. Recent Changes -------------- The modification log is now kept in the distribution file 'changes.txt'. Contact ------- Sandra J. Hasstedt University of Utah sandy@genetics.utah.edu http://hasstedt.genetics.utah.edu/ Last-Modified: 5 Dec 2006