From a9220ebe15704c4cc72426e581c17272416ab6f4 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Wed, 17 Jun 2026 19:28:34 +0000 Subject: [PATCH] Document redundant CommID columns, add warnings against canonical values --- doc/src/tables/aggressions.m4 | 14 ++++++++++++- doc/src/tables/locations_gps.m4 | 37 ++++++++++++++++++++++++++++++++- doc/src/tables/locations_map.m4 | 36 +++++++++++++++++++++++++++++++- doc/src/tables/pantgrunts.m4 | 33 +++++++++++++++++++++++++++++ 4 files changed, 117 insertions(+), 3 deletions(-) diff --git a/doc/src/tables/aggressions.m4 b/doc/src/tables/aggressions.m4 index aee953f..85ae7bd 100644 --- a/doc/src/tables/aggressions.m4 +++ b/doc/src/tables/aggressions.m4 @@ -308,7 +308,19 @@ The |COMM_IDS|.\ |COMM_IDS.CommID| of the of the focal. observation when the data was collected `. It may, in fact, differ from the community recorded elsewhere. -|notnull| + This row exists because of the way the community was recorded in + the old MS Access database. + There, the community was recorded twice, once in the follow and + again with the record of aggression. + + This column exists so no information was lost in the conversion of + the MS Access data to SokweDB. + At some point in the future, perhaps when all inconsistencies + between the value of this column and the community information + recorded elsewhere are resolved, this column may be removed from + this table. + + |notnull| .. _AGGRESSIONS.Extractedby: diff --git a/doc/src/tables/locations_gps.m4 b/doc/src/tables/locations_gps.m4 index 355b915..814e42f 100644 --- a/doc/src/tables/locations_gps.m4 +++ b/doc/src/tables/locations_gps.m4 @@ -30,6 +30,14 @@ LOCATIONS_GPS (spatial LOCATIONS in UTM coordinates) |LOCATIONS_GPS_summary| +The system will generate a warning if the community of the follow +related to the location information, or that of the |WATCHES| row that +exists to support the location record, is not the comm unity +associated with the location record. +This means, if the LOCATIONS_GPS.\ |LOCATIONS_GPS.CommID| is not the +|WATCHES|.\ |WATCHES.CommID| of the related |WATCHES| row. + + .. contents:: :depth: 2 @@ -104,7 +112,34 @@ CommID This is not necessarily the community the individual is a member of, although it usually is. -|LOCATIONS_GPS.CommID_summary| |notnull| +|LOCATIONS_GPS.CommID_summary| + +.. note:: + This is not the canonical source of information on the focal's + community at the time of observation or :ref:`the community under + observation when the data was collected `. + It may, in fact, differ from the community recorded elsewhere. + + This row exists because of the way the community was recorded in + the old MS Access database. + There, the community was recorded twice, once in the follow and + again with the record of location. + + When there is no related follow, there is still a related |WATCHES| + row that exists solely to provide information concerning location + data. + In this case the community information in the |WATCHES| row was + initially the same as the value of this column. + But the data could change and become out of sync. + + This column exists so no information was lost in the conversion of + the MS Access data to SokweDB. + At some point in the future, perhaps when all inconsistencies + between the value of this column and the community information + recorded elsewhere are resolved, this column may be removed from + this table. + +|notnull| .. _LOCATIONS_GPS.FollowNum: diff --git a/doc/src/tables/locations_map.m4 b/doc/src/tables/locations_map.m4 index 50278d0..4c197d1 100644 --- a/doc/src/tables/locations_map.m4 +++ b/doc/src/tables/locations_map.m4 @@ -30,6 +30,13 @@ LOCATIONS_MAP (spatial LOCATIONS in map numbers) |LOCATIONS_MAP_summary| +The system will generate a warning if the community of the follow +related to the location information, or that of the |WATCHES| row that +exists to support the location record, is not the community associated +with the location record. +This means, if the LOCATIONS_MAP.\ |LOCATIONS_MAP.CommID| is not the +|WATCHES|.\ |WATCHES.CommID| of the related |WATCHES| row. + .. contents:: :depth: 2 @@ -93,7 +100,34 @@ CommID This is not necessarily the community the individual is a member of, although it usually is. -|LOCATIONS_MAP.CommID_summary| |notnull| +|LOCATIONS_MAP.CommID_summary| + +.. note:: + This is not the canonical source of information on the focal's + community at the time of observation or :ref:`the community under + observation when the data was collected `. + It may, in fact, differ from the community recorded elsewhere. + + This row exists because of the way the community was recorded in + the old MS Access database. + There, the community was recorded twice, once in the follow and + again with the record of location. + + When there is no related follow, there is still a related |WATCHES| + row that exists solely to provide information concerning location + data. + In this case the community information in the |WATCHES| row was + initially the same as the value of this column. + But the data could change and become out of sync. + + This column exists so no information was lost in the conversion of + the MS Access data to SokweDB. + At some point in the future, perhaps when all inconsistencies + between the value of this column and the community information + recorded elsewhere are resolved, this column may be removed from + this table. + +|notnull| .. _LOCATIONS_MAP.FollowNum: diff --git a/doc/src/tables/pantgrunts.m4 b/doc/src/tables/pantgrunts.m4 index 5e910a0..a9c9934 100644 --- a/doc/src/tables/pantgrunts.m4 +++ b/doc/src/tables/pantgrunts.m4 @@ -51,6 +51,13 @@ This related |EVENTS| row supplies the time of the pantgrunt and relates to the follow, and the |ROLES| role related to the event supplies information on the individuals involved. +The system will generate a warning if the community of the follow +related to the pantgrunt information, or that of the |WATCHES| row +that exists to support the pantgrunt record, is not the community +associated with the pantgrunt record. +This means, if the PANTGRUNTS.\ |PANTGRUNTS.CommID| is not the +|WATCHES|.\ |WATCHES.CommID| of the related |WATCHES| row. + For further information, including additional data integrity rules, see the documentation of the :ref:`EVENTS ` table. @@ -115,6 +122,32 @@ CommID This is not necessarily the community the focal is a member of. |PANTGRUNTS.CommID_summary| + +.. note:: + This is not the canonical source of information on the focal's + community at the time of observation or :ref:`the community under + observation when the data was collected `. + It may, in fact, differ from the community recorded elsewhere. + + This row exists because of the way the community was recorded in + the old MS Access database. + There, the community was recorded twice, once in the follow and + again with the pantgrunt information. + + When there is no related follow, there is still a related |WATCHES| + row that exists solely to provide information concerning pantgrunt + data. + In this case the community information in the |WATCHES| row was + initially the same as the value of this column. + But the data could change and become out of sync. + + This column exists so no information was lost in the conversion of + the MS Access data to SokweDB. + At some point in the future, perhaps when all inconsistencies + between the value of this column and the community information + recorded elsewhere are resolved, this column may be removed from + this table. + |notnull| -- 2.34.1