Initial setup

Activate the conda environment filabres and check that the software is available:

$ conda activate filabres
(filabres) $ filabres-version
1.3.0

Note that your version can be different to the one shown above.

Warning

  • From this point we are assuming that the user is always working within the filabres environment, although the prompt (filabres) $ will not be explicitly shown.

  • It is recommedable to start running the code from an empty directory.

Generate configuration files

The first thing that you need to do before start working with filabres is to generate some configuration files that will define the behavior of the program. These initial files can be easily generated by using the --setup with two arguments: 1) the name of the instrument, and 2) the directory where the original (raw data) FITS files are stored.

For example, to use the CAFOS instrument with the original files located under the directory /Volumes/NicoPassport/CAHA/CAFOS2017:

$ filabres --setup cafos /Volumes/NicoPassport/CAHA/CAFOS2017
File setup_filabres.yaml created!
File ignored_images.yaml created!
File image_corrections.yaml created!
File forced_classifications.yaml created!

The new files have been written in YAML format, which is a human-readable data-serialization language commonly used for configuration files.

File setup_filabres.yaml

The first file, setup_filabres.yaml, contains a few definitions:

 1# file setup_filabres.yaml
 2#
 3# generated automatically by filabres v.1.3.0
 4#
 5# creation date 2023-03-10T18:19:57.364013
 6#
 7instrument: cafos
 8datadir: /Volumes/NicoPassport/CAHA/CAFOS2017/
 9gaiadr_source: gaiadr2.gaia_source
10tweak_order_astrometry: 2
11ignored_images_file: ignored_images.yaml
12image_header_corrections_file: image_header_corrections.yaml
13forced_classifications_file: forced_classifications.yaml

  • instrument: the instrument name

  • datadir: the directory where the original (raw data) FITS files are stored

  • gaiadr_source: the database with the Gaia data release to be employed during the astrometric calibration. Note that the examples in this tutorial have been created using gaiadr2.gaia_source, although the last version of filabres will automatically set this parameter to gaiadr3.gaia_source.

  • tweak_order_astrometry: the polynomial degree employed to map the astrometric distortions using the Astrometry.net tools. This value is automatically set to 2, assuming that the astrometric calibration will be refined using the AstrOmatic tools (sextractor and scamp). If these tools are not installed, it is recommended to use a value of 3 to improve the initial (and unique in that case) astrometric solution.

  • ignored_images_file: the name of an auxiliary YAML file that contains files that must be ignored (explained below)

  • image_header_corrections_file: the name of an auxiliary YAML file that contains corrections for the classification of images (explained below).

  • forced_classifications_file: the name of an auxiliary YAML file that contains the images that have to be classified manually (explained below).

Note that under the directory datadir there must exist a subdirectory tree with the original FITS files segregated by observing night in different subdirectories, i.e.,

$ ls /Volumes/NicoPassport/CAHA/CAFOS2017/
170225_t2_CAFOS/ 170524_t2_CAFOS/ 170807_t2_CAFOS/ 171108_t2_CAFOS/
170226_t2_CAFOS/ 170525_t2_CAFOS/ 170809_t2_CAFOS/ 171116_t2_CAFOS/
170319_t2_CAFOS/ 170526_t2_CAFOS/ 170811_t2_CAFOS/ 171120_t2_CAFOS/
170331_t2_CAFOS/ 170527_t2_CAFOS/ 170825_t2_CAFOS/ 171121_t2_CAFOS/
170403_t2_CAFOS/ 170528_t2_CAFOS/ 170903_t2_CAFOS/ 171209_t2_CAFOS/
170408_t2_CAFOS/ 170601_t2_CAFOS/ 170918_t2_CAFOS/ 171217_t2_CAFOS/
170420_t2_CAFOS/ 170602_t2_CAFOS/ 170926_t2_CAFOS/ 171218_t2_CAFOS/
170422_t2_CAFOS/ 170621_t2_CAFOS/ 170928_t2_CAFOS/ 171219_t2_CAFOS/
170502_t2_CAFOS/ 170627_t2_CAFOS/ 170929_t2_CAFOS/ 171221_t2_CAFOS/
170505_t2_CAFOS/ 170628_t2_CAFOS/ 171002_t2_CAFOS/ 171223_t2_CAFOS/
170506_t2_CAFOS/ 170629_t2_CAFOS/ 171008_t2_CAFOS/ 171225_t2_CAFOS/
170507_t2_CAFOS/ 170713_t2_CAFOS/ 171011_t2_CAFOS/ 171228_t2_CAFOS/
170517_t2_CAFOS/ 170720_t2_CAFOS/ 171015_t2_CAFOS/ 171230_t2_CAFOS/
170518_t2_CAFOS/ 170724_t2_CAFOS/ 171016_t2_CAFOS/
170519_t2_CAFOS/ 170731_t2_CAFOS/ 171101_t2_CAFOS/

Note

The original FITS files are not modified by filabres. This program copies all the required files to the working directory in order to keep the original files safe from accidental overwritting or deletion. In this sense, the working directory should be different from datadir.

It is also possible to include additional definitions in the configuration file setup_filabres.yaml. For instance, one can define alternative configuration files to be used when running the AstrOmatic.net utilities sextractor and scamp:

# sextractor and scamp files
default_param: default.param
config_sex: config.sex
config_scamp: config.scamp

The inclusion of the previous lines in setup_filabres.yaml will force filabres to make use of the particular configuration files located at the current directory (the one from which you are actually running filabres). Note that you can also provide absolute paths to those file names. Obviously, those alternative files can be easily modified by the user to play with different options when running sextractor and/or scamp.

File ignored_images.yaml

The second YAML file is empty except for some comments:

1# file ignored_images.yaml
2#
3# generated automatically by filabres v.1.3.0
4#
5# creation date 2023-03-10T18:19:57.364437
6#

This file will contain a description of files that, for any reason, must be ignored. The inclusion of the unuseful file names here will help to keep all the original files within datadir without the need to actually removing them (which can allow later the recovery of any of the ignored files).

File image_header_corrections.yaml

The third YAML file is also empty except for the same comments:

1# file image_header_corrections.yaml
2#
3# generated automatically by filabres v.1.3.0
4#
5# creation date 2023-03-10T18:19:57.373984
6#

This file will describe changes that we will have to introduce in some FITS keywords of the original files in order to obtain a correct image classification.

File forced_classifications.yaml

The last YAML file is also empty except for the same comments:

1# file forced_classifications.yaml
2#
3# generated automatically by filabres v.1.3.0
4#
5# creation date 2023-03-10T18:19:57.374064
6#

This file will be used to define the images that will be manually classified.