docs: move is_surveillance to general metadata, clarify conditional columns

Author: Tanisha127

malariagen_data/anoph/sample_metadata.py

@@ -732,8 +732,10 @@ def clear_extra_metadata(self):
             - ``terms_of_use_expiry_date`` - Expiry date of terms of use for the sample.
             - ``terms_of_use_url`` - URL of the terms of use for the sample.
             - ``unrestricted_use`` - Whether the sample can be used without restrictions.
+            - ``is_surveillance`` - Whether the sample can be used for surveillance.
 
-            **Sequence QC metadata**:
+            **Sequence QC metadata** (present for all sample sets, values may
+            be missing if QC data is unavailable for a given sample set):
 
             - ``mean_cov`` - Mean sequencing coverage across the genome.
             - ``median_cov`` - Median sequencing coverage across the genome.
@@ -747,7 +749,7 @@ def clear_extra_metadata(self):
             - ``mean_cov_3L`` - Mean coverage on chromosome arm 3L.
             - ``median_cov_3L`` - Median coverage on chromosome arm 3L.
             - ``mode_cov_3L`` - Modal coverage on chromosome arm 3L.
-            - ``mean_cov_3R`` - Mean coverage on chromosome arm 3R.=
+            - ``mean_cov_3R`` - Mean coverage on chromosome arm 3R.
             - ``median_cov_3R`` - Median coverage on chromosome arm 3R.
             - ``mode_cov_3R`` - Modal coverage on chromosome arm 3R.
             - ``mean_cov_X`` - Mean coverage on chromosome X.
@@ -758,25 +760,24 @@ def clear_extra_metadata(self):
             - ``contam_pct`` - Estimated contamination percentage.
             - ``contam_LLR`` - Log-likelihood ratio for contamination estimate.
 
-            **Surveillance flags**:
-
-            - ``is_surveillance`` - Whether the sample can be used for surveillance.
-
-            **AIM (Ancestry-Informative Marker) metadata** (if available):
+            **AIM (Ancestry-Informative Marker) metadata** (only present when
+            an AIM analysis is available for the data resource, e.g., *Ag3*):
 
-            - ``aim_species_fraction_arab`` - Fraction of gambcolu vs. arabiensis AIMs
-              indicating arabiensis.
+            - ``aim_species_fraction_arab`` - Fraction of gambcolu vs. arabiensis
+              AIMs indicating arabiensis.
             - ``aim_species_fraction_colu`` - Fraction of gambiae vs. coluzzii AIMs
               indicating coluzzii.
-            - ``aim_species_fraction_colu_no2l`` - Fraction of gambiae vs. coluzzii AIMs
-              indicating coluzzii, excluding chromosome arm 2L.
+            - ``aim_species_fraction_colu_no2l`` - Fraction of gambiae vs. coluzzii
+              AIMs indicating coluzzii, excluding chromosome arm 2L.
             - ``aim_species_gambcolu_arabiensis`` - Taxon assigned by gambcolu vs.
               arabiensis AIMs.
             - ``aim_species_gambiae_coluzzii`` - Taxon assigned by gambiae vs.
               coluzzii AIMs.
             - ``aim_species`` - Final species assignment combining both AIM analyses.
 
-            **Cohort metadata** (if available):
+            **Cohort metadata** (only present when a cohorts analysis is available
+            for the data resource; quarter columns are only present for cohorts
+            analyses from 20230223 onwards):
 
             - ``country_iso`` - ISO code of the country of collection.
             - ``admin1_name`` - Name of the first-level administrative region.
@@ -785,14 +786,16 @@ def clear_extra_metadata(self):
             - ``taxon`` - Taxon assigned by combining AIM and cohort analyses.
             - ``cohort_admin1_year`` - Cohort grouping by admin level 1 and year.
             - ``cohort_admin1_month`` - Cohort grouping by admin level 1 and month.
-            - ``cohort_admin1_quarter`` - Cohort grouping by admin level 1 and quarter.
+            - ``cohort_admin1_quarter`` - Cohort grouping by admin level 1 and
+              quarter (cohorts analysis >= 20230223 only).
             - ``cohort_admin2_year`` - Cohort grouping by admin level 2 and year.
             - ``cohort_admin2_month`` - Cohort grouping by admin level 2 and month.
-            - ``cohort_admin2_quarter`` - Cohort grouping by admin level 2 and quarter.
+            - ``cohort_admin2_quarter`` - Cohort grouping by admin level 2 and
+              quarter (cohorts analysis >= 20230223 only).
 
-            The exact columns present depend on the sample sets requested and
-            which analyses are available. The returned DataFrame is a copy and
-            can be safely modified without affecting internal caches.
+            The exact columns present depend on the data resource and sample sets
+            requested. The returned DataFrame is a copy and can be safely modified
+            without affecting internal caches.
         """,
     )
     def sample_metadata(