From 855e70674d98d135e5996f3919565dff131c69ac Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Thu, 1 Jun 2023 18:04:00 -0500 Subject: [PATCH] Begin to document tables Improve the introduction sub-sections and special values. Introduce some code tables. Document BIOGRAPHY, COMM_MEMBS, and COMM_MEMBS_LOG. --- doc/src/architecture/special_values.m4 | 27 ++- doc/src/code_tables.m4 | 261 ++++++++++++++++++++++++ doc/src/epilog.inc.m4 | 93 ++++++++- doc/src/index.m4 | 2 + doc/src/intro/about_db.m4 | 9 + doc/src/intro/about_doc.m4 | 12 +- doc/src/tables.m4 | 33 +++ doc/src/tables/biography.m4 | 271 +++++++++++++++++++++++++ doc/src/tables/comm_memb_log.m4 | 105 ++++++++++ doc/src/tables/comm_membs.m4 | 127 ++++++++++++ include/constants.m4 | 33 ++- 11 files changed, 957 insertions(+), 16 deletions(-) create mode 100644 doc/src/code_tables.m4 create mode 100644 doc/src/tables.m4 create mode 100644 doc/src/tables/biography.m4 create mode 100644 doc/src/tables/comm_memb_log.m4 create mode 100644 doc/src/tables/comm_membs.m4 diff --git a/doc/src/architecture/special_values.m4 b/doc/src/architecture/special_values.m4 index 0d4b709..b521afd 100644 --- a/doc/src/architecture/special_values.m4 +++ b/doc/src/architecture/special_values.m4 @@ -32,7 +32,7 @@ or deleting codes to or from the tables which define the system's vocabulary. At times, SokweDB recognizes that particular codes have special -meanings, for example, the BIOGRAPHY_ table's ``sdb_female`` (female) +meanings, for example, the |BIOGRAPHY| table's ``sdb_female`` (female) Sex code. The meaning of these codes is fixed into the logic of the system. As examples, an individual must be female to be allowed to have a menstruation, or, the individual must be in the community to be @@ -42,8 +42,8 @@ defined in support or other tables. Because these codes have intrinsic meaning, they cannot be removed from the SokweDB system nor should their presence in the data be used to code a different meaning from that which the code presently has. For example, the meaning of -DEPARTTYPES_ code value ``sdb_end_of_obs`` (alive\ [#f11]_) should not -be changed to mean “death due to meteorite impact” because the +|DEPARTTYPES| code value ``sdb_end_of_obs`` (alive\ [#f11]_) should +not be changed to mean “death due to meteorite impact” because the system's programs would then allow individuals to have sexual cycles after death. Each of the "special" values that the system requires retain particular meaning is listed in the Special Values section of @@ -56,13 +56,13 @@ adjusted to reflect the change. SokweDB prevents ordinary users from altering rows that contain special values in an attempt to prevent mis-configuration of the system. Only users with permissions to modify a table's triggers may -alter the table's special values. This is not a panacea. To return to -the example above, not only does the system expect a DEPARTTYPES_ code -of ``sdb_end_of_obs`` to mean alive, it also expects -``sdb_end_of_obs`` to be the only code in DEPARTTYPES_ that means -alive. If another DEPARTTYPES_ code is created to indicate a more -specific sort of "alive-ness", unless re-programmed the system will -consider all individuals given that code to be dead, not alive. A +alter the table's special values.\ [#f12]_ This is not a panacea. To +return to the example above, not only does the system expect a +|DEPARTTYPES| code of ``sdb_end_of_obs`` to mean alive, it also +expects ``sdb_end_of_obs`` to be the only code in |DEPARTTYPES| that +means alive. If another |DEPARTTYPES| code is created to indicate a +more specific sort of "alive-ness", unless re-programmed the system +will consider all individuals given that code to be dead, not alive. A careful review of the documentation should be undertaken before modifying the content of tables that instantiate special values. @@ -70,3 +70,10 @@ modifying the content of tables that instantiate special values. .. [#f10] As opposed to the system's programmers. .. [#f11] Specifically, "still alive and present as of the last census date". + +.. [#f12] + Rather than create another role just to control the alteration of + special values the choice was made to use PostgreSQL's ``TRIGGER`` + privilege. This allows superusers (or the somewhat less + privileged) the necessary access. This conveniently separates + regular users from those who can do more. diff --git a/doc/src/code_tables.m4 b/doc/src/code_tables.m4 new file mode 100644 index 0000000..6776fd3 --- /dev/null +++ b/doc/src/code_tables.m4 @@ -0,0 +1,261 @@ +.. Copyright (C) 2023 The Meme Factory, Inc. www.karlpinc.com + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + +.. M4 setup +include(constants.m4) +include(macros.m4) +sdb_rst_quotes(`on') +sdb_generated_rst() + +.. contents:: + :depth: 2 + +.. code_tables: + +Code Tables +=========== + + +.. _COMM_IDS: + +COMM_IDS (Community IDentifiers) +-------------------------------- +.. |COMM_IDS_summary| replace:: + Each row represents a community. There is one row for every + chimpanzee community on which any information has been recorded, + whether presently under-study or not. + +|COMM_IDS_summary| This includes the special community named +``sdb_unknown_comm``, which is used when an individual cannot be +assigned to a community. + + +.. _COMM_IDS_special_values: + +Special Values +`````````````` + +The |COMM_IDS.CommID| value of ``sdb_unknown_comm`` is special. + + +Column Descriptions +``````````````````` + +.. _COMM_IDS.CommID: + +Comm_ID (Community IDentifier) +'''''''''''''''''''''''''''''' + +.. |COMM_IDS.CommID_summary| replace:: + A short sequence of characters which identify a community. + +|COMM_IDS.CommID_summary| |keycol| + + +.. _COMM_IDS.Name: + +Name +'''' + +.. |COMM_IDS.Name_summary| replace:: + The name of the community. + +|COMM_IDS.Name_summary| |emptytext| |notnull| + + +.. _COMM_IDS.Notes: + +Notes +''''' + +.. |COMM_IDS.Notes_summary| replace:: + Notes on the community, how membership is assigned and other + relevant information. + +|COMM_IDS.Notes_summary| |notonlyspaces| |notnull| + + +.. _COMM_IDS.MembCriteria: + +MembCriteria (Membership Criteria) +'''''''''''''''''''''''''''''''''' + +.. |Comm_IDS.MembCriteria_summary| replace:: + A description of the requirements to be a member of the community. + +|COMM_IDS.MembCriteria_summary| |notonlyspaces| |notnull| + + +.. _DEPARTTYPES: + +DEPARTTYPES (community Departure reasons) +----------------------------------------- + +.. |DEPARTTYPES_summary| replace:: + Contains one row for each way a chimpanzee can leave a community, + plus a special row with a code of ``sdb_unknown_comm`` to indicates + the individual was in the community when last observed. + +|DEPARTTYPES_summary| + + +Special Values +`````````````` + +The |DEPARTTYPES.DepartType| value of ``sdb_unknown_comm`` is special. +It indicates the individual is still alive and in the community. Only +individuals that are in a community may be observed in the community. + + +Column Descriptions +``````````````````` + +.. _DEPARTTYPES.DepartType: + +DepartType +'''''''''' + +.. |DEPARTTYPES.DepartType_summary| replace:: + A one character code identifying a way an individual can leave a community. + +|DEPARTTYPES.DepartType_summary| |keycol| |uppercase| + + +.. _DEPARTTYPES.Description: + +Description +''''''''''' + +.. |DEPARTTYPES.Description_summary| replace:: + A description of the code. + +|DEPARTTYPES.Description_summary| |emptytext| + + +.. _ENTRYTYPES: + +ENTRYTYPES (community Entry reasons) +------------------------------------ + +.. |ENTRYTYPES_summary| replace:: + Contains one row for each way a chimpanzee can enter a community. + +|ENTRYTYPES_summary| + + +Special Values +`````````````` + +None. + + +Column Descriptions +``````````````````` + +.. _ENTRYTYPES.EntryType: + +EntryType +''''''''' + +.. |ENTRYTYPES.EntryType_summary| replace:: + A one character code identifying a way an individual can enter a community. + +|ENTRYTYPES.EntryType_summary| |keycol| |uppercase| + + +.. _ENTRYTYPES.Description: + +Description +''''''''''' + +.. |ENTRYTYPES.Description_summary| replace:: + A description of the code. + +|ENTRYTYPES.Description_summary| |emptytext| |notnull| + + +.. _PEOPLE: + +PEOPLE +---------- + +.. |PEOPLE_summary| replace:: + Contains one row for each person involved in data collection. + +|PEOPLE_summary| Anyone who's identity is recorded in SokweDB +must have a row representing them in this table. + +Note that, for reasons of simplicity and performance, SokweDB accepts +only the ASCII character set.\ [#f14]_ (Those characters found on a +standard U.S. keyboard.) + + +Special Values +`````````````` + +None. + + +Column Descriptions +``````````````````` + +.. _PEOPLE.Person: + +Person +'''''' + +.. |PEOPLE.Person_summary| replace:: + A short character string used to identify the person. + +|PEOPLE.Person_summary| |keycol| + + +.. _PEOPLE.Name: + +Name +'''' + +.. |PEOPLE.Name_summary| replace:: + The name of the person. + +|PEOPLE.Name_summary| |emptytext| |notnull| + + +.. _PEOPLE.Description: + +Description +''''''''''' + +.. |PEOPLE.Description_summary| replace:: + A description of the person, should such be necessary to distinguish + them from other people with the same or similar name. + +|PEOPLE.Description_summary| |notonlyspaces| |notnull| + + +.. rubric:: Footnotes + +.. [#f14] The database could accept the full-set of Unicode characters, + providing glyphs for all languages and cultures as well as a + full set of emoji. And if collation (sorting) was + configured so as *not* to support language and cultural + conventions then there would be no performance impact. + + But this would allow, say, chimpanzees to be named with + Chinese ideographic glyphs; allow arbitrary glyphs to be + used anywhere text might appear. Because this is not + desired we would need to institute additional controls to + keep the data clean. It is simpler to live with the ASCII + character set when it comes to recording people's names. diff --git a/doc/src/epilog.inc.m4 b/doc/src/epilog.inc.m4 index 17e5712..656224e 100644 --- a/doc/src/epilog.inc.m4 +++ b/doc/src/epilog.inc.m4 @@ -35,10 +35,99 @@ sdb_generated_rst()dnl https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model -.. Substitutions (used to give labels to internal links) +.. Table and column name substitutions, so we can add "extra comments" to + the section heading and still get a link label with the name of the + table or column. +.. |BIOGRAPHY| replace:: :ref:`BIOGRAPHY ` +.. |BIOGRAPHY.AnimID| replace:: :ref:`AnimID ` +.. |BIOGRAPHY.BDMin| replace:: :ref:`BDMin ` +.. |BIOGRAPHY.BDMax| replace:: :ref:`BDMax ` +.. |BIOGRAPHY.BirthComm| replace:: :ref:`BirthComm ` +.. |BIOGRAPHY.BirthDate| replace:: :ref:`BirthDate ` +.. |BIOGRAPHY.DepartDate| replace:: :ref:`DepartDate ` +.. |BIOGRAPHY.EntryDate| replace:: :ref:`EntryDate ` +.. |BIOGRAPHY.FirstBorn| replace:: :ref:`FirstBorn ` -.. |allownull| replace:: This column may be ``NULL``. + +.. |COMM_IDS| replace:: :ref:`COMM_IDS ` +.. |COMM_IDS.CommID| + replace:: :ref:`CommID ` +.. |COMM_IDS.Name| + replace:: :ref:`Name ` +.. |COMM_IDS.Notes| + replace:: :ref:`Notes ` +.. |COMM_IDS.MembCriteria| + replace:: :ref:`MembCriteria ` + +.. |COMM_MEMB_LOG| replace:: :ref:`COMM_MEMB_LOG ` + +.. |COMM_MEMBS| replace:: :ref:`COMM_MEMBS ` +.. |COMM_MEMBS.StartDate| replace:: :ref:`StartDate ` +.. |COMM_MEMBS.EndDate| replace:: :ref:`EndDate ` + +.. |DEPARTTYPES| replace:: :ref:`DEPARTTYPES ` +.. |DEPARTTYPES.DepartType| + replace:: :ref:`Code ` +.. |DEPARTTYPES.Description| + replace:: :ref:`Code ` + +.. |ENTRYTYPES| replace:: :ref:`ENTRYTYPES ` +.. |ENTRYTYPES.EntryType| + replace:: :ref:`EntryType ` + +.. |PEOPLE| replace:: :ref:`PEOPLE ` +.. |PEOPLE.Person| replace:: :ref:`Person ` + +.. Substitutions, standardized phrases and sentences. + +.. Values + +.. |null| replace:: ``NULL`` + +.. |true| replace:: ``TRUE`` + +.. |false| replace:: ``FALSE`` + +.. Sentences + +.. |unique| replace:: + Each value stored in this column must be unique. + +.. |notnull| replace:: + This column may *not* be |null|. + +.. |allownull| replace:: + This column may be |null|. + +.. |notempty| replace:: + This column may not be empty, it must contain characters. + +.. |emptytext| replace:: + This column may not be empty, it must contain characters and it must + contain at least one non-whitespace character. + +.. |nospaces| replace:: + This column may not contain whitespace characters. + +.. |notonlyspaces| replace:: + This column may be empty. It need not contain characters, but it + may not contain only whitespace characters. + +.. Used in code table documentation of the key columns. +.. |keycol| replace:: + |unique| |notnull| |notempty| |nospaces| + +.. Used in data table documentation of automatically generated ID columns. +.. |idcol| replace:: + A unique, automatically generated, positive integer which serves to + identify the row. + +.. |uppercase| replace:: + This column may not contain lower case letters. + + +.. Substitutions, used to give labels to internal links .. The upload schema, which is not yet documented .. |Uploads| replace:: :ref:`Uploads ` diff --git a/doc/src/index.m4 b/doc/src/index.m4 index 933a5fe..7bec5da 100644 --- a/doc/src/index.m4 +++ b/doc/src/index.m4 @@ -32,6 +32,8 @@ Technical Documentation intro.rst architecture.rst er_diagrams.rst + code_tables.rst + tables.rst appendices.rst .. Add these back later.... diff --git a/doc/src/intro/about_db.m4 b/doc/src/intro/about_db.m4 index 5ddc1f0..315fb8f 100644 --- a/doc/src/intro/about_db.m4 +++ b/doc/src/intro/about_db.m4 @@ -67,6 +67,7 @@ Individual accounts are given their own, private, workspaces (:ref:`schemas `). This separates private from shared data, which allows for better long-term data maintenance. + About Databases ``````````````` @@ -76,6 +77,10 @@ database. Access to data outside a database, from within the database, is possible but requires additional work that depends upon the data source. + +About Tables +```````````` + Databases store data in tables. Related singleton datum, such as a single name, a single birthdate, a mother, are kept together in a single row of a table constructed to hold this particular kind of @@ -91,6 +96,10 @@ meters, and the id of the 2nd chimpanzee. Each column of a table is expected to contain the same "kind" of data; a name should not go in the "birthdate"column. +The SokweDB design endeavors to name tables in the plural, as they hold +multiple rows. Column names are singular, as each column of each +table holds a single value. + .. _views: diff --git a/doc/src/intro/about_doc.m4 b/doc/src/intro/about_doc.m4 index 9c107f5..4bc06b3 100644 --- a/doc/src/intro/about_doc.m4 +++ b/doc/src/intro/about_doc.m4 @@ -57,7 +57,7 @@ is a value. The empty string\ [#f4]_ is a string and so it is reasonable to compare it with other non-empty strings. The empty -string is distinct from ``NULL``\ [#f5]_, which means "no +string is distinct from |null|\ [#f5]_, which means "no information", and is used when there is no value/no data at all. Data consistency is guaranteed only when the guarantee is explicitly @@ -76,6 +76,12 @@ A Guide for the Reader This is a reference document, and as such is not expected to be read from front-to-back. +Care must be taken when querying columns which allow |null| values. +SQL uses a `three valued logic `_, the values being |true|, +|false|, and |null|. This only comes into play when a |null| value is +encountered but can be a particularly important factor when a single +query relates multiple tables. + .. rubric:: Footnotes @@ -87,8 +93,10 @@ from front-to-back. .. [#f4] Written ``''`` in SQL. -.. [#f5] Written ``NULL`` in SQL. +.. [#f5] Written |null| in SQL. .. [#f15] The notations in the :ref:`erdiagrams` are dense in constraints, constraints built into the database, which ensure data integrity. + +.. _SQL logic: https://www.postgresql.org/docs/current/functions-logical.html diff --git a/doc/src/tables.m4 b/doc/src/tables.m4 new file mode 100644 index 0000000..d44b236 --- /dev/null +++ b/doc/src/tables.m4 @@ -0,0 +1,33 @@ +.. Copyright (C) 2023 The Meme Factory, Inc. www.karlpinc.com + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + +.. M4 setup +include(constants.m4) +include(macros.m4) +sdb_rst_quotes(`on') +sdb_generated_rst() + + +.. data_tables: + +Data Tables +=========== + +.. toctree:: + :maxdepth: 3 + + tables/biography.rst + tables/comm_membs.rst + tables/comm_memb_log.rst diff --git a/doc/src/tables/biography.m4 b/doc/src/tables/biography.m4 new file mode 100644 index 0000000..646765d --- /dev/null +++ b/doc/src/tables/biography.m4 @@ -0,0 +1,271 @@ +.. Copyright (C) 2023 The Meme Factory, Inc. www.karlpinc.com + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + +.. M4 setup +include(constants.m4) +include(macros.m4) +sdb_rst_quotes(`on') +sdb_generated_rst() + +.. _BIOGRAPHY: + +BIOGRAPHY +--------- + +.. |BIOGRAPHY_summary| replace:: + Each row represents a chimpanzee. This table contains one row for + each chimpanzee on which data has ever been recorded (in SokweDB), + and an additional row for ``sdb_unk`` a generic value used when a + chimpanzee is unrecognized. + +|BIOGRAPHY_summary| BIOGRAPHY contains the basic demographic data of +individual chimpanzees. + +When the individual is not the first recorded offspring of their +mother, based on the |BIOGRAPHY.BirthDate| of all recorded maternal +siblings, the |BIOGRAPHY.FirstBorn| value must be +``sdb_not_firstborn`` (not first born). + +The date the individual entered the study (|BIOGRAPHY.EntryDate|) may +not be before the individual's birth date (|BIOGRAPHY.BirthDate|). + +The date the individual left the study (|BIOGRAPHY.DepartDate|) may +not be before the date the individual entered the study +(|BIOGRAPHY.EntryDate|). + + +.. _BIOGRAPHY.AnimID: + +AnimID (Animal IDentifier) +`````````````````````````` + +.. |BIOGRAPHY.AnimID_summary| replace:: + A short sequence of characters which uniquely identify the chimpanzee. + +|BIOGRAPHY.AnimID_summary| |keycol| + + +.. _BIOGRAPHY.AnimIDNum: + +AnimIDNum (Animal IDentifier Number) +```````````````````````````````````` + +.. |BIOGRAPHY.AnimIDNum_summary| replace:: + A unique positive integer used to identify the chimpanzee in SIV papers. + +|BIOGRAPHY.AnimIDNum_summary| |unique| |notnull| + + +.. _BIOGRAPHY.AnimName: + +AnimName (Animal Name) +`````````````````````` + +.. |BIOGRAPHY.AnimName_summary| replace:: + The name of the chimpanzee. + +|BIOGRAPHY.AnimName_summary| |emptytext| |notnull| + + +.. _BIOGRAPHY.BirthComm: + +BirthComm (Birth Community) +``````````````````````````` + +.. |BIOGRAPHY.BirthComm_summary| replace:: + The |COMM_IDS|.\ |COMM_IDS.CommID| of the community in which the + individual was born. + +|BIOGRAPHY.BirthComm_summary| This column may be |null| when the birth +community is unknown. + + +.. _BIOGRAPHY.BCCertainty: + +BCCertainty (Birth Community Certainty) +``````````````````````````````````````` + +.. |BIOGRAPHY.BCCertainty_summary| replace:: + A code indicating the certainty of the |BIOGRAPHY.BirthComm|, the + certainty of the birth community. Only 2 values are allowed, + ``sdb_bg_certain`` when the birth community is certain and + ``sdb_bg_uncertain`` when the birth community is uncertain. + +|BIOGRAPHY.BCCertainty_summary| |notnull| + + +.. _BIOGRAPHY.Sex: + +Sex +``` + +.. |BIOGRAPHY.Sex_summary| replace:: + A code indicating the sex of the individual. Only 3 values are allowed: + ``sdb_male`` for males, ``sdb_female`` for females, and ``sdb_unk_sex`` + when the sex is unknown. + +|BIOGRAPHY.Sex_summary| |notnull| + + +.. _BIOGRAPHY.MomID: + +MomID (Mother's AnimID) +``````````````````````` + +.. |BIOGRAPHY.MomID_summary| replace:: + The |BIOGRAPHY.AnimID| of the individual's mother, when known. + +|BIOGRAPHY.MomID_summary| |allownull| + + +.. _BIOGRAPHY.DadID: + +DadID (Father's AnimID) +``````````````````````` + +.. |BIOGRAPHY.DadID_summary| replace:: + The |BIOGRAPHY.AnimID| of the individual's father, when known. + +|BIOGRAPHY.DadID_summary| |allownull| + + +.. _BIOGRAPHY.DadIDPub: + +DadIDPub (Publication of Paternity) +``````````````````````````````````` + +.. |BIOGRAPHY.DadIDPub_summary| replace:: + Citation of the publication where paternity was declared, or 'Unknown' when + paternity has not yet been published. + +|BIOGRAPHY.DadIDPub_summary| |notnull| + + +.. _BIOGRAPHY.FirstBorn: + +FirstBorn +````````` + +.. |BIOGRAPHY.FirstBorn_summary| replace:: + A code indicating whether the individual is the mother's first + born. One of 3 values are allowed: ``sdb_firstborn`` means known to + be the first born, ``sdb_not_firstborn`` means known not to be the + first born, and ``sdb_unk_firstborn`` means that the firstborn + status is unknown. + +|BIOGRAPHY.FirstBorn_summary| |notnull| + + +.. _BIOGRAPHY.BirthDate: + +BirthDate +````````` + +.. |BIOGRAPHY.BirthDate_summary| replace:: + The individual's (often estimated) birth date. + +|BIOGRAPHY.BirthDate_summary| |notnull| + + +.. _BIOGRAPHY.BDMin: + +BDMin (Minimum Birth Date) +`````````````````````````` + +.. |BIOGRAPHY.BDMin_summary| replace:: + The earliest possible birthdate. + +|BIOGRAPHY.BDMin_summary| If born into the study, this is the last +date prior to birth that the mother was seen without the infant. |notnull| + + +.. _BIOGRAPHY.BDMax: + +BDMin (Maximum Birth Date) +`````````````````````````` + +.. |BIOGRAPHY.BDMax_summary| replace:: + The latest possible birthdate. + +|BIOGRAPHY.BDMax_summary| If born into the study, this is date of the +first sighting of the infant. |notnull| + + +.. _BIOGRAPHY.BDDist: + +BDDist (Birth Date Distribution) +```````````````````````````````` + +.. |BIOGRAPHY.BDDist_summary| replace:: + The probability distribution of the likelihood of birth between + |BIOGRAPHY.BDMin| and |BIOGRAPHY.BDMax|. Only one of 2 values are + allowed, ``sdb_bddist_normal`` when it is most likely that the + actual birthdate is closer to |BIOGRAPHY.BirthDate| than to + |BIOGRAPHY.BDMin| or |BIOGRAPHY.BDMax|, or ``sdb_bddist_uniform`` + when any birthdate between |BIOGRAPHY.BDMin| and |BIOGRAPHY.BDMax| + is equally likely. + +|BIOGRAPHY.BDDist_summary| |notnull| + + +.. _BIOGRAPHY.EntryDate: + +EntryDate +````````` + +.. |BIOGRAPHY.EntryDate_summary| replace:: + The date the individual entered the study; the date first seen. + +|BIOGRAPHY.EntryDate_summary| |notnull| + + +.. _BIOGRAPHY.EntryType: + +EntryType +````````` + +.. |BIOGRAPHY.EntryType_summary| replace:: + An |ENTRYTYPES|.\ |ENTRYTYPES.EntryType| code indicating how the + individual entered the study. + +|BIOGRAPHY.EntryType_summary| |notnull| + + +.. _BIOGRAPHY.DepartDate: + +DepartDate +`````````` + +.. |BIOGRAPHY.DepartDate_summary| replace:: + The date the individual was last in the study, or the date the + individual was last seen. For living individuals this is the date + of last census. + +|BIOGRAPHY.DepartDate_summary| |notnull| + + +.. _BIOGRAPHY.DepartType: + +DepartType +`````````` + +.. |BIOGRAPHY.DepartType_summary| replace:: + A |DEPARTTYPES|.\ |DEPARTTYPES.DepartType| code indicating that the + individual is still alive and under study, or how the individual + left the study. The |DEPARTTYPES|.\ |DEPARTTYPES.DepartType| + ``sdb_end_of_obs`` value is special. It indicates the individual + is still alive and in the community. + +|BIOGRAPHY.DepartType_summary| |notnull| diff --git a/doc/src/tables/comm_memb_log.m4 b/doc/src/tables/comm_memb_log.m4 new file mode 100644 index 0000000..8043daa --- /dev/null +++ b/doc/src/tables/comm_memb_log.m4 @@ -0,0 +1,105 @@ +.. Copyright (C) 2023 The Meme Factory, Inc. www.karlpinc.com + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + +.. M4 setup +include(constants.m4) +include(macros.m4) +sdb_rst_quotes(`on') +sdb_generated_rst() + +.. _COMM_MEMB_LOG: + +COMM_MEMB_LOG +------------- + +.. |COMM_MEMB_LOG_summary| replace:: + Each row is a log entry describing a change in an individual + chimpanzee's community membership. All community membership + changes since November of 2013 are recorded here. + +|COMM_MEMB_LOG_summary| + +This is meta-information which records history concerning the state of +the database. + + +.. _COMM_MEMB_LOG.CommMLID: + +CommMLID (Community Membership Log IDentifier) +`````````````````````````````````````````````` + +.. |COMM_MEMB_LOG.CommMLID_summary| replace:: + |idcol| + +|COMM_MEMB_LOG.CommMLID_summary| |notnull| + + +.. _COMM_MEMB_LOG.DateOfUpdate: + +DateOfUpdate +```````````` + +.. |COMM_MEMB_LOG.DateOfUpdate_summary| replace:: + The date the database was updated to reflect the change in + community membership. + +|COMM_MEMB_LOG.DateOfUpdate_summary| |notnull| + + +.. _COMM_MEMB_LOG.AnimID: + +AnimID (Animal IDentifier) +`````````````````````````` + +.. |COMM_MEMB_LOG.AnimID_summary| replace:: + The |BIOGRAPHY|.\ |BIOGRAPHY.AnimID| which identifies the + chimpanzee who's community membership was updated. + +|COMM_MEMB_LOG.AnimID_summary| |notnull| + + +.. _COMM_MEMB_LOG.Description: + +Description +``````````` + +.. |COMM_MEMB_LOG.Description_summary| replace:: + A description of the change made to community membership. + +|COMM_MEMB_LOG.Description_summary| |notnull| |emptytext| + + +.. _COMM_MEMB_LOG.Rationale: + +Rationale +````````` + +.. |COMM_MEMB_LOG.Rationale_summary| replace:: + The rationale for the change in community membership. + +|COMM_MEMB_LOG.Rationale_summary| |notonlyspaces| |notnull| + + +.. _COMM_MEMB_LOG.MadeBy: + +MadeBy +`````` + +.. |COMM_MEMB_LOG.MadeBy_summary| replace:: + The |PEOPLE|.\ |PEOPLE.Person| designating the researcher who + determined the community membership should be changed. + +|COMM_MEMB_LOG.MadeBy_summary| |notnull| + diff --git a/doc/src/tables/comm_membs.m4 b/doc/src/tables/comm_membs.m4 new file mode 100644 index 0000000..152e24e --- /dev/null +++ b/doc/src/tables/comm_membs.m4 @@ -0,0 +1,127 @@ +.. Copyright (C) 2023 The Meme Factory, Inc. www.karlpinc.com + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + +.. M4 setup +include(constants.m4) +include(macros.m4) +sdb_rst_quotes(`on') +sdb_generated_rst() + +.. _COMM_MEMBS: + +COMM_MEMBS +---------- + +.. |COMM_MEMBS_summary| replace:: + Each row represents an un-interrupted series of days during which + the given chimpanzee is a member of the given community. The unit + of time is the day; it is not possible to place any given + chimpanzee in more than one community within a single day. + +|COMM_MEMBS_summary| Leaving a community, whether to join another or +not, ends this period of community membership. Another row in +``COMM_MEMBS`` is required to record a newer period of community +membership, whether in the same or a different community. + +An individual may not be recorded in more than one community on any +given day, although there may be days during which the individual is +not placed in any community. + +An individual may not be placed in a community unless that individual +is under study; the |COMM_MEMBS.StartDate| may not be before the +individual's |BIOGRAPHY|.\ |BIOGRAPHY.EntryDate| and the +|COMM_MEMBS.EndDate| may not be after the individual's +|BIOGRAPHY|.\ |BIOGRAPHY.DepartDate|. + + +.. _COMM_MEMBS.CommMID: + +CommMID (Community Memberships IDentifier) +`````````````````````````````````````````` + +.. |COMM_MEMBS.CommMID_summary| replace:: + |idcol| + +|COMM_MEMBS.CommMID_summary| |notnull| + + +.. _COMM_MEMBS.AnimID: + +AnimID (Animal IDentifier) +`````````````````````````` + +.. |COMM_MEMBS.AnimID_summary| replace:: + The |BIOGRAPHY|.\ |BIOGRAPHY.AnimID| which identifies the + chimpanzee who's community membership is recorded. + +|COMM_MEMBS.AnimID_summary| |notnull| + + +.. _COMM_MEMBS.StartDate: + +StartDate +````````` + +.. |COMM_MEMBS.StartDate_summary| replace:: + The date on which the individual joined the community; the + start date, inclusive, of the interval of continuous membership. + +|COMM_MEMBS.StartDate_summary| |notnull| + + +.. _COMM_MEMBS.EndDate: + +EndDate +````````` + +.. |COMM_MEMBS.EndDate_summary| replace:: + The last date on which the individual was a community member; the + end date, inclusive, of the interval of continuous membership + +|COMM_MEMBS.EndDate_summary| |notnull| + + +.. _COMM_MEMBS.CommID: + +CommID (Community IDentifier) +````````````````````````````` + +.. |COMM_MEMBS.CommID_summary| replace:: + The |COMM_IDS|.\ |COMM_IDS.CommID| identifying the community in which + the row records membership. + +|COMM_MEMBS.CommID_summary| |notnull| + + +.. _COMM_MEMBS.StartSource: + +StartSource +``````````` + +.. |COMM_MEMBS.StartSource_summary| replace:: + Description of how the |COMM_MEMBS.StartDate| was determined. + +|COMM_MEMBS.StartSource_summary| |notonlyspaces| |notnull| + + +.. _COMM_MEMBS.EndSource: + +EndSource +````````` + +.. |COMM_MEMBS.EndSource_summary| replace:: + Description of how the |COMM_MEMBS.EndDate| was determined. + +|COMM_MEMBS.EndSource_summary| |notonlyspaces| |notnull| diff --git a/include/constants.m4 b/include/constants.m4 index d9aa4a0..cc6c14d 100644 --- a/include/constants.m4 +++ b/include/constants.m4 @@ -37,13 +37,42 @@ dnl dnl Special values -- hardcoded constants dnl +dnl +dnl BIOGRAPHY +dnl + +dnl The unknown chimp +define(`sdb_unk', `UNK') + +dnl BCCertainty +define(`sdb_bg_certain', `C') +define(`sdb_bg_uncertain', `U') + +dnl BDDist +define(`sdb_bddist_normal', `N') +define(`sdb_bddist_uniform', `U') + +dnl FirstBorn +define(`sdb_firstborn', `Y') +define(`sdb_not_firstborn', `N') +define(`sdb_unk_firstborn', `U') + dnl Sex define(`sdb_male', `M') define(`sdb_female', `F') -define(`sdb_unknown', `U') +define(`sdb_unk_sex', `U') -dnl Departtypes +dnl +dnl DEPART_TYPES +dnl +dnl Alive as of the last observation define(`sdb_end_of_obs', `O') +dnl +dnl COMM_IDS +dnl +dnl The unknown community +define(`sdb_unknown_comm', `Unknown') + divert(`0')dnl Output with m4 again ]}])dnl End of ifdef over the whole file. -- 2.34.1