From 503cc73d725d6e5bb9372241d79dac2abcb4eda9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Sat, 28 Feb 2026 22:52:41 +0000 Subject: [PATCH] Initial ESTRUS_STATES design --- doc/src/analyzed.m4 | 1 + doc/src/analyzed/estrus_states.m4 | 200 ++++++++++++++++++++++++++++++ doc/src/analyzed/sightings.m4 | 6 +- doc/src/epilog.inc.m4 | 16 +++ 4 files changed, 220 insertions(+), 3 deletions(-) create mode 100644 doc/src/analyzed/estrus_states.m4 diff --git a/doc/src/analyzed.m4 b/doc/src/analyzed.m4 index b3dcb04..e455784 100644 --- a/doc/src/analyzed.m4 +++ b/doc/src/analyzed.m4 @@ -31,4 +31,5 @@ a rudimentary analytical process. .. toctree:: :maxdepth: 3 + analyzed/estrus_states.rst analyzed/sightings.rst diff --git a/doc/src/analyzed/estrus_states.m4 b/doc/src/analyzed/estrus_states.m4 new file mode 100644 index 0000000..5d5c0a9 --- /dev/null +++ b/doc/src/analyzed/estrus_states.m4 @@ -0,0 +1,200 @@ +.. 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 + +.. _ESTRUS_STATES: + +ESTRUS_STATES +------------- + +.. |ESTRUS_STATES_summary| replace:: + + ESTRUS_STATES contains one row for each female chimpanzee + for every day the individual's estrus state was observed. + It records daily minimum and maximum sexual swelling information. + +|ESTRUS_STATES_summary| +This table provides an automatically maintained summary of the estrus +state information found throughout SokweDB. + +The ESTRUS_STATES table is automatically constructed by the system and +cannot be manually maintained. +The table's rows are computed from the SokweDB tables' content. + +The |ESTRUS_SOURCES| table is used to both force specific estrus state +values and to add additional records of estrus state, records from +"external" data sources, into ESTRUS_STATES' minimum and maxium estrus +calculations. +There is no way to remove rows from ESTRUS_STATES when SokweDB tables, +other than the |ESTRUS_SOURCES| table, contain estrus state +information on an individual on a particular day. +But if the only reason a row appears in ESTRUS_STATES is due to rows in +|ESTRUS_SOURCES|, the row can be removed from ESTRUS_STATES by +removing the |ESTRUS_SOURCES| rows. + +Rows may exist in |ESTRUS_SOURCES| to record additional estrus state +information on an individual on a given day regardless of whether +other tables in SokweDB also contain estrus information. +Should the SokweDB db's content change in a way that removes the +individual's daily estrus information, the relevant rows in +|ESTRUS_SOURCES| become the sole source of the individual's daily +estrus information. + +.. _estrus_state_determination: + +The ESTRUS_STATES.\ |ESTRUS_STATES.EstrusMin| value is the minimum of +all the minimum estrus swelling states recorded in SokweDB for the +individual for a given day. +Notably, this includes minimum estrus values present in +|ESTRUS_SOURCES|, which provides a way to include arbitrary estrus +state information. + +The ESTRUS_STATES.\ |ESTRUS_STATES.EstrusMax| value is the maximum of +all the maximum estrus swelling states recorded in SokweDB for the +individual for a given day, computed in a fashion analogous to the +|ESTRUS_STATES.EstrusMin| computation. + +Minimums and maximums are computed by comparing |CYCLE_STATES|.\ +|CYCLE_STATES.AsNum| values. +|CYCLE_STATES|.\ |CYCLE_STATES.Code| values associated with |null| +|CYCLE_STATES.AsNum| values are not used in minimum or maximum +calculations. +This means that only those |CYCLE_STATES|.\ |CYCLE_STATES.Code| values +associated with non-|null| |CYCLE_STATES.AsNum| values appear as +|ESTRUS_STATES.EstrusMin| or |ESTRUS_STATES.EstrusMax| values. + +There is a mechanism for ignoring the above minimum and maximum +calculations and manually specifying a daily estrus state value. +To do this, create a row in |ESTRUS_SOURCES| with the special +|ESTRUS_SOURCES.Source| value of ``sdb_manual_estrus``. +The |ESTRUS_SOURCES.EstrusMin| and ESTRUS_SOURCES.EstrusMax| values in +the row you create then become the values used in the ESTRUS_STATES.\ +|ESTRUS_STATES.EstrusMin| and |ESTRUS_STATES.EstrusMax| columns for +the given individual for the given day. + +To allow the manual adjustment of |ESTRUS_STATES.EstrusMin| values +without also being forced to supply manual value for +|ESTRUS_STATES.EstrusMax|, |null| |ESTRUS_SOURCES|.\ +|ESTRUS_SOURCES.EstrusMin| and |ESTRUS_SOURCES|.\ +|ESTRUS_SOURCES.EstrusMax| values are ignored. + + +.. contents:: + :depth: 2 + + +.. _ESTRUS_STATES.ID: + +ID (Estrus_States IDentifier) +````````````````````````````` + +.. |ESTRUS_STATES.ID_summary| replace:: + |idcol| + +|ESTRUS_STATES.ID_summary| |notnull| + + +.. _ESTRUS_STATES.Date: + +Date +```` + +.. |ESTRUS_STATES.Date_summary| replace:: + The date of the individual's estrus state. + +|ESTRUS_STATES.Date_summary| |notnull| + + +.. _ESTRUS_STATES.AnimID: + +AnimID (Animal IDentifier) +`````````````````````````` + +.. |ESTRUS_STATES.AnimID_summary| replace:: + The |BIOGRAPHY_DATA|.\ |BIOGRAPHY_DATA.AnimID| of the individual + who's estrus state was observed. + +|ESTRUS_STATES.AnimID_summary| |notnull| + + +.. _ESTRUS_STATES.EstrusMin: + +EstrusMin (Estrus Minimum swelling) +``````````````````````````````````` + +.. |ESTRUS_STATES.EstrusMin_summary| replace:: + The minimum estrus swelling observed on the day. + A |CYCLE_STATES|.\ |CYCLE_STATES.Code| value. + +|ESTRUS_STATES.EstrusMin_summary| +See :ref:`above ` for more information +on how the value of this column is determined. + +|notnull| + + +.. _ESTRUS_STATES.EstrusMinSource: + +EstrusMinSource +``````````````` + +.. |ESTRUS_STATES.EstrusMinSource_summary| replace:: + A code indicating the record-taking that is the source of the + minimum estrus swelling information. + A |SIGHTING_RECORDS|.\ |SIGHTING_RECORDS.Code| value. + +|ESTRUS_STATES.EstrusMinSource_summary| +See :ref:`above ` for more information +on how the value of this column is determined. + +|notnull| + + +.. _ESTRUS_STATES.EstrusMax: + +EstrusMax (Estrus Maximum swelling) +``````````````````````````````````` + +.. |ESTRUS_STATES.EstrusMax_summary| replace:: + The maximum estrus swelling observed on the day. + A |CYCLE_STATES|.\ |CYCLE_STATES.Code| value. + +|ESTRUS_STATES.EstrusMax_summary| +See :ref:`above ` for more information +on how the value of this column is determined. + +|notnull| + + +.. _ESTRUS_STATES.EstrusMaxSource: + +EstrusMaxSource +``````````````` + +.. |ESTRUS_STATES.EstrusMaxSource_summary| replace:: + A code indicating the record-taking that is the source of the + maximum estrus swelling information. + A |SIGHTING_RECORDS|.\ |SIGHTING_RECORDS.Code| value. + +|ESTRUS_STATES.EstrusMaxSource_summary| +See :ref:`above ` for more information +on how the value of this column is determined. + +|notnull| diff --git a/doc/src/analyzed/sightings.m4 b/doc/src/analyzed/sightings.m4 index 48623c6..73929df 100644 --- a/doc/src/analyzed/sightings.m4 +++ b/doc/src/analyzed/sightings.m4 @@ -40,9 +40,9 @@ 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. +records of daily sightings into SIGHTINGS, records from "external" +data sources, 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 SokweDB tables, other than the |NON_BREC_SIGHTING_SOURCES| table, indicate that an individual was sighted. diff --git a/doc/src/epilog.inc.m4 b/doc/src/epilog.inc.m4 index e6f2502..2cd7769 100644 --- a/doc/src/epilog.inc.m4 +++ b/doc/src/epilog.inc.m4 @@ -234,6 +234,22 @@ sdb_generated_rst()dnl .. |ESTRUS_SOURCES.Notes| replace:: :ref:`Notes ` +.. |ESTRUS_STATES| replace:: :ref:`ESTRUS_STATES ` +.. |ESTRUS_STATES.ID| replace:: + :ref:`ID ` +.. |ESTRUS_STATES.Date| replace:: + :ref:`Date ` +.. |ESTRUS_STATES.AnimID| replace:: + :ref:`AnimID ` +.. |ESTRUS_STATES.EstrusMin| replace:: + :ref:`EstrusMin ` +.. |ESTRUS_STATES.EstrusMinSource| replace:: + :ref:`EstrusMinSource ` +.. |ESTRUS_STATES.EstrusMax| replace:: + :ref:`EstrusMax ` +.. |ESTRUS_STATES.EstrusMaxSource| replace:: + :ref:`EstrusMaxSource ` + .. |EVENTS| replace:: :ref:`EVENTS ` .. |EVENTS.EID| replace:: :ref:`EID ` -- 2.34.1