# scutout
Tool to extract source cutouts from a collection of FITS astronomical images
## **Credit**
This software is distributed with GPLv3 license. If you use scutout for your research, please add repository link or acknowledge authors in your papers.
## **Installation**
To install the package with pip from PyPi:
``` pip install scutout ```
To build and install the package from source:
* Clone this repository or download the tar file of the desired release;
* Create a local install directory, e.g. ```$INSTALL_DIR```;
* Add installation path to your ```PYTHONPATH``` environment variable:
``` export PYTHONPATH=$PYTHONPATH:$INSTALL_DIR/lib/python2.7/site-packages ```
* Build and install package:
``` python setup install --prefix=$INSTALL_DIR```
All dependencies will be automatically downloaded and installed in ```$INSTALL_DIR```.
To use package scripts:
* Add binary directory to your ```PATH``` environment variable:
``` export PATH=$PATH:$INSTALL_DIR/bin ```
## **Usage**
To run source cutout tool:
* Prepare a configuration file (e.g. ```config.ini```) with desired options (e.g. workdir, data paths, cutout search options, etc). A sample config file (.ini format) is provided in the ```config``` directory. Supported options are:
`[RUN]`
- `workdir`: Work directory where to place cutout files. Default: current directory
- `keep_tmpfiles`: To keep or remove tmp files produced per each source. Valid values: {yes|no}. Default: yes
`[CUTOUT_SEARCH]`
- `survey`: List of surveys to be searched, separated by commas. For each searched survey you must provide the path to metadata (e.g. a .tbl table produced by Montage mImgtbl task). Valid values: {first, nvss, mgps, vgps, sgps, cornish, scorpio_atca_2_1, scorpio_askap15_b1, scorpio_askap36_b123, scorpio_askap36_b123_ch[1-5], meerkat_gps, meerkat_gps_ch[1-14], askap_racs, thor, irac_3_6, irac_4_5, irac_5_8, irac_8, mips_24, higal_70, higal_160, higal_250, higal_350, higal_500, wise_3_4, wise_4_6, wise_12, wise_22, atlasgal, atlasgal_planck, msx_8_3, msx_12_1, msx_14_7, msx_21_3}.
- `use_same_radius`: Use the source radius given in `source_radius` option instead of the radius provided in input file. Valid values: {yes|no}. Default: no
- `source_radius`: Source radius in arcsec used by default if no radius is given in the input file. Default: 300"
- `cutout_factor`: Used to compute cutout size as 2 x source_radius x cutout_factor. Default: 5
- `multi_input_img_mode`: Method used to deal with multiple input image found in a given survey. Valid values: {best,mosaic,first}. Best takes the image in which the given source is better covered. Mosaic performs a mosaic of the available images found. This option is slower and was found to crash occasionally. First takes the first image available regardless of the source coverage. Default: best
- `convert_to_jy_pixel`: To convert cutout image units in Jy/pixels. Valid values: {yes|no}. Default: yes
- `subtract_bkg`: Subtract background from image (done before reprojection). Valid values: {yes|no}. Default: no
- `regrid`: To regrid cutouts to same projection (aligned to North): Valid values: {yes|no}. Default: yes
- `convolve`: To convolve cutouts to same resolution. Valid values: {yes|no}. Default: yes
- `crop`: To crop cutouts around source position to have final images with same number of pixels. Valid values: {yes|no}. Default: yes
- `crop_size`: Cropped image size in pixels. Default: 200
`[BKG_SUBTRACTION]`
- `bkg_estimator`: Estimator used to compute the background. Valid values: {median|sigmaclip}. Default: sigmaclip
- `bkg_inner_radius_factor`: Factor used to compute the background annulus inner radius R1= R_source x factor. Default: 1.1
- `bkg_outer_radius_factor`: Factor used to compute the background annulus outer radius R2= R_source x factor. Default: 1.2
- `bkg_max_nan_thr`: Max fraction of NAN pixels in background annulus above which bkg calculation fails. In this case the background is set to 0. Default: 0.1
`[XXX_DATA]`
- `metadata`: Path to Montage table (.tbl file produced with Montage mImgtbl task) containing survey FITS file list and metadata. Specify an option block per each survey XXX, where XXX can be: {FIRST, NVSS, MGPS, VGPS, SGPS, CORNISH, APEX_ATLASGAL, APEX_ATLASGAL_PLANCK, SCORPIO_ATCA_2_1_DATA, SCORPIO_ASKAP15_B1, SCORPIO_ASKAP36_B123, SCORPIO_ASKAP36_B123_CH[1-5], MEERKAT_GPS, MEERKAT_GPS_CH[1-14], ASKAP_RACS, THOR, WISE_3_4, WISE_4_6, WISE_12, WISE_22, SPITZER_IRAC3_6, SPITZER_IRAC4_5, SPITZER_IRAC5_8, SPITZER_IRAC8, SPITZER_MIPS24, HERSCHEL_HIGAL70, HERSCHEL_HIGAL160, HERSCHEL_HIGAL250, HERSCHEL_HIGAL350, HERSCHEL_HIGAL500, MSX_8_3, MSX_12_1, MSX_14_7, MSX_21_3}
* Prepare an ascii file (e.g. ```sources.dat```) with source sky positions for cutout extraction. File shall be given with the following header and space-delimited columns:
```# RA DEC RADIUS OBJNAME```
```ra1 dec1 r1 sname1```
```ra2 dec2 r2 sname2```
```... ... ... ...```
```... ... ... ...```
where:
- RA column (mandatory): Source right ascension in degrees
- DEC column (mandatory): Source declination in degrees
- RADIUS column (optional): Source radius in arcsec. If not given a default source radius (```source_radius``` option) will be used
- OBJNAME column (mandatory): Source name identifier, used as basis to create source cutout sub-directory
* Run cutout search:
``` $INSTALL_DIR/bin/run_scutout.py --config=config.ini --filename=sources.dat```
## **Testing**
To run unit tests, enter into scutout directory and type:
``` python -m unittest -v tests.test_utils```
or, if coverage library is installed:
``` coverage run --source=scutout -m unittest -v tests.test_utils ```
Raw data
{
"_id": null,
"home_page": "https://github.com/SKA-INAF/scutout",
"name": "scutout",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "source,cutout,survey",
"author": "Simone Riggi",
"author_email": "simone.riggi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/77/28/a2de2482f8caaee40cd34fb6deb22acee76ec2db758219d6fa6f5115065e/scutout-1.0.3.tar.gz",
"platform": null,
"description": "# scutout\nTool to extract source cutouts from a collection of FITS astronomical images\n\n## **Credit**\nThis software is distributed with GPLv3 license. If you use scutout for your research, please add repository link or acknowledge authors in your papers.\n\n## **Installation** \n\nTo install the package with pip from PyPi: \n\n``` pip install scutout ``` \n \nTo build and install the package from source: \n\n* Clone this repository or download the tar file of the desired release; \n* Create a local install directory, e.g. ```$INSTALL_DIR```; \n* Add installation path to your ```PYTHONPATH``` environment variable: \n ``` export PYTHONPATH=$PYTHONPATH:$INSTALL_DIR/lib/python2.7/site-packages ```\n* Build and install package: \n ``` python setup install --prefix=$INSTALL_DIR``` \n\nAll dependencies will be automatically downloaded and installed in ```$INSTALL_DIR```. \n \nTo use package scripts:\n\n* Add binary directory to your ```PATH``` environment variable: \n ``` export PATH=$PATH:$INSTALL_DIR/bin ``` \n\n## **Usage** \n\nTo run source cutout tool:\n\n* Prepare a configuration file (e.g. ```config.ini```) with desired options (e.g. workdir, data paths, cutout search options, etc). A sample config file (.ini format) is provided in the ```config``` directory. Supported options are: \n\n `[RUN]`\n - `workdir`: Work directory where to place cutout files. Default: current directory\n - `keep_tmpfiles`: To keep or remove tmp files produced per each source. Valid values: {yes|no}. Default: yes \n \n `[CUTOUT_SEARCH]`\n - `survey`: List of surveys to be searched, separated by commas. For each searched survey you must provide the path to metadata (e.g. a .tbl table produced by Montage mImgtbl task). Valid values: {first, nvss, mgps, vgps, sgps, cornish, scorpio_atca_2_1, scorpio_askap15_b1, scorpio_askap36_b123, scorpio_askap36_b123_ch[1-5], meerkat_gps, meerkat_gps_ch[1-14], askap_racs, thor, irac_3_6, irac_4_5, irac_5_8, irac_8, mips_24, higal_70, higal_160, higal_250, higal_350, higal_500, wise_3_4, wise_4_6, wise_12, wise_22, atlasgal, atlasgal_planck, msx_8_3, msx_12_1, msx_14_7, msx_21_3}. \n - `use_same_radius`: Use the source radius given in `source_radius` option instead of the radius provided in input file. Valid values: {yes|no}. Default: no\n - `source_radius`: Source radius in arcsec used by default if no radius is given in the input file. Default: 300\"\n - `cutout_factor`: Used to compute cutout size as 2 x source_radius x cutout_factor. Default: 5\n - `multi_input_img_mode`: Method used to deal with multiple input image found in a given survey. Valid values: {best,mosaic,first}. Best takes the image in which the given source is better covered. Mosaic performs a mosaic of the available images found. This option is slower and was found to crash occasionally. First takes the first image available regardless of the source coverage. Default: best\n - `convert_to_jy_pixel`: To convert cutout image units in Jy/pixels. Valid values: {yes|no}. Default: yes\n - `subtract_bkg`: Subtract background from image (done before reprojection). Valid values: {yes|no}. Default: no\n - `regrid`: To regrid cutouts to same projection (aligned to North): Valid values: {yes|no}. Default: yes\n - `convolve`: To convolve cutouts to same resolution. Valid values: {yes|no}. Default: yes\n - `crop`: To crop cutouts around source position to have final images with same number of pixels. Valid values: {yes|no}. Default: yes\n - `crop_size`: Cropped image size in pixels. Default: 200\n \n `[BKG_SUBTRACTION]` \n - `bkg_estimator`: Estimator used to compute the background. Valid values: {median|sigmaclip}. Default: sigmaclip\n - `bkg_inner_radius_factor`: Factor used to compute the background annulus inner radius R1= R_source x factor. Default: 1.1\n - `bkg_outer_radius_factor`: Factor used to compute the background annulus outer radius R2= R_source x factor. Default: 1.2\n - `bkg_max_nan_thr`: Max fraction of NAN pixels in background annulus above which bkg calculation fails. In this case the background is set to 0. Default: 0.1\n \n `[XXX_DATA]`\n - `metadata`: Path to Montage table (.tbl file produced with Montage mImgtbl task) containing survey FITS file list and metadata. Specify an option block per each survey XXX, where XXX can be: {FIRST, NVSS, MGPS, VGPS, SGPS, CORNISH, APEX_ATLASGAL, APEX_ATLASGAL_PLANCK, SCORPIO_ATCA_2_1_DATA, SCORPIO_ASKAP15_B1, SCORPIO_ASKAP36_B123, SCORPIO_ASKAP36_B123_CH[1-5], MEERKAT_GPS, MEERKAT_GPS_CH[1-14], ASKAP_RACS, THOR, WISE_3_4, WISE_4_6, WISE_12, WISE_22, SPITZER_IRAC3_6, SPITZER_IRAC4_5, SPITZER_IRAC5_8, SPITZER_IRAC8, SPITZER_MIPS24, HERSCHEL_HIGAL70, HERSCHEL_HIGAL160, HERSCHEL_HIGAL250, HERSCHEL_HIGAL350, HERSCHEL_HIGAL500, MSX_8_3, MSX_12_1, MSX_14_7, MSX_21_3} \n \n \n* Prepare an ascii file (e.g. ```sources.dat```) with source sky positions for cutout extraction. File shall be given with the following header and space-delimited columns: \n \n ```# RA DEC RADIUS OBJNAME``` \n ```ra1 dec1 r1 sname1``` \n ```ra2 dec2 r2 sname2``` \n ```... ... ... ...``` \n ```... ... ... ...``` \n \n where: \n - RA column (mandatory): Source right ascension in degrees \n - DEC column (mandatory): Source declination in degrees \n - RADIUS column (optional): Source radius in arcsec. If not given a default source radius (```source_radius``` option) will be used \n - OBJNAME column (mandatory): Source name identifier, used as basis to create source cutout sub-directory \n\n* Run cutout search: \n ``` $INSTALL_DIR/bin/run_scutout.py --config=config.ini --filename=sources.dat``` \n\n## **Testing** \n\nTo run unit tests, enter into scutout directory and type:\n\n``` python -m unittest -v tests.test_utils```\n\nor, if coverage library is installed:\n\n``` coverage run --source=scutout -m unittest -v tests.test_utils ```\n\n\n",
"bugtrack_url": null,
"license": "GPL3",
"summary": "Tool to extract source cutouts from a collection of astronomical FITS images",
"version": "1.0.3",
"project_urls": {
"Download": "https://github.com/user/reponame/archive/v1.0.0.tar.gz",
"Homepage": "https://github.com/SKA-INAF/scutout"
},
"split_keywords": [
"source",
"cutout",
"survey"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "28faf368ffc2fd5e042f92e7e09f705435db4aee6ec42e7d999758580d966441",
"md5": "0f9841c16aef846644c408ed051ee1bd",
"sha256": "240c5652a158b532f8af1d4c90d7120ca080d29c9560fb5f2da1fab24b85aa97"
},
"downloads": -1,
"filename": "scutout-1.0.3-py3.6.egg",
"has_sig": false,
"md5_digest": "0f9841c16aef846644c408ed051ee1bd",
"packagetype": "bdist_egg",
"python_version": "1.0.3",
"requires_python": null,
"size": 51182,
"upload_time": "2022-03-20T20:10:35",
"upload_time_iso_8601": "2022-03-20T20:10:35.524801Z",
"url": "https://files.pythonhosted.org/packages/28/fa/f368ffc2fd5e042f92e7e09f705435db4aee6ec42e7d999758580d966441/scutout-1.0.3-py3.6.egg",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f35b1ba361df924ae9a34bbe91e07547d7590866b791adf3d53d9ff4c17321b4",
"md5": "1e0c69c89647bd1d4057417a08af2907",
"sha256": "8770a3424dde0112a4a23b85fda562dca4033561392746bae5e56176f6a5374d"
},
"downloads": -1,
"filename": "scutout-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e0c69c89647bd1d4057417a08af2907",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 38011,
"upload_time": "2022-03-20T20:10:33",
"upload_time_iso_8601": "2022-03-20T20:10:33.369715Z",
"url": "https://files.pythonhosted.org/packages/f3/5b/1ba361df924ae9a34bbe91e07547d7590866b791adf3d53d9ff4c17321b4/scutout-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7728a2de2482f8caaee40cd34fb6deb22acee76ec2db758219d6fa6f5115065e",
"md5": "d226ee1230f59f51d5a5ec876725b874",
"sha256": "7491643ae67657d6609846dd864a4428d5f4675d91559b0b4f66700e543f1dab"
},
"downloads": -1,
"filename": "scutout-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "d226ee1230f59f51d5a5ec876725b874",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 36578,
"upload_time": "2022-03-20T20:10:37",
"upload_time_iso_8601": "2022-03-20T20:10:37.161473Z",
"url": "https://files.pythonhosted.org/packages/77/28/a2de2482f8caaee40cd34fb6deb22acee76ec2db758219d6fa6f5115065e/scutout-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-03-20 20:10:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SKA-INAF",
"github_project": "scutout",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "astropy",
"specs": []
},
{
"name": "montage-wrapper",
"specs": []
},
{
"name": "radio-beam",
"specs": []
},
{
"name": "regions",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "pyparsing",
"specs": []
},
{
"name": "enlighten",
"specs": []
}
],
"lcname": "scutout"
}
JSON
