This document describes the Babase baboon data management system. This includes a description of the tables, the intended use of all related programs and directories, the design of the system, and procedures for maintaining the data management system itself. This document does not include the procedures actually used to enter data into the system, or the details of how to operate the systems programs. Nor does it include any instructions on the operation or administration of the computer itself. Further information on the topics not covered in this document can be found in the Protocol for Data Management: Amboseli Baboon Project document.
The Protocol for Data Management: Amboseli Baboon Project document is an important adjunct to the Babase system, but it is not considered part of the system itself because it describes the use of the system but not the capabilities of the system. It is important to maintain the distinction between use and capabilities so that when an enhancement is needed, it is clear whether the desired result can be obtained by altering the way the system is used, or whether the system itself needs to be modified. It is also important to provide different types of documentation to those who operate the system from those who manage and maintain the system because each of these two groups do not need to know all the details of the others' work.
Any deviation from the standards described in this document should be discussed with the project directors and may God have mercy on your souls.
This document follows a number of conventions, most of them typographic but some of them stylistic. Some output formats, particularly plain text, have limited typographic capabilities so the various forms of typographic markup are not always distinguishable, either from each other or from the surrounding text.
Each table in Babase is documented in a section of its own, beginning with a description of the table as a whole and continuing with sub-sections for each column in the table. Of particular importance is the sentence that describes what a row in the given table represents. These are summarized in the textual tables given in the Table Overview section.
Interrelationships between the columns of a table, or between tables, is documented at the beginning of the table's section, not in the sub-sections documenting the columns themselves. Although relationships between 2 tables concern both of the tables the description of each such relationship appears only once in this document, in the overall description of one of the of the two tables concerned. On occasion there may be be brief mention elsewhere.
All TABLE NAMES are written in UPPER CASE. Column Names are in lower case with Initial Capitals. SOMETABLE.Somecolumn is shorthand for “the Somecolumn column of the SOMETABLE table”. The use of a period to separate the table from the column name is the convention used by SQL to eliminate ambiguity regarding which table a column belongs to. When a column name includes an acronym the acronym is capitalized, as is the first letter of the next word when the acronym begins the column name. For example, PCSColor.
Actual database values are typographically distinguished
from the surrounding text, as in the following sentence:
“The Sname (short name) of the baboon Pebbles is
PEB.”
When this document defines a word, uses it for the first time, or otherwise wishes to refer to a word or phrase as a thing in and of itself, the word or phrase is typographically distinguished as follows: “The word census has several meanings within this document.”
Text that has special meaning to computer systems is
typographically distinguished as follows: “The SQL
SELECT statement is the standard method for
retrieving data from relational databases.”
Emphasized text is typographically distinguished as follows: “Always backup your data.”
When the words must or cannot or the phrases must not or may not are used, the system will not allow a contrary condition. For example: "Sname must be a unique data value" or "A user with read-only permissions may not change data values." Babase will immediately raise an error when a dis-allowed change is attempted and the change will not take effect.
When the words should or ought are used the system does not enforce the condition. It may or may not report a violation of the condition. An example: "The sexual cycle event referred to in the pregnancy table's Conceive column should date the conception that began the pregnancy." In this case the system has no way of knowing when the pregnancy began and so no way of validating the date.
When the phrase the system will report is used there is some mechanism for reporting a an unusual but not dis-allowed condition. Unlike prohibited conditions, unusual conditions are not generally reported at the time the condition is created.[1]
The documentation is written with a tendency to emphasize Special Values. So, for example, “not alive” is often written instead of “dead” because Babase has a special value that means alive but the system is not aware of a particular code that means dead. The result is an occasional double negative.
Significant but often slightly off-topic paragraphs are set off from the surrounding material as a note, shown in Example 1.1.
Example 1.1. A note
Note
Written material has no voice that can be raised, but attention can be drawn with typographical conventions.
When the reader should take care, particularly when the system might do something unexpected in a given circumstance, this is noted in a caution. Example 1.2 shows how a caution is set off from the surrounding text.
Example 1.2. A caution
Babase will reject your change if you try to do something that is not allowed, like giving a male an onset of turgesence date.
Caution
When the rejected change is one of a number of changes bundled into a transaction none of the changes will make it into the database.
When a mis-use of the system will lead to incorrect results, particularly when such results are not obvious, this document contains a warning. Example 1.3 show how warnings are set off from the surrounding text.
Example 1.3. A warning
Warning
Babase cannot detect when an Sname is mis-typed, so it is possible to inadvertently assign a female's sexual cycle to the wrong female.
To otherwise draw the readers attention to material some text is marked important. Example 1.4 show how important text is set off from the surrounding material.
Example 1.4. Text denoted important
Babase has a number of components, many of them, like the SQL web interface, are third party tools, not written by the Babase developers.
Important
When the third party tools are upgraded their “look” may change but the features they provide should remain. As Babase is composed of Free Software the Babase project always has the option of customizing any of its third party tools and can contribute its improvements back to the program's developers for inclusion into future releases.
Suggestions as to how to use Babase are noted in tips, as are remarks on how data are presently entered in Babase or recorded in the field. Example 1.5 show how a tip is set off from the regular document text.
Often, the tips are the result of best practice
developed from considered experience and so document how
Babase is used at the time of this writing. However, as best
practice continues to develop and field protocols change, the
Protocol for Data
Management: Amboseli Baboon Project and the Amboseli
Baboon Research Project Monitoring Guide should always be
consulted. Those documents have precedence over the tips
presented herein should there be conflicting advice.
Supplemental and cross-referential material is presented in footnotes.
Anyone who is changing or adding programs to the system should read this entire document. Chapter 3: “Baboon Data: Primary Source Material” is particularly important for all those using the system. Chapter 2: “Babase System Architecture” provides the introduction to Babase. It explains fundamental concepts without which Babase cannot be understood, although some portions can be skipped; the sections “The Babase Program Code” and “Indexes” are primarily of interest to programmers and the section “Special Values” is for the data maintainers. Everyone will want to pay special attention to the “Entity-Relationship Diagrams” section. These diagrams can also be found in PDF form in The Babase Pocket Reference, where they may be easier on the eye. The section “Data Maintenance Programs” of chapter 8: “Babase Programs” is of little interest to those who only want to retrieve information from the system. Portions of the “Useful Programs and Functions” section of the same chapter is of interest to the more sophisticated user. Note that some functions may be hidden in “Next” links, depending on the format chosen when reading this document. Data maintainers should be sure to understand chapter 5: “Support Tables”. Those who are only retrieving data from Babase need not read chapter 7: “Data Entry”.