.. lsst-task-topic:: lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask

######################
FgcmCalibrateTractTask
######################

``FgcmCalibrateTractTask`` will run the full ``fgcmcal`` processing cycle on a single tract with multi-band coverage.
Note that the results will not be as robust as a full global calibration because of the limited ability to tract instrumental changes from observations in a single tract.
Running ``FgcmCalibrateTractTask`` requires a look-up table generated by :doc:`lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutTask`.

``FgcmCalibrateTractTask`` uses :doc:`lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask` to extract stars from individual calexp source catalog files.
If ``sourceTable_visit`` parquet tables are available, use of :doc:`lsst.fgcmcal.fgcmCalibrateTractTable.FgcmCalibrateTractTableTask` is recommended in place of this task.

``FgcmCalibrateTractTask`` is available as a :ref:`command-line task <pipe-tasks-command-line-tasks>`, :command:`fgcmCalibrateTract.py`.

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-summary:

Processing summary
==================

``FgcmCalibrateTractTask`` runs the full ``fgcmcal`` processing, from building star lists to fitting to the output of final products.
Specifically, it will:

#. Build the star lists: :doc:`lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask`

#. Run the fitter until convergence: :doc:`lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleTask`

#. Output the final data products: :doc:`lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsTask`

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-cli:

fgcmCalibrateTract.py command-line interface
============================================

.. code-block:: text

   fgcmCalibrateTract.py REPOPATH [@file [@file2 ...]] [--output OUTPUTREPO | --rerun RERUN] [--id] [other options]

Key arguments:

:option:`REPOPATH`
   The input Butler repository's URI or file path.

Key options:

:option:`--id`:
   The data IDs to process.  The ``tract`` must be specified.

.. seealso::

   See :ref:`command-line-task-argument-reference` for details and additional options.

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-api:

Python API summary
==================

.. lsst-task-api-summary:: lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-butler:

Butler datasets
===============

When run as the ``fgcmCalibrateTract.py`` command-line task, or directly through the `~lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask.runDataRef` method, ``FgcmCalibrateTractTask`` obtains datasets from the input Butler data repository and persists outputs to the output Butler data repository.
Note that configurations for ``FgcmCalibrateTractTask``, and its subtasks, affect what datasets are persisted and what their content is.

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-butler-inputs:

Input datasets
--------------

``camera``
   Camera geometry and detector object
``fgcmLookupTable``
    FGCM look-up table produced by :doc:`lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutTask`

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-butler-outputs:

Output datasets
---------------

``fgcm_stars``
    Reference catalog of standard stars.  See :doc:`lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsTask`
``fgcm_photoCalib_tract``
    One ``fgcm_photoCalib_tract`` photometric calibration file is output for each visit / ccd / tract.
``transmission_atmosphere_fgcm_tract``
    One atmospheric transmission curve is output for each visit.

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-subtasks:

Retargetable subtasks
=====================

.. lsst-task-config-subtasks:: lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-configs:

Configuration fields
====================

.. lsst-task-config-fields:: lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask

.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask-examples:

Examples
========

.. code-block:: bash

    fgcmCalibrateTract.py /datasets/hsc/repo --rerun <rerun name> --id visit=26024^26028^26032^26036^26044^26046^26048^26050^26058^26060^26062^26070^26072^26074^26080^26084^26094^23864^23868^23872^23876^23884^23886^23888^23890^23898^23900^23902^23910^23912^23914^23920^23924^28976^1258^1262^1270^1274^1278^1280^1282^1286^1288^1290^1294^1300^1302^1306^1308^1310^1314^1316^1324^1326^1330^24494^24504^24522^24536^24538^23212^23216^23224^23226^23228^23232^23234^23242^23250^23256^23258^27090^27094^27106^27108^27116^27118^27120^27126^27128^27130^27134^27136^27146^27148^27156^380^384^388^404^408^424^426^436^440^442^446^452^456^458^462^464^468^470^472^474^478^27032^27034^27042^27066^27068 ccd=0..8^10..103 tract=9615