From 9a632d228f3eabdeae8cff27ad659c3434e2150c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Tue, 10 Feb 2026 22:20:07 +0000 Subject: [PATCH] Initial design of SIGHTINGS Includes the tables: SIGHTINGS, NON_BREC_SIGHTING_SOURCES, SIGHTING_RECORDS --- doc/src/code_tables.m4 | 67 +++++++++ doc/src/epilog.inc.m4 | 33 +++++ doc/src/tables.m4 | 2 + doc/src/tables/non_brec_sighting_sources.m4 | 111 +++++++++++++++ doc/src/tables/sightings.m4 | 145 ++++++++++++++++++++ include/global_constants.m4 | 6 + 6 files changed, 364 insertions(+) create mode 100644 doc/src/tables/non_brec_sighting_sources.m4 create mode 100644 doc/src/tables/sightings.m4 diff --git a/doc/src/code_tables.m4 b/doc/src/code_tables.m4 index 2eca5ac..a74bbce 100644 --- a/doc/src/code_tables.m4 +++ b/doc/src/code_tables.m4 @@ -690,6 +690,73 @@ Description |ROLE_CODES.Description_summary| |emptytext| |notnull| +.. _SIGHTING_RECORDS: + +SIGHTING_RECORDS +---------------- + +.. |SIGHTING_RECORDS_summary| replace:: + Contains one row for each non-BRec data source affecting the + per-day, per-chimpanzee sightings found in the |SIGHTINGS| table. + +|SIGHTING_RECORDS_summary| + +The SIGHTING_RECORDS.\ |SIGHTING_RECORDS.Priority| value must be unique. + +Special Values +`````````````` + +The |SIGHTING_RECORDS.Code| value of ``sdb_sokwedb_source`` is special. +It indicates that the sighting is due to data held in SokweDB, aside +from the |NON_BREC_SIGHTING_SOURCES| table. + + +Column Descriptions +``````````````````` + +.. _SIGHTING_RECORDS.Code: + +Code +'''' + +.. |SIGHTING_RECORDS.Code_summary| replace:: + A code identifying a type of record-keeping which is used as a + source in the tracking of chimpanzee sightings. + +|SIGHTING_RECORDS.Code_summary| +|caseuniquekeycol| |uppercase| + + +.. _SIGHTING_RECORDS.Priority: + +Priority +'''''''' + +.. |SIGHTING_RECORDS.Priority_summary| replace:: + An integer determining which code is to be recorded in the + |SIGHTINGS|.\ |SIGHTINGS.Source| column when there are multiple + non-BRec sources. + +|SIGHTING_RECORDS.Priority_summary| +The |SIGHTING_RECORDS.Code| with the lowest numbered Priority value is +recorded in |SIGHTINGS|.\ |SIGHTINGS.Source|, when there are multiple +sources recorded for a given individual on a given day in +|NON_BREC_SIGHTING_SOURCES|. + +|nonnegative| |notnull| + + +.. _SIGHTING_RECORDS.Description: + +Description +''''''''''' + +.. |SIGHTING_RECORDS.Description_summary| replace:: + A description of the code. + +|SIGHTING_RECORDS.Description_summary| |emptytext| |notnull| + + .. _SPECIES: SPECIES diff --git a/doc/src/epilog.inc.m4 b/doc/src/epilog.inc.m4 index b30634d..2fddb22 100644 --- a/doc/src/epilog.inc.m4 +++ b/doc/src/epilog.inc.m4 @@ -300,6 +300,39 @@ sdb_generated_rst()dnl .. |ROLE_CODES.Role| replace:: :ref:`Role ` +.. |SIGHTING_RECORDS| replace:: :ref:`SIGHTING_RECORDS ` +.. |SIGHTING_RECORDS.Code| replace:: + :ref:`Code ` +.. |SIGHTING_RECORDS.Priority| replace:: + :ref:`Priority ` + +.. |NON_BREC_SIGHTING_SOURCES| replace:: + :ref:`NON_BREC_SIGHTING_SOURCES ` +.. |NON_BREC_SIGHTING_SOURCES.ID| replace:: + :ref:`ID ` +.. |NON_BREC_SIGHTING_SOURCES.Source| replace:: + :ref:`Source ` +.. |NON_BREC_SIGHTING_SOURCES.Date| replace:: + :ref:`Date ` +.. |NON_BREC_SIGHTING_SOURCES.AnimID| replace:: + :ref:`AnimID ` +.. |NON_BREC_SIGHTING_SOURCES.CommID| replace:: + :ref:`CommID ` +.. |NON_BREC_SIGHTING_SOURCES.Notes| replace:: + :ref:`Notes ` + +.. |SIGHTINGS| replace:: :ref:`SIGHTINGS ` +.. |SIGHTINGS.SightID| replace:: + :ref:`SightID ` +.. |SIGHTINGS.Date| replace:: + :ref:`SightDate ` +.. |SIGHTINGS.AnimID| replace:: + :ref:`AnimID ` +.. |SIGHTINGS.CommID| replace:: + :ref:`CommID ` +.. |SIGHTINGS.Source| replace:: + :ref:`Source ` + .. |SPECIES| replace:: :ref:`SPECIES ` .. |SPECIES.Species| replace:: :ref:`Species ` diff --git a/doc/src/tables.m4 b/doc/src/tables.m4 index 9ad8c65..71523cf 100644 --- a/doc/src/tables.m4 +++ b/doc/src/tables.m4 @@ -39,4 +39,6 @@ Data Tables tables/follow_studies.rst tables/humans.rst tables/roles.rst + tables/non_brec_sighting_sources.rst + tables/sightings.rst tables/species_present.rst diff --git a/doc/src/tables/non_brec_sighting_sources.m4 b/doc/src/tables/non_brec_sighting_sources.m4 new file mode 100644 index 0000000..6bfb6e8 --- /dev/null +++ b/doc/src/tables/non_brec_sighting_sources.m4 @@ -0,0 +1,111 @@ +.. Copyright (C) 2026 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)dnl +include(macros.m4)dnl +sdb_rst_quotes(`on')dnl +sdb_generated_rst()dnl + +.. _NON_BREC_SIGHTING_SOURCES: + +NON_BREC_SIGHTING_SOURCES +------------------------- + +.. |NON_BREC_SIGHTING_SOURCES_summary| replace:: + There is a row for each chimpanzee, for each date sighted, for + non-BRec related sightings. + This table is used to make "manual", that is, non-BRec + related, changes to the per-day record of chimpanzee sightings + found in the |SIGHTINGS| table. + +|NON_BREC_SIGHTING_SOURCES_summary| + +.. contents:: + :depth: 2 + + +.. _NON_BREC_SIGHTING_SOURCES.ID: + +ID (IDentifier) +``````````````` + +.. |NON_BREC_SIGHTING_SOURCES.ID_summary| replace:: + |idcol| + +|NON_BREC_SIGHTING_SOURCES.ID_summary| |notnull| + + +.. _NON_BREC_SIGHTING_SOURCES.Source: + +Source +`````` + +.. |NON_BREC_SIGHTING_SOURCES.Source_summary| replace:: + Code indicating the Non-BRec record in which the sighting was + recorded. + A |SIGHTING_RECORDS|.\ |SIGHTING_RECORDS.Code| value. + +|NON_BREC_SIGHTING_SOURCES.Source_summary| +The special value ``sdb_sowkedb_source`` may not appear as a value in +this column. + +|notnull| + + +.. _NON_BREC_SIGHTING_SOURCES.Date: + +Date +```` + +.. |NON_BREC_SIGHTING_SOURCES.Date_summary| replace:: + The date the individual was sighted. + +|NON_BREC_SIGHTING_SOURCES.Date_summary| |notnull| + + +.. _NON_BREC_SIGHTING_SOURCES.AnimID: + +AnimID (Animal IDentifier) +`````````````````````````` + +.. |NON_BREC_SIGHTING_SOURCES.AnimID_summary| replace:: + The |BIOGRAPHY_DATA|.\ |BIOGRAPHY_DATA.AnimID| of the individual + sighted. + +|NON_BREC_SIGHTING_SOURCES.AnimID_summary| |notnull| + + +.. _NON_BREC_SIGHTING_SOURCES.CommID: + +CommID (Community IDentifier) +````````````````````````````` + +.. |NON_BREC_SIGHTING_SOURCES.CommID_summary| replace:: + The |COMM_IDS|.\ |COMM_IDS.CommID| of the community to which the + individual was assigned for the day. + +|NON_BREC_SIGHTING_SOURCES.CommID_summary| |notnull| + + +.. _NON_BREC_SIGHTING_SOURCES.Notes: + +Notes +````` + +.. |NON_BREC_SIGHTING_SOURCES.Notes_summary| replace:: + Textual notes related to the sighting. + +|NON_BREC_SIGHTING_SOURCES.Notes_summary| |notnull| diff --git a/doc/src/tables/sightings.m4 b/doc/src/tables/sightings.m4 new file mode 100644 index 0000000..2b9a955 --- /dev/null +++ b/doc/src/tables/sightings.m4 @@ -0,0 +1,145 @@ +.. Copyright (C) 2026 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)dnl +include(macros.m4)dnl +sdb_rst_quotes(`on')dnl +sdb_generated_rst()dnl + +.. _SIGHTINGS: + +SIGHTINGS +--------- + +.. |SIGHTINGS_summary| replace:: + + SIGHTINGS contains one row for each chimpanzee for every day the + individual was observed. + It records the community to which the individual was assigned on + each day, as well as daily sexual swelling information. + SIGHTINGS is typically used to assist with censoring + calculations. + +|SIGHTINGS_summary| + +The SIGHTINGS table is automatically constructed by the system and +cannot be manually maintained. +The table's rows are computed from the SokweDB tables' content. + +The |NON_BREC_SIGHTING_SOURCES| table is used to add additional +"manual" sighting records to SIGHTINGS, when the other parts of +SokweDB do not indicate that an individual was sighted on a particular +day. +There is no way to remove rows from SIGHTINGS when tables, other than +the |NON_BREC_SIGHTING_SOURCES| table, indicate that an individual was +sighted. +But if the only reason a row appears in SIGHTINGS is due to rows in +|NON_BREC_SIGHTING_SOURCES|, the row can be removed from SIGHTINGS by +removing the |NON_BREC_SIGHTING_SOURCES| rows. + +Rows may exist in |NON_BREC_SIGHTING_SOURCES| to record additional +sightings of an individual on a given day when other tables in SokweDB +also imply a sighting of the individual. +In this case, the rows in |NON_BREC_SIGHTING_SOURCES| have no effect. +However, should the SokweDB db's content change in a way that +indicates the individual was not sighted, the relevant rows in +|NON_BREC_SIGHTING_SOURCES| will then cause the SIGHTINGS row to be +retained -- recording the individual as "sighted". + +.. _sightings_source_determination: + +When a row exists in SIGHTINGS only because of rows in +|NON_BREC_SIGHTING_SOURCES|, the |SIGHTING_RECORDS|.\ +|SIGHTING_RECORDS.Priority| column is determines the value of the +|SIGHTINGS.Source| column. +Whenever tables other than |NON_BREC_SIGHTING_SOURCES| indicate the +sighting of an individual, the |SIGHTINGS.Source| column contains the +special value ``sdb_sokwedb_source``. +In other words, |NON_BREC_SIGHTING_SOURCES| only determines the +|SIGHTINGS.Source| value when no other tables in the database indicate +a sighting occurred. + +The |SIGHTINGS.Date| must be during a period when the sighted individual +was under study, on or after the individual's |BIOGRAPHY_DATA|.\ +|BIOGRAPHY_DATA.EntryDate| and on or before the individual's +|BIOGRAPHY_DATA|.\ |BIOGRAPHY_DATA.DepartDate|. + + +.. contents:: + :depth: 2 + + +.. _SIGHTINGS.SightID: + +SightID (SIGHTings IDentifier) +`````````````````````````````` + +.. |SIGHTINGS.SightID_summary| replace:: + |idcol| + +|SIGHTINGS.SightID_summary| |notnull| + + +.. _SIGHTINGS.Date: + +Date +```` + +.. |SIGHTINGS.Date_summary| replace:: + The date the individual was sighted. + +|SIGHTINGS.Date_summary| |notnull| + + +.. _SIGHTINGS.AnimID: + +AnimID (Animal IDentifier) +`````````````````````````` + +.. |SIGHTINGS.AnimID_summary| replace:: + The |BIOGRAPHY_DATA|.\ |BIOGRAPHY_DATA.AnimID| of the individual + sighted. + +|SIGHTINGS.AnimID_summary| |notnull| + + +.. _SIGHTINGS.CommID: + +CommID (Community IDentifier) +````````````````````````````` + +.. |SIGHTINGS.CommID_summary| replace:: + The |COMM_IDS|.\ |COMM_IDS.CommID| of the community to which the + individual was assigned for the day. + +|SIGHTINGS.CommID_summary| |notnull| + + +.. _SIGHTINGS.Source: + +Source +`````` + +.. |SIGHTINGS.Source_summary| replace:: + A code indicating the record-taking that is the source of the + sighting information. + A |SIGHTING_RECORDS|.\ |SIGHTING_RECORDS.Code| value. + +|SIGHTINGS.Source_summary| +See :ref:`above ` for more information +on how the value of this column is determined. + +|notnull| diff --git a/include/global_constants.m4 b/include/global_constants.m4 index 7faab72..ea0312e 100644 --- a/include/global_constants.m4 +++ b/include/global_constants.m4 @@ -126,6 +126,12 @@ dnl The NestStart and NestEnd values define(`sdb_in_nest', `1') define(`sdb_out_of_nest', `0') +dnl +dnl SIGHTING_RECORDS +dnl +dnl Value used when the SokweDB tables indicate a sighting +define(`sdb_sokwedb_source', `SOKWEDB') + dnl dnl Special sexual cycle values dnl -- 2.34.1