\chapter[\pxm' Filesystem Configuration]{\pxm' Filesystem Configuration}\label{chap:polyxmass-filesys-config}
The previous chapter dealt with how to teach \pxm\ a new polymer type (such a proteins, nucleic acids, polystyrene, polymethylmetacrylate\dots). Knowing how to teach the program a brand new polymer is crucial knowledge if the user wishes to use \pxm\ to its full power. While the reader might want to start immediately with learning how to use the program, we feel that, before doing this, it is necessary that the user be as well informed as possible about the configuration issues within \pxm\ (since these configuration issues will hamper use of the software program if not dealt with correctly).
\pxm\ only can deal with any number of different polymer types if it has a reliable means to know ---for each polymer type dealt with at any given time--- where to find the data required to process correctly the polymer sequence. This reliable means is \pxm' very standardized filesystem, with which the user is expected to comply.
This chapter goes a little farther in the knowledge of how \pxm\ internally understands polymer definitions. Indeed, the user must understand how a number of correlations are made during operation of \pxm. For example, how does the sequence editor know the way a monomer should be rendered graphically in it? The reader will understand in great detail how the whole bunch of configuration data required by \pxm\ are to be organized on the disk, so that the program can access them without error and with the greatest performance possible.
For the sake of simplicity, we'll call the \emph{stock confdata directory} the directory in which the installation procedure has developed the \pxm' filesystem. For our examples here, this directory is \filename{/usr/share/polyXmass} (meaning that \pxm\ was installed in the \filename{/usr} standard directory tree). Also, we'll assume that the user has made a personal copy of the stock confdata \filename{config} directory in his personal directory, namely \filename{/home/rusconi/pxmconfig} (meaning user ``rusconi'' has some personal polymer configuration data).
Please, do note that the \filename{/home/rusconi/pxmconfig} corresponds to the \filename{config} subdirectory of the \emph{stock confdata} directory (\filename{/usr/share/polyXmass/config}; only this subdirectory has chemistry-related configuration data ---atoms and polymers ---, which are inherently customizable by the user).
Making a personal copy of the \pxm\ filesystem is very useful when the user wants to modify/add polymer chemistries (or graphical rendering specifications for these). However, the program will not be aware of this until the user puts the relevant resource information in the \filename{.gnome/polyXmass} resource file in his home directory. The following section will tell you all about the \pxm' \filename{.gnome/polyXmass} resource file.
\section*{\pxm' resource file}
\addcontentsline{toc}{section}{\numberline{}\pxm' resource file}
While there are polymer-related configuration data (dealt with later in this chapter), there are also resource configuration bits which the user may want to store to configure the behaviour of \pxm.
These resource configuration bits are stored in a resource file: \filename{.gnome/polyXmass} in the user's home directory.
Each time the \pxm\ program is executed, it checks for the existence ---in the user's home directory--- of the \filename{.gnome/polyXmass} resource file. Whenever it does not find it (or does not find proper information in it) it initializes the program with default values. Please, see an example of such a resource file in the appendix, page~\pageref{apdx:user_resource_file}. The \filename{.gnome/polyXmass} file is the place where ---as the \pxm\ program will increase and more functionalities are added--- the resource configuration data will be organized in more and more data sections (see the file format in the appendix example) for customization data to be stored.
For what we are concerned with now (the location of the user's confdata directory), the user will let the program know that he has such a personal directory by setting the value of the \cfgkey{UserConfigDir} key in the \filename{.gnome/polyXmass} resource file to the absolute filename of the user's confdata directory (also called pathname, like \cfgval{/home/rusconi/pxmconfig}).
Thus, the line in the \filename{/home/rusconi/.gnome/polyXmass} file would read:
\begin{center}
\begin{verbatim}
UserConfigDir=/home/rusconi/pxmconfig
\end{verbatim}
\end{center}
Note that if the user has indeed a personal polymer-related data configuration directory, but does not want to use customized polymer definitions and configuration data, he can enter in his \filename{.gnome/polyXmass} resource file the following line:
\begin{center}
\begin{verbatim}
UserConfigDir=default
\end{verbatim}
\end{center}
This line indicates that \filename{/usr/share/polyXmass/config} is the proper directory for polymer definitions and configuration data.\\
Now that we know how to tell \pxm\ where to look for polymer configuration data and other configuration data ---through the use of a user-specific resource configuration file--- we can further study how polymer configuration data files are organized. There are two main categories of configuration data in \pxm:
\begin{itemize}
\item polymer-related configuration data, again divided into:
\begin{itemize}
\item polymer chemistry definition data (a polymer-specific single file,\\
\textit{i.e.} \filename{/usr/share/polyXmass/config/polyXmass-protein.dat});
\item house keeping configuration data (in files like \filename{polymer.dic} or \filename{pixmaps.dic}) ;
\end{itemize}
\item general house keeping configuration data, again divided into:
\begin{itemize}
\item graphical interface definition files (a single directory,\\
\textit{i.e.} \filename{/usr/share/polyXmass/glade-interface});
\item other different purpose files (atom definition file \dots)
\end{itemize}
\end{itemize}
\section*{Atom Definition Data}
\addcontentsline{toc}{section}{\numberline{}Atom Definition Data}
The atom definition data are stored in a single file called \filename{polyXmass-atoms.dat}, located in the \pxm' stock confdata \filename{config} subdirectory: \\ \centerline {\filename{/usr/share/polyXmass/config}}
%\[\textrm{\filename{/usr/share/polyXmass/config}}\]
No other place is currently allowed for this configuration data file, since it is of little interest to disseminate various atom definition files around. We will see, in the next section, that this does not apply to the polymer definition files, since these are very customizable (each different user of \pxm\ may be working on different sets of polymer types).
\section*{\pxm' Filesystem Standard}\label{sect:pol-filesys-std}
\addcontentsline{toc}{section}{\numberline{}\pxm' Filesystem Standard}
The root of the \pxm\ filesystem is the stock confdata directory, strictly-speaking. However, when a user makes a personal copy of the stock confdata directory, what is the real operational root of the filesystem is the \filename{config} subdirectory. This directory must contain all the polymer definition files and all the polymer directories.
Sorry for repeating this twice, but it is very important: all the polymer-related configuration data are located in the \filename{config} directory, itself located in the stock confdata directory (thus directory \filename{/usr/share/polyXmass/config}, and we'll speak about it using \filename{config} for short). If the user has in his resource \filename{.gnome/polyXmass} file a line indicating a valid value for the \cfgkey{UserConfigDir} key (like \cfgval{/home/rusconi/pxmconfig}, for example), then the program would search there for the polymer definition files and other polymer configuration data. All the \pxm\ polymer-related data configuration hierarchy is rooted in the \filename{config} stock confdata subdirectory, and the following section will highlight, in an orderly fashion, all the basic elements in this hierarchy.
\subsection*{Polymer Definition Files}
\addcontentsline{toc}{subsection}{\numberline{}Polymer Definition Files}
If you look in the \pxm' stock confdata \filename{config}, you would see that the polymer definition files are usually named according to the following scheme: \filename{polyXmass-\emph{poltype}.dat}. For the \emph{protein} polymer, the polymer definition would be stored in a file named something like \filename{polyXmass-protein.dat}. Note that the user can name the polymer definition files any way he wants, provided that they are located in the correct configuration directory and that they are correctly referenced in a dictionary file (see below for details).
This is well, so now the configuration directory has a number of different polymer definition files in it: one for \emph{protein}, another for \emph{saccharide}, a third for \emph{nucacids}, and so on\dots\ But how is \pxm\ going to use them? For example, upon reading a polymer sequence file, how is \pxm\ going to know which polymer definition file it should read in order to correctly interpret the data in the sequence file? The answer is in the polymer sequence file itself: each polymer sequence file (sequence file, for short) contains a piece of data that says what type of polymer it is. For example, a \emph{protein} polymer sequence file will necessarily contain a piece of data indicating something like \verb#<polyXmass:type> protein</polyXmass:type>#.
Open one of the polymer definition files with a text editor, and you'll see what \fileformat{XML}-formatted files look like.
\pxm\ is perfectly able to check that piece of information upon every reading of any sequence file, and in fact so does it. Once \pxm\ knows of what polymer type is a given sequence, it needs to know which polymer definition file it should use in order to interpret the data properly (\textit{i.e.} which polymer definition file corresponds to this precise polymer type). This is detailed in the next section. Equally important is the question of how does \pxm\ know from which directory it should load all the little graphics files that are used to render the monomers in the sequence editor? This is detailed in the next section also\dots\ Keep reading.
\subsection*{The \mbox{\filename{polymer.dic}} Dictionary File}
\addcontentsline{toc}{subsection}{\numberline{}The polymer.dic Dictionary File}
\pxm\ needs ---at every instant--- to know which polymer type definition file corresponds to any given polymer type. This correspondence is provided in the \filename{polymer.dic} dictionary file. This file lists the correspondences between the names of the different polymer types known to the system and their correspondent polymer definition file. The \filename{polymer.dic} file must be located in the \filename{config} directory.
The lines in this file ---of syntax \verb#polymer-type=pol-def-file|directory#--- should look like:\\
\begin{verbatim}
protein=polyXmass-protein.dat|protein
dna=polyXmass-dna.dat|nucacids
rna=polyXmass-rna.dat|nucacids
peptide=polyXmass-peptide.dat|protein
DNA=polyXmass-dna.dat|nucacids
\end{verbatim}
\makebox[1.85in]{\vdots} % creates an empy invisible box, centering in it the vertical dots.
Each time the user defines a new polymer type, he should register it by making a connection between the newly defined polymer type name (for example, \emph{protein}) and the file that holds the polymer definition (for example, \filename{polyXmass-protein.dat}). Note that the new polymer name registered in the \filename{polymer.dic} file must be the same (identical) as the one that is used to characterize the polymer type in the polymer definition data file. This connection is as easy as writing ---in the \filename{polymer.dic} dictionary file--- a line like the ones above. This is the only way that \pxm\ can be knowledgeable of what polymer definition file it should use to interpret data being read from a polymer sequence file (or from the keyboard, or whatever). The second element of information that is associated to the polymer definition name is the polymer definition directory. This is the directory where the graphics files and other polymer type-specific material is going to be stored. For the \emph{protein} polymer type, listed in the example above, the polymer definition file is \filename{polyXmass-protein.dat} and the polymer definition directory is \filename{protein}. The polymer definition directory is very important because it is the location where \pxm\ is going to reliably fetch polymer definition-specific data, for example for graphical polymer sequence rendering.
Check your local filesystem to see how this translates on your disk. The \filename{polymer.dic} dictionary file must be located in the \filename{config} stock confdata subdirectory or in the user's equivalent confdata directory. The \filename{config/protein} directory should contain a number of graphics files and a dictionary file that we'll all describe soon.
As we have seen in chapter~\ref{chap:polymer-def-process}, page~\pageref{chap:polymer-def-process}, the polymer definition file mainly contains polymer chemistry data (monomer formul{\ae}\dots), which is mainly oriented to letting \pxm\ perform mass calculation/elemental composition processes correctly.
We now ought to be concerned with the problem of displaying graphically the polymer sequence in the sequence editor. Indeed, now that \pxm\ knows how to check, from a given polymer sequence file, what polymer type there is in it, it should be able to know how to display correctly the polymer sequence in the graphical editor.
The graphical representation of a polymer sequence is ---by \pxm\ design--- polymer specific. That is, the user can configure the system to display different polymer types differently. I felt this was a powerful feature, because the chemist who works on synthetic polymers will most probably not want to display his polymer sequences the same way as would do the biochemist (working, say, on nucleic acids). \pxm\ allows an extremely high level of flexibility in this field also. The way \pxm\ ensures that the graphical representation of a given polymer sequence is performed correctly is described thoroughly in next section. The very first step, however, have we seen already: the \verb#|protein# information element in the \verb#protein=polyXmass-protein.dat|protein# is the directory where \pxm\ is asked to go fetch the data required for polymer sequence rendering when the polymer sequence being rendered is of type \emph{protein}. But what is in this directory?
\subsection*{The \mbox{\filename{pixmaps.dic}} Dictionary File}
\addcontentsline{toc}{subsection}{\numberline{}The pixmaps.dic Dictionary File}
The way \pxm\ ensures that the graphical display of any polymer sequence in the editor is performed according to polymer-specific user-defined guidances, is by assigning to each polymer type a set of little graphics objects.\footnote{We can call these little graphics objects \emph{icon}s (or \emph{pixmap}s in \OSname{UNIX} terminology), and since each of these icons is very tightly associated with their correspondent monomer, \pxm\ calls these specific little pixmaps \emph{monicon}s.}
Each polymer type must have a set of monicons; and each monomer has its uniquely associated monicon. It is by using the proper monicon for each monomer in the polymer sequence that the editor displays a polymer sequence like an ordered patchwork of little images (pixmaps, or icons). Each of these monicons must exist in the form of one little graphic file (a \emph{pixmap file}). Each monomer relies on a single pixmap file for its proper materialization in the sequence editor. All the pixmap files pertaining to a given polymer type (this is a set of monicons) must be located in a single polymer-specific directory (itself located in the usual \filename{config} directory). For the \emph{protein} polymer type, for example, we would have the following directory: \filename{/usr/share/polyXmass/config/\emph{protein}}.
It should be noted that more than one polymer type might share a given set of monicons. This means that \pxm\ should have a means of finding the correspondence between a polymer type and the directory in which all its monicons are stored. There is one file that gives these correspondences: the \filename{polymer.dic} dictionary file, that we have described earlier. The \verb#|protein# information element is there just for that, telling \pxm\ that the pixmaps for the \emph{protein} and for the \emph{peptide} polymer types are located precisely in the \filename{config/protein} directory (or the user's personal equivalent \filename{config/protein} directory).
Well, we are proceeding steeply, but what about the real graphical representation of the polymer sequence? If we used the analogy of a polymer sequence being a long word with letters not being separated with spaces, we could ask the question like this \textsl{``for each letter, how does \pxm\ guess how to represent it in the sequence editor? In other words: where is the font and what are its characters?''}. The next paragraphss explain this in detail.
The best way to explain how \pxm\ enforces a proper sequence display in the sequence editor is to detail, step by step, what happens internally when a sequence file is read from disk.
First, as we described already, \pxm\ checks in the sequence file what polymer type the sequence is. Let us say that the sequence file is of polymer type \emph{protein}. Knowing this, \pxm\ looks for the \cfgkey{protein} key, in the \filename{polymer.dic} dictionary file, in order to get the value which tells which directory is associated to this polymer definition. This directory is the place where all the monicons for the \emph{protein} polymer are stored (let us call this value \cfgval{monicons-dir}). If the \cfgval{\filename{monicons-dir}} value is valid, \pxm\ knows that all the pixmaps of the \emph{protein} polymer type are in \filename{monicons-dir}.
Well, this is correct. But, now that we know where all the little graphics files are located (the pixmaps we were talking about earlier), how does \pxm\ know which pixmap file should be used for which monomer?
Once again, the solution is a dictionary file: \pxm\ needs a correspondence dictionary file to make the correspondence between any single monomer code in a polymer definition and its correspondent pixmap file. This dictionary file, named \filename{pixmaps.dic}, must be located in the same directory as the one containing the pixmap files. For our example, that means that \filename{pixmaps.dic} must be located in the \filename{monicons-dir} directory.
The lines ---of syntax \verb#monomer-code=pixmap-file#--- should look like:
\begin{verbatim}
Ala=alanine.xpm
Y=tyrosine.xpm
\end{verbatim}
\makebox[1.2in]{\vdots} % creates an empy invisible box, centering in it the vertical dots.
What does all this mean? Simply that the graphical representation of a polymer sequence into the \pxm' graphical sequence editor is nothing else than an ordered patchwork that is made by sticking together as many monicons as there are monomers in the sequence! Upon reading of a polymer sequence (from the keyboard, from a disk file, or whatever), \pxm\ looks, for each monomer, how it should be represented in the editor.
Is not this design flexible? Certainly yes, because this means that you are entitled, as the user, to modify the visual aspect of every single monomer you use in your polymers.
To sum up a bit, and to use the font analogy that was proposed at the end of the previous section: we can say that the flexibility of the \pxm' design resides in the fact that the user is perfectly able to construct his own ``polymer writing'' fonts; and this simply by drawing each single character of them in the form of little graphics files.\footnote{Check the \filename{/usr/share/polyXmass/config/protein} directory and open a \filename{.xpm} file with a bitmap editing program, like \software{The Gimp} ---just enter \progname{gimp} at the prompt--- and you'll see how it is!}
If you look at the Figure~\ref{fig:dna-sequence-and-patchwork}, the screen dump shows a sequence editor with an oligonucleotide loaded; the right part of the figure shows a patchwork prepared using the monicons taken from single files (there were four different files, one for each different pixmap). The monicons for both the left and right parts of the figure were made using the exact same pixmap files on disk.
\begin{figure}
\begin{center}
\includegraphics[scale=1.5]{figures/scrumps/jpg/dna-sequence-and-patchwork.jpg}
\end{center}
\caption[Sequence display using pixmaps]{\textbf{The sequence is displayed graphically using a pixmap for each different monomer.} The left part of the figure shows a DNA sequence being displayed as an ordered succession of little pixmaps that were read from disk. The right part of the figure shows an unordered patchwork made by pasting onto a white sheet some pixmaps previously read from disk files. There were four pixmap files, one for each different nucleotide monicon. The pixmap files used were the same for both the parts of the figure.}
\label{fig:dna-sequence-and-patchwork}
\end{figure}
\section*{Configuring the \pxm' Filesystem}\label{sect:polyxmass-filesystem-config}
\addcontentsline{toc}{section}{\numberline{}Configuring the \pxm' Filesystem}
While \OSname{UNIX} fans will almost certainly choose to configure \pxm\ the ``unixian''-text file way, I programmed a graphical configuration module so that people more comfortable with graphical interfaces than with text terminals will feel at home even for this critical task.
The \guimenu{File}\guimenuitem{Preferences}\guimenuitem{Filesystem configuration} menu will open a window with a notebook in which each page deals with each one of the two \filename{polymer.dic} and \filename{pixmaps.dic} configuration files. Each notebook page has a columnar list widget and a number of other widgets, like combos\footnote{A combo widget is a hybrid widget that consists of a text entry widget, that the user sees always, and of a list widget that the user can drop down by clicking onto the downward arrow of the combo.}, text entries and buttons. Each list widget in each notebook page displays the contents of the \filename{polymer.dic} (page 1) and \filename{pixmaps.dic} (page 2) files. Please, see Figure~\ref{fig:fs-config-polymer-dic-page} and Figure~\ref{fig:fs-config-pixmaps-dic-page}.
\subsection*{The \mbox{\filename{polymer.dic}} Dictionary File}
\addcontentsline{toc}{subsection}{\numberline{}The polymer.dic Dictionary File}
\begin{figure}
\begin{center}
\includegraphics[scale=2]{figures/scrumps/jpg/fs-config-polymer-dic-page.jpg}
\end{center}
\caption[Filesystem configuration-polymer.dic]{\textbf{Filesystem configuration-polymer.dic.} The window is displayed with the first notebook page on top. This notebook page is entitled ``polymer.dic'' because it lists automatically the contents of the \filename{polymer.dic} dictionary file that \pxm\ uses at the moment of the configuration (be this file a user's private file, or the distribution original file). See text for details.}
\label{fig:fs-config-polymer-dic-page}
\end{figure}
The first notebook page deals with the \filename{polymer.dic} file exclusively. While the list only displays the contents of the \filename{polymer.dic} file, the user may trigger the update of the data pertaining to his own configuration: asking to parse his \filename{config} directory so that each polymer definition file found in it be scanned and its name displayed. The same holds true for all the polymer definition directories. Each of these updates are triggered by clicking onto their related button: \guilabel{refresh File list} and \guilabel{refresh Dir list}. The first button will parse the \filename{config} \pxm' filesystem root directory and list in the second combo widget all the found \emph{valid} polymer definition files.\footnote{The program will test each file for \fileformat{XML}-well-formedness before making it an item in the list.} The second button will parse the \filename{config} \pxm' filesystem root directory and list in the third combo widget all the found polymer definition directories (actually it will list indiscriminately \emph{all} the directories found beneath the \filename{config} directory, as it has no means to assess if any directory is a valid polymer definition directory or not). We did not speak of the first combo. Well, this combo is where the user will edit new items. While the other combo textual elements cannot be new (they must be identical to one of the items in the relevant combo list), the first combo is where the user will define new polymer definition names.
For a new polymer definition name to be inserted in the \filename{polymer.dic} file, it must be associated to a valid polymer definition file name and it must also be associated to an existing polymer definition directory. Once the polymer definition name is satisfactorily entered in its combo entry, and that the polymer definition file and the polymer definition directory have been chosen from their respective combo list, the user may click onto the \guilabel{APPEND} or \guilabel{INSERT} button. This will check that the data entered are correct and if so will append/insert the newly constructed item to the list.
To remove an item, just select it from the list and click onto the \guilabel{REMOVE} button. Once the list reflects exactly the desired contents of the \filename{polymer.dic} file, just click onto the \guilabel{WRITE FILE} button. This will backup your file with a '$\sim$' appended to the end of its original file name and write a brand new \filename{polymer.dic} file, strictly identical to the just-tailored list contents.
\subsection*{The \mbox{\filename{pixmaps.dic}} Dictionary File}
\addcontentsline{toc}{subsection}{\numberline{}The pixmaps.dic Dictionary File}
\begin{figure}
\begin{center}
\includegraphics[scale=2]{figures/scrumps/jpg/fs-config-pixmaps-dic-page.jpg}
\end{center}
\caption[The Filesystem configuration-pixmaps.dic]{\textbf{Filesystem configuration-pixmaps.dic.} When the user has selected a polymer definition name from the list in the first notebook page, and next switches to the second (this) notebook page, all the data are updated automatically. See text for details.}
\label{fig:fs-config-pixmaps-dic-page}
\end{figure}
The second notebook page is a bit more complicated than the first. Its role is to ease the process of configuring the way the monomers should be rendered in the graphical sequence editor. There are two different situations that we have to deal with: when the monomer is not going to be modified (that's the easy situation) and when the monomer is modified (that is the more complicated situation).
Contrary to the \guilabel{polymer.dic} notebook page, which has its list immediately filled with the \filename{polymer.dic} file contents, the \guilabel{pixmaps.dic} notebook page is not filled as soon as the window is opened. This is simply because, in the \pxm\ filesystem there is one \filename{pixmaps.dic} file per polymer definition. This \filename{pixmaps.dic} file is located into the polymer definition directory. When the window is opened at first, no item in the list of the \guilabel{polymer.dic} notebook page is selected, so the program has no means to know of which polymer definition it should list the \filename{pixmaps.dic} file's contents.
To let the program know that the user is interested in any given polymer definition, all is needed is to select the proper item from the list of the first page (list of the polymer definitions). Once this is done, the user can switch to the notebook's second page, and this time all the relevant \filename{pixmaps.dic} file's data will be listed properly in the list. Also, the combo lists will be updated automatically (the user can even trigger updates by clicking onto the desired button).
The organization of the second notebook's page is very similar to the first one described above, unless the columned list in it has four columns. The first column lists all the monomer codes currently known to the program for the currently selected polymer definition (from the \filename{pixmaps.dic} file). The second column lists the modification name that a monomer might undergo. In the distribution, the lines of the \filename{pixmaps.dic} file that deal with monomer modification are the last ones, so scroll the list to see them. The third column lists (when the row deals with a monomer modification) the graphical operation that must be performed to render the modification into the sequence editor. See more detailed explanations page~\pageref{sect:monomer-target-definition}. The third column lists the pixmap files that have been chosen to render the monomers. Each list row corresponds very precisely to the contents of a line of the \filename{pixmaps.dic} file. The process by which an item is modified and added is the same as the one described for the other notebook page.
The button labeled \guilabel{refresh Polymer definition data} triggers the parsing of the polymer definition file. Next, the program lists ---in the first combo's list--- all the monomers available to the polymer definition and ---in the second combo's list--- all the modifications the are known to the polymer definition. The button labeled \guilabel{refresh File list} will parse all the files contained in the polymer definition directory, check that each parsed file is a valid graphics file and display its name in the fourth combo's list. \footnote{The following graphics formats are recognized: \fileformat{xpm jpg png tif}.} The third combo's list contains only three unchanging items: the empty string (``''), ``T'' (transparent compositing'') and ``O'' (opaque compositing). These are the instructions that the program will follow upon chemical modification of a monomer in the sequence editor. This is going to be described in detail in the next chapter.
The graphical configuration module has been devised to be restrictive, in such a way that the user can easily ---and with no error--- construct new items to put in the columnar lists (and thus in the \filename{polymer.dic} and \filename{pixmaps.dic} files).
\cleardoublepage
