\documentclass{article} \usepackage[koi8-r]{inputenc} \usepackage[russian, english]{babel} \usepackage{pst-pdgr} \usepackage{pstricks-add} \usepackage{url} \usepackage{fancyvrb} \usepackage{listings} \lstset{language=Perl, captionpos=b, basicstyle=\ttfamily, abovecaptionskip=\abovedisplayskip, belowcaptionskip=\belowdisplayskip} \renewcommand{\lstlistlistingname}{List of Listings} \usepackage{graphicx} \usepackage{paralist} \psset{descarmA=1} \newcommand{\program}[1]{\textsf{#1}} \usepackage[breaklinks,colorlinks,linkcolor=black,citecolor=black, pagecolor=black,urlcolor=black]{hyperref} \DefineShortVerb{\|} \begin{document} \selectlanguage{english} \title{A Program For Automatic Pedigree Construction With \path{pst-pdgr}\\ User Manual and Algorithm Description} \author{Boris Veytsman, \path{borisv@lk.net} \and Leila Akhmadeeva} \date{March 2012} \maketitle \begin{abstract} The set of macros in \path{pst-pdgr} package allows to typeset complex pedigrees. However, a manual placement of pedigree symbols on a canvas is a time-consuming task. This program produces \TeX{} files from spreadsheets with the data on inheritance for a large class of pedigrees. It has a simple interface and can be used for quite complex pedigrees. \end{abstract} \begin{center} \input{english1.tex} \end{center} \clearpage \tableofcontents \listoffigures \listoftables \lstlistoflistings \clearpage \part{User Manual} \label{part:manual} \section{Introduction} \label{sec:intro} Medical pedigree is a very important tool for clinicians, genetic researchers and educators. As stated in~\cite{PedigreeNomenclature95}, ``The construction of an accurate family pedigree is a fundamental component of a clinical genetic evaluation and of human genetic research.'' The package \path{pst-pdgr}~\cite{pst-pdgr06} provides a set of PSTricks macros (see~\cite{PSTricks93}) to typeset pedigrees. In the framework of \path{pst-pdgr} the user manually chooses coordinates for each pedigree node on the diagram. While this is relatively easy for small pedigrees, this task becomes increasingly time-consuming for larger ones. There may be several approaches to automate it. For example, one may have data about the patients and their families in a spreadsheet or database. Then it would be useful to generate pedigrees from such data. This is the aim of the program \path{pedigree} described in this manual. Spreadsheets and databases can export the data as separated values files (``csv'' files for Comma Separated Values). Our program reads these files and outputs LaTeX{} code with \path{pst-pdgr} macros. We tried to make this code readable, so a user might tweak it if necessary. Of course, manually produced \LaTeX{} code is more versatile than the automatically generated one. There are certain limitations for the program: \begin{inparaenum} \item only persons having common genes with the proband or the ``starting person'' are included in the pedigree; \item no adopted children, sperm donors or surrogate mothers are shown on the pedigree; \item only one disease is shown on the chart; \item the support for consanguinic unions and inbreeding is rather experimental (see Section~\ref{sec:consanguinic}). \end{inparaenum} Subsequent versions of the program may ease some of these limitations. \section{Installation} \label{sec:install} \subsection{System Requirements} \label{sec:reqs} The program requires \program{Perl} version~5 or newer (it was tested with \program{Perl} v5.8.8, but should work with any \program{Perl-5}). The \LaTeX{} macros require \path{pst-pdgr} version~0.3 (July 2007) or newer. \subsection{Unix/Linux Installation} \label{sec:install_unix} If your system has a working \program{make} program, which is the usual case for Unix-like environments, the supplied \path{Makefile} installs the executable \path{pedigree} in \path{/usr/local/bin}, the libraries in \path{/usr/local/lib/site_perl} and the manual pages in \path{/usr/local/man}. This is done by the usual command |make install|. Optionally you can install files in the \path{doc} and \path{examples} subdirectories in the proper places in your system. \subsection{Installation in Other Systems} \label{sec:other} If your system does not have \program{make}, you need to manually perform the following: \begin{enumerate} \item Install the executable \path{pedigree.pl} to the place your system can find it. \item Install the libraries: \path{Pedigree.pm}, directory \path{Pedigree} and all files in it to the \program{Perl} search path. The latter is listed in the array \path{@INC}, which can be checked by the command |perl -V| or its equivalent. \end{enumerate} \section{Configuration} \label{sec:config} \subsection{Configuration Variables and Location of Configuration File} \label{sec:conf_file} The program defaults are sufficient for most cases. However, if you want to draw pedigrees in a language other than English, or to tweak the layout of the pedigrees, you need to change the program configuration. The behavior of the program \program{pedigree} is determined by \emph{configuration variables.} There are several sources of configuration variables. They are (in the order of increasing priority): \begin{enumerate} \item Program defaults. \item The system configuration file\footnote{On Unix-like systems, where \path{/etc} exists} \path{/etc/pedigree.cfg}. On \TeX Live the system coniguration files are \path{$TEXMFHOME/texmf-config/pedigree/pedigree.cfg} and \path{$TEXMFLOCAL/pedigree/pedigree.cfg}. \item User configuration file\footnote{On Unix-like systems, where \path{$HOME} exists} \path{$HOME/.pedigreerc}. \item The file specified by the |-c| option (see Section~\ref{sec:invocation}). \end{enumerate} If a file mentioned in this list does not exists, the program silently\footnote{Unless \path{-d} option is selected, see Section~\ref{sec:invocation}} continues. Note that even if a configuration file with higher priority exists, the program reads the files with lower priority first. The former \emph{overrides} the latter, but not precludes it from reading. In other words, if \path{/etc/pedigree.cfg} defines variables \lstinline|$foo| and \lstinline|$bar|, and \path{$HOME/.pedigreerc} defines \lstinline|$bar| and \lstinline|$baz|, the program takes \lstinline|$foo| from the first file, and \lstinline|$bar| and \lstinline|$baz| from the second one. \subsection{Configuration File Format} \label{sec:conf_file_format} All configuration files mentioned in Section~\ref{sec:conf_file}, have the same format. They are actually snippets of \program{Perl} code, executed by the program \program{pedigree}. This means, by the way, that all precautions usually taken with respect to programs and scripts, are relevant for configuration files as well. In particular, it is a bad idea to have world-writable system-wide configuration file \path{/etc/pedigree.cfg}. The code in configuration files is very simple, and one does not need to know \program{Perl} to edit configuration files. There are several simple rules which are enough to understand these files: \begin{enumerate} \item All text after \lstinline|#| to the end of the line is a comments. In particular, the lines starting with \lstinline|#|, are comment lines. \item \program{Perl} commands must end by semicolon \lstinline|;|. \item The commands like \begin{lstlisting} $xdist=1.5; \end{lstlisting} or \begin{lstlisting} @fieldsforprint=qw(Name DoB); \end{lstlisting} assign values to the variables. \item Variables starting with \lstinline|$| are scalars and take numerical or string values. Variables starting with \lstinline|@| are arrays and take list of values. \item A backslash in single quotes stands for itself, A backslash in double quotes or inside \lstinline|<