From ddb3413bfd2fa1c54a482b121f993a924d430002 Mon Sep 17 00:00:00 2001 From: Javier Gonzalez Date: Thu, 6 Nov 2025 10:42:39 -0500 Subject: [PATCH 1/3] improve agasc-update-supplement arguments to enforce the possible choices of --status --- agasc/scripts/update_supplement.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/agasc/scripts/update_supplement.py b/agasc/scripts/update_supplement.py index 7b9ccff..20e5da9 100755 --- a/agasc/scripts/update_supplement.py +++ b/agasc/scripts/update_supplement.py @@ -212,7 +212,11 @@ def get_obs_status_parser(): ) status.add_argument("--obsid", help="OBSID for status override.", type=int) status.add_argument("--agasc-id", help="AGASC ID for status override.", type=int) - status.add_argument("--status", help="Status to override.") + status.add_argument( + "--status", + help="Status to override. If using integer codes, 0=ok/good, 1=bad.", + choices=["ok", "good", "bad", 0, 1] + ) status.add_argument("--comments", help="Comments for status override.", default="") status.add_argument( "--bad-star-id", From be0af5170eae6f9bfefe82f617e9f1184cf61a63 Mon Sep 17 00:00:00 2001 From: Javier Gonzalez Date: Thu, 6 Nov 2025 10:45:13 -0500 Subject: [PATCH 2/3] improve docs related to star-observation disposition: describe the required information, and correct the command-line command --- docs/supplement.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/supplement.rst b/docs/supplement.rst index 61bbfe0..5db6408 100644 --- a/docs/supplement.rst +++ b/docs/supplement.rst @@ -149,6 +149,18 @@ can be updated using the `agasc-update-supplement`_ script. This is normally done using a YAML file, but the script also accepts command-line arguments to specify the bad star and star observation information (more info below). +When updating the star-observation status, one has to provide the following information: + + - status: a numeric code indicating whether the observation is good or bad **(0=good, 1=bad)**. + When calling the script from the command line, one can also use the strings "ok", "good", + or "bad". + - obsid: the OBSID of the observation to which the status applies. + - mp_starcat_time: required when the OBSID is not enough to uniquely identify the observation. + - comments: a string with comments about the reason to set the status (optional). + This is usually set to an annotation from the rubric above. + - agasc_id: list of AGASC IDs to which the status applies. + This is optional. If not provided, all stars in the observation are used. + Calling the script with a YAML file can be done as follows:: agasc-update-supplement --obs-status-file status.yml @@ -193,7 +205,7 @@ Alternatively, the following call adds a single bad star:: The following adds a single star observation:: - agasc-update-supplement --obs 11849 --agasc-id 1019348536 --status False + agasc-update-supplement --obsid 11849 --agasc-id 1019348536 --status bad --comments "no telem" Updating via mica tools """"""""""""""""""""""" From 391f1d3c144ba87f16da76345aea1d5ea80d64f9 Mon Sep 17 00:00:00 2001 From: Javier Gonzalez Date: Fri, 7 Nov 2025 11:15:06 -0500 Subject: [PATCH 3/3] improve docs related to star-observation disposition: explain that agasc-supplement-tasks (the script used in standard processing) is not exactly the same as agasc-update-supplement. --- docs/supplement.rst | 64 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/docs/supplement.rst b/docs/supplement.rst index 5db6408..26ed030 100644 --- a/docs/supplement.rst +++ b/docs/supplement.rst @@ -138,16 +138,68 @@ Details ------- The following sections provide more detailed information on the underlying -tools used to manage the AGASC supplement. In most cases these will not be -run manually during production processing. +tools used to manage the AGASC supplement. In most cases these tools will not be +run manually during production processing, which uses the higher-level `agasc-supplement-tasks`_ +script to coordinate the various steps. Bad Star and Star Observation Updates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The tables of bad stars and of star observation status in the AGASC supplement -can be updated using the `agasc-update-supplement`_ script. This is normally -done using a YAML file, but the script also accepts command-line arguments to -specify the bad star and star observation information (more info below). +is normally done using `agasc-supplement-tasks`_ and an `obs_status.yml` YAML file. The +`agasc-supplement-tasks`_ script runs a few steps spelled out in the +`task_schedule_supplement_dispositions.cfg` file, which include: + + - update the supplement + - re-run the magnitude estimation for the affected stars + - re-generate the weekly reports + - generate a diff of the updated supplement against the previous version + +If we want to update the supplement manually, there are two alternatives: + + - `agasc-update-magnitudes`_ + - `agasc-update-supplement`_ + +agasc-update-magnitudes +"""""""""""""""""""""""" + +The `agasc-update-magnitudes`_ script re-runs the update of the supplement, the magnitude estimation +and report generation at once. This command is part of the task schedule run by +`agasc-supplement-tasks`_ when applying dispositions. It is generally better to use the +higher-level script, but in some cases it might be acceptable to run the following commands +directly:: + + agasc-update-magnitudes \ + --log-level debug \ + --report \ + --output-dir ${SKA}/data/agasc/rc \ + --obs-status-file ${SKA}/data/agasc/rc/obs_status.yml \ + --args-file ${SKA}/data/agasc/rc/supplement_reports/weekly/latest/call_args.yml + cp -fr ${SKA}/data/agasc/rc/supplement_reports/weekly/latest/stars/* \ + ${SKA}/data/agasc/rc/supplement_reports/stars + +Note these options are meant to re-run the magnitude estimation with the same arguments as the last +run. The last line copies the observation-specific HTML reports to the top location + +The downside of this approach is that the supplement diff is not generated, and a report of +"suspect" stars is not re-generated. + +The `agasc-update-magnitudes`_ script has command-line options to update the supplement without +providing an obs-status file. The options are the same as those for `agasc-update-supplement`_ +(see below). + +agasc-update-supplement +""""""""""""""""""""""""" + +An easier alternative is the `agasc-update-supplement`_ script. This script can be run manually +and provides more flexibility in specifying the bad star and star observation information +(more info below). However, **this script only updates the supplement file and does not +re-run the magnitude estimation or re-generate the reports**. Sometimes this is acceptable. + +In what follows, we assume the script is called from the same directory where the +supplement file to be updated resides. By default, the script looks for a file +named ``agasc_supplement.h5`` in the current working directory, but this can be +changed via a command-line argument. When updating the star-observation status, one has to provide the following information: @@ -165,7 +217,7 @@ Calling the script with a YAML file can be done as follows:: agasc-update-supplement --obs-status-file status.yml -An example `status.yml` file is: +An example ``status.yml`` file is: .. code-block:: yaml