.. _epscripts:

Entry-point console scripts
===========================

The scubes package includes various entry-point command-line scripts for 
different tasks. They are: :ref:`epscubes`, :ref:`epscubesml`, :ref:`epgetluptonrgb`,
:ref:`epsexmaskstars`, :ref:`epsexmaskstarscube`, :ref:`epml2header` and 
:ref:`epfilters`. Scripts with the ``ml`` (master list) identificator are optimized 
to work with information from with a list of objects used as input. The *cube* 
suffix will identify scripts which work with a cube produced by :ref:`epscubes` 
or :ref:`epscubesml` as input.

All scripts include the ``--help`` option for more information.

.. toctree::
    :maxdepth: 2
    :glob:
    
.. _radeconv:

Right-ascencion and Declination conversion
------------------------------------------

The input values of RA and DEC will be converted to degrees using the 
:meth:`scubes.utilities.io.convert_coord_to_degrees`. All scripts with RA 
and DEC inputs parse angles in two different units:

- **hourangle**: using *hms* divisors; Ex: *10h37m2.5s*
- **degrees**: using *:* or *dms*  divisors; Ex: *10:37:2.5* or *10d37m2.5s*

Note that *10h37m2.5s* is a totally different angle from *10:37:2.5* 
(*159.26 deg* and *10.62 deg* respectively).

.. _epscubes:

``scubes`` 
----------
.. literalinclude:: ../src/scubes/entry_points.py
    :language: python
    :linenos:
    :lines: 104-124

``scubes`` is the main script of **S-Cubes**. It calibrates the zero-points, 
calculates the fluxes and uncertainties for the 12-band images cropped from 
`S-PLUS <https://www.splus.iag.usp.br/>`__ observed tiles. The stamps are 
downloaded from `S-PLUS Cloud <https://splus.cloud/>`__ and the zero-points 
for the data-release 4 (DR4) are 
`included <https://github.com/splus-collab/s-cubes/tree/main/src/scubes/data>`__ 
to the package.

The usage of this script is detailed in :ref:`How to create a cube`.

.. _epscubesml:

``scubesml`` 
------------
.. literalinclude:: ../src/scubes/entry_points.py
    :language: python
    :linenos:
    :lines: 195-221

``scubesml`` is the same as :ref:`epscubes` but gathering the needed input 
information from a *masterlist*. 

*Masterlist* is a csv text file in which one could gather information of a list 
of objects to create cubes. The file must contain at least 5 columns named with 
the following header and information:

#. ``SNAME``: A nickname for the object 
#. ``FIELD``: S-PLUS Field (TILE) in which the program will search for the coordinates 
#. ``RA__deg``: Right-ascencion in degrees 
#. ``DEC__deg``: Declination in degrees 
#. ``SIZE__pix``: SIZE of the object in pixels 

Masterlist file content example::

    SNAME,FIELD,RA__deg,DEC__deg,SIZE__pix
    S00001,SPLUS-s24s34,52.08196,-31.06817,53.65902
    S00002,SPLUS-s24s35,52.87771,-30.21333,25.898617
    (...)

.. warning::
    There are some differences betweeen ``scubesml`` and ``scubes``. The former does 
    not have some options available on the latter (e.g. *--det_img*, *--mask_stars*, 
    etc). Another difference is that at the end of the execution of the script, 
    ``scubesml`` automatically runs the same routines executed by :ref:`epml2header`,
    including all the masterlist information to the *primary header* of the cube.
    Moreover, the size of the object (``scubes`` option *--size*) is created using 
    the option *--size_multiplicator*. The size will be:

    .. math::
        S = S_{mult} \times R_{50}\ \mathrm{[pix]}

Entry-point console ``scubesml`` call example:

.. code:: console

   scubesml --w workdir --size_multiplicator 10 -- MY_OBJECT /path/to/my_masterlist.csv

.. _epgetluptonrgb:

``get_lupton_RGB`` 
------------------
.. literalinclude:: ../src/scubes/utilities/utils.py
    :language: python
    :linenos:
    :lines: 97-110

This script will generate a Lupton RGB for the coordinates and size required by
the user. The imagem will be generated and downloaded from the 
`S-PLUS Cloud <https://splus.cloud/>`__ server. 

.. code:: console
    
    get_lupton_RGB -l 1500 -g NGC1365 -- SPLUS-s28s33 53.40004798 -36.14143008

.. _epsexmaskstars:

``sex_mask_stars``
------------------
.. literalinclude:: ../src/scubes/utilities/utils.py
    :language: python
    :linenos:
    :lines: 167-210

``sex_mask_stars`` scripts uses SExtractor in order to create a spatial mask of
stars, attempting to remove the areas enclosed by the brightest ones along the 
FOV. This script implements the *--mask_stars* option of the scubes. 

.. code:: console

    sex_mask_stars --back_size 256 --class_star 0.4 -l 1500 -g NGC1365 -- SPLUS-s28s33 53.40004798 -36.14143008

.. _epsexmaskstarscube:

``sex_mask_stars_cube`` 
-----------------------
.. literalinclude:: ../src/scubes/utilities/utils.py
    :language: python
    :linenos:
    :lines: 291-334

The same as ``sex_mask_stars`` but gathering the required information to run from
a cube generated by ``scubes`` or ``scubesml``.

.. code:: console

    sex_mask_stars_cube -p 0.3 -B 256 MYGALAXY_cube.fits

.. _epml2header:

``ml2header``
--------------
.. literalinclude:: ../src/scubes/utilities/utils.py
    :language: python
    :linenos:
    :lines: 422-443

This script will add all masterlist information to the primary header of a S-CUBES 
original cube.

.. code:: console
    
    ml2header /path/to/MYGALAXY_cube.fits /path/to/my_masterlist.csv

.. _epfilters:

``scubes_filters``
------------------
.. literalinclude:: ../src/scubes/entry_points.py
    :language: python
    :linenos:
    :lines: 237-259

This script prints the S-PLUS filters information table formatted with the 
required number of decimals.

.. code:: console

    scubes_filters --decimals 2