<p align="center">
<img src="docs/hostphot_logo.png" alt="drawing" width="300"/>
</p>
Global and local photometry of galaxies hosting supernovae or other transients
[](https://github.com/temuller/hostphot)
[](https://hostphot.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/temuller/hostphot/blob/master/LICENSE)
[](https://github.com/temuller/hostphot/actions/workflows/main.yml)
[](https://pypi.org/project/hostphot/)
[](https://doi.org/10.21105/joss.04508)
[](https://doi.org/10.5281/zenodo.6992139)
[](https://raw.githubusercontent.com/temuller/hostphot/main/coverage.svg)
Read the full documentation at [hostphot.readthedocs.io](https://hostphot.readthedocs.io/en/latest/). It is recommended to read the **Further Information** section to understand how HostPhot works.
___
## Conda environment
It is recommended to create an environment before installing HostPhot:
```code
conda create -n hostphot pip
conda activate hostphot
pip install hostphot
```
### Requirements
HostPhot has the following requirements:
```code
numpy
pandas
matplotlib
python-dotenv
astropy
reproject
photutils
astroquery
extinction
sfdmap
pyvo
sep
ipywidgets (optional: for interactive aperture)
ipympl (optional: for interactive aperture)
ipython (optional: for interactive aperture)
pytest (optional: for testing the code)
```
### Tests
To run the tests, go to the parent directory and run the following command:
```code
pytest -v
```
## Modules
### Cutouts
This module allows you to download image cutouts from different surveys (e.g. `PS1`):
```python
from hostphot.cutouts import download_images
name = 'SN2004eo'
host_ra, host_dec = 308.2092, 9.92755 # coords of host galaxy of SN2004eo
survey = 'PS1'
download_images(name, host_ra, host_dec, survey=survey)
```
### Image Pre-processing
Coadds can be created and stars can be masked out of the images:
```python
from hostphot.coadd import coadd_images
coadd_filters = 'riz'
coadd_images(name, filters=coadd_filters, survey=survey) # creates a new fits file
```
```python
from hostphot.image_masking import create_mask
# one can extract the mask parameters from the coadd
# this also creates new fits files
coadd_mask_params = create_mask(name, host_ra, host_dec,
filt=coadd_filters, survey=survey,
extract_params=True)
for filt in 'grizy':
create_mask(name, host_ra, host_dec, filt, survey=survey,
common_params=coadd_mask_params)
```
If the user is not happy with the result of the masking, there are a few parameters that can be adjusted. For instance, `threshold` sets the threshold used by `sep` for detecting objects. Lowering it will allow the detection of fainter objects. `sigma` is the width of the gaussian used for convolving the image and masking the detected objects. If `crossmatch` is set to `True`, the detected objects are cross-matched with the Gaia catalog and only those in common are kept. This is useful for very nearby host galaxies (e.g. that of SN 2011fe) so the structures of the galaxy are not maked out, artificially lowering its flux.
### Local Photometry
Local photometry can be obtained for multiple circular apertures:
```python
import hostphot.local_photometry as lp
ap_radii = [3, 4] # aperture radii in units of kpc
ra, dec = 308.22579, 9.92853 # coords of SN2004eo
z = 0.0157 # redshift
results = lp.multi_band_phot(name, ra, dec, z,
survey=survey, ap_radii=ap_radii,
use_mask=True, correct_extinction=True,
save_plots=True)
```
If the results return `NaN` values, this means that the flux is below the detection limit for the given survey.
### Global Photometry
Global photometry can be obtained in a similar way to local photometry, using common aperture:
```python
import hostphot.global_photometry as gp
results = gp.multi_band_phot(name, host_ra, host_dec,
survey=survey, ra=ra, dec=dec,
use_mask=True, correct_extinction=True,
common_aperture=True, coadd_filters='riz',
save_plots=True)
```
By default, HostPhot corrects for Milky Way extinction using the recalibrated dust maps
by Schlafly & Finkbeiner (2011) and the extinction law from Fitzpatrick (1999).
### Surveys List
This is the list of surveys in HostPhot:
* DES
* PS1
* SDSS
* GALEX
* 2MASS
* WISE
* unWISE
* Legacy Survey
* Spitzer (SEIP)
* VISTA (VHS, VIDEO, VIKING)
* HST (WFC3 only)
* SkyMapper (not well calibrated for extended sources)
* SPLUS
* UKIDSS
## Contributing
To contribute, either open an issue or send a pull request (prefered option). You can also contact me directly (check my profile: https://github.com/temuller).
### Adding other surveys
If you wish a survey to be added to HostPhot, there are a couple of ways of doing it. 1) You can do a pull request, following the same structure as used for the surveys that are already implemented, or 2) open an issue asking for a survey to be added. Either way, there are a fews things needed to add a survey: where to download the images from (e.g., using `astroquery`), zero-points to convert the images's flux/counts values into magnitudes, the magnitude system (e.g. AB, Vega), the pixel scaling of the images (in units of arcsec/pixel), the filters transmission functions and any other piece of information necessary to properly estimate magnitudes, errors, etc. If you open an issue asking for a survey to be added, please include all this information. For more information, please check the [Adding New Surveys](https://hostphot.readthedocs.io/en/latest/further_information/adding_surveys.html) section of the documentation.
## Citing HostPhot
If you make use of HostPhot, please cite the following [paper](https://joss.theoj.org/papers/10.21105/joss.04508):
```code
@article{Müller-Bravo2022,
author = {Tomás E. Müller-Bravo and Lluís Galbany},
title = {HostPhot: global and local photometry of galaxies hosting supernovae or other transients},
doi = {10.21105/joss.04508},
url = {https://doi.org/10.21105/joss.04508},
year = {2022},
publisher = {The Open Journal},
volume = {7},
number = {76},
pages = {4508},
journal = {Journal of Open Source Software}
}
```
## What's new!
v2.9.0
* Fixing issue when applying/propagating common-mask parameters (e.g. from a coadd) to other images
* Updated error propagation for Legacy Survey with inverse-variance maps (using it as a weight mask now)
* Bumping up the DR version of VIKING and VIDEO for VISTA
v2.8.0
* Fix SED plotting with negative or too large values/errors, and improve plotting aesthetics
* Fix problem downloading some 2MASS images giving internal server error (no image overlap)
* Adding UKIDSS, SPLUS and SkyMapper surveys. WARNINGS: SkyMapper photometry (DR2) is not very accurate with extended sources!
* The marker showing the galaxy position on images has changed colour for better visualization
* Adding functions to easily load previously saved parameteres from pickle files
* Adding missing extinction correction for flux (not magnitudes)
* Including exposure time into flux for PS1, VISTA and UKIDSS surveys
* Adding SDSS ZP offsets into flux
* Output zeropoint together with the photometry
* Updating LegacySurvey errors, taken from inverse-variance maps and ZP uncertainty
* Adding missing offsets to unWISE W1 and W2 bands into fluxes
* Kron radius is no longer "optimized", just the scale, which doesn't have any effect in practice for the user
v2.7.1
* Adding SED plotting
* Fixed plotting angle of masked object
v2.7.0
* MAJOR BUG: Convertion factor between different pixel scales fixed (it was previously inverted). This affects the common aperture photometry between different surveys!
* Moving font family to `_constant.py` file
v2.6.2
* Prettier plots (now using `aplpy`), but also more informative!
* Scale of the apertures for the masks is now a parameter (`r`)
* Raise exception is now `True` by default when calculating photometry
v2.6.1
* 2MASS cutouts improved (picking largest image)
v2.6.0:
* HST (WFC3 only - pseudo-trial) included
* 2MASS cutouts fixed (it now downloads the image closest to the given coordinates)
v2.5.1:
* Using sfdmap2 instead of sfdmap to avoid issues with numpy version (requires Python>=3.9)
v2.5.0:
* Systematic error floor added to PS1 photometry
* Added missing uncertainties in the error budget of DES (~5 mmag)
* Flux/counts have been added to output photometry
* GALEX now downloads images with largest exposure time by default
* Fixed image realignment/orientation between different surveys when using common apertures (for masking and global photometry)
* Added option to output mask parameters, and also aperture parameters for global photometry
* Option added to set a distant threshold to identify the host galaxy in the image (by default use the nearest object)
* Slight change in the column names of the local photometry output file
* Offsets in SDSS zeropoints to place it in the AB system
* overwrite set to True by default when downloading image cutouts
* Other minor bugs fixed
v2.4.0:
* Fixed and improved GALEX cutouts
* Better galaxy identification
* Better output plots for masked images
* Option to return NaN or raise an exception when getting photometry
v2.3.2:
* Improved download of GALEX images (download even if they seem to be just background noise)
## Acknowledgements
I thank Yuchen LIU for helping me adding Spitzer as part of AstroHackWeek 2022.
Raw data
{
"_id": null,
"home_page": "https://github.com/temuller/hostphot",
"name": "hostphot",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Tom\u00e1s Enrique M\u00fcller-Bravo and Llu\u00eds Galbany",
"author_email": "t.e.muller-bravo@ice.csic.es",
"download_url": "https://files.pythonhosted.org/packages/4d/53/b1ad86784a1898f4952a78321eada13886819dfb85befa2116b184318ec6/hostphot-2.9.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n\t<img src=\"docs/hostphot_logo.png\" alt=\"drawing\" width=\"300\"/>\n</p>\n\nGlobal and local photometry of galaxies hosting supernovae or other transients\n\n[](https://github.com/temuller/hostphot)\n[](https://hostphot.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/temuller/hostphot/blob/master/LICENSE)\n[](https://github.com/temuller/hostphot/actions/workflows/main.yml)\n\n[](https://pypi.org/project/hostphot/)\n[](https://doi.org/10.21105/joss.04508)\n[](https://doi.org/10.5281/zenodo.6992139)\n[](https://raw.githubusercontent.com/temuller/hostphot/main/coverage.svg)\n\n\nRead the full documentation at [hostphot.readthedocs.io](https://hostphot.readthedocs.io/en/latest/). It is recommended to read the **Further Information** section to understand how HostPhot works.\n___\n## Conda environment\n\nIt is recommended to create an environment before installing HostPhot:\n\n```code\nconda create -n hostphot pip\nconda activate hostphot\npip install hostphot\n```\n\n### Requirements\n\nHostPhot has the following requirements:\n\n```code\nnumpy\npandas\nmatplotlib\npython-dotenv\nastropy\nreproject\nphotutils\nastroquery\nextinction\nsfdmap\npyvo\nsep\nipywidgets (optional: for interactive aperture)\nipympl (optional: for interactive aperture)\nipython (optional: for interactive aperture)\npytest (optional: for testing the code)\n```\n\n### Tests\n\nTo run the tests, go to the parent directory and run the following command:\n\n```code\npytest -v\n```\n\n## Modules\n\n### Cutouts\n\nThis module allows you to download image cutouts from different surveys (e.g. `PS1`):\n\n```python\nfrom hostphot.cutouts import download_images\n\nname = 'SN2004eo'\nhost_ra, host_dec = 308.2092, 9.92755 # coords of host galaxy of SN2004eo\nsurvey = 'PS1'\ndownload_images(name, host_ra, host_dec, survey=survey)\n```\n\n### Image Pre-processing\n\nCoadds can be created and stars can be masked out of the images:\n\n```python\nfrom hostphot.coadd import coadd_images\n\ncoadd_filters = 'riz'\ncoadd_images(name, filters=coadd_filters, survey=survey) # creates a new fits file\n```\n\n```python\nfrom hostphot.image_masking import create_mask\n\n# one can extract the mask parameters from the coadd\n# this also creates new fits files\ncoadd_mask_params = create_mask(name, host_ra, host_dec,\n filt=coadd_filters, survey=survey,\n extract_params=True) \n\nfor filt in 'grizy':\n create_mask(name, host_ra, host_dec, filt, survey=survey,\n common_params=coadd_mask_params)\n```\n\nIf the user is not happy with the result of the masking, there are a few parameters that can be adjusted. For instance, `threshold` sets the threshold used by `sep` for detecting objects. Lowering it will allow the detection of fainter objects. `sigma` is the width of the gaussian used for convolving the image and masking the detected objects. If `crossmatch` is set to `True`, the detected objects are cross-matched with the Gaia catalog and only those in common are kept. This is useful for very nearby host galaxies (e.g. that of SN 2011fe) so the structures of the galaxy are not maked out, artificially lowering its flux.\n\n### Local Photometry\n\nLocal photometry can be obtained for multiple circular apertures:\n\n\n```python\nimport hostphot.local_photometry as lp\n\nap_radii = [3, 4] # aperture radii in units of kpc\nra, dec = 308.22579, 9.92853 # coords of SN2004eo\nz = 0.0157 # redshift\n\nresults = lp.multi_band_phot(name, ra, dec, z,\n survey=survey, ap_radii=ap_radii, \n use_mask=True, correct_extinction=True,\n save_plots=True)\n```\n\nIf the results return `NaN` values, this means that the flux is below the detection limit for the given survey.\n\n### Global Photometry\n\nGlobal photometry can be obtained in a similar way to local photometry, using common aperture:\n\n```python\nimport hostphot.global_photometry as gp\n\nresults = gp.multi_band_phot(name, host_ra, host_dec, \n survey=survey, ra=ra, dec=dec,\n use_mask=True, correct_extinction=True,\n common_aperture=True, coadd_filters='riz', \n save_plots=True)\n```\n\nBy default, HostPhot corrects for Milky Way extinction using the recalibrated dust maps\nby Schlafly & Finkbeiner (2011) and the extinction law from Fitzpatrick (1999).\n\n### Surveys List\n\nThis is the list of surveys in HostPhot:\n\n * DES\n * PS1\n * SDSS\n * GALEX\n * 2MASS\n * WISE\n * unWISE\n * Legacy Survey\n * Spitzer (SEIP)\n * VISTA (VHS, VIDEO, VIKING)\n * HST (WFC3 only)\n * SkyMapper (not well calibrated for extended sources)\n * SPLUS\n * UKIDSS\n\n## Contributing\n\nTo contribute, either open an issue or send a pull request (prefered option). You can also contact me directly (check my profile: https://github.com/temuller).\n\n### Adding other surveys\n\nIf you wish a survey to be added to HostPhot, there are a couple of ways of doing it. 1) You can do a pull request, following the same structure as used for the surveys that are already implemented, or 2) open an issue asking for a survey to be added. Either way, there are a fews things needed to add a survey: where to download the images from (e.g., using `astroquery`), zero-points to convert the images's flux/counts values into magnitudes, the magnitude system (e.g. AB, Vega), the pixel scaling of the images (in units of arcsec/pixel), the filters transmission functions and any other piece of information necessary to properly estimate magnitudes, errors, etc. If you open an issue asking for a survey to be added, please include all this information. For more information, please check the [Adding New Surveys](https://hostphot.readthedocs.io/en/latest/further_information/adding_surveys.html) section of the documentation.\n\n\n## Citing HostPhot\n\nIf you make use of HostPhot, please cite the following [paper](https://joss.theoj.org/papers/10.21105/joss.04508):\n\n```code\n@article{M\u00fcller-Bravo2022, \n author = {Tom\u00e1s E. M\u00fcller-Bravo and Llu\u00eds Galbany},\n title = {HostPhot: global and local photometry of galaxies hosting supernovae or other transients},\n doi = {10.21105/joss.04508}, \n url = {https://doi.org/10.21105/joss.04508}, \n year = {2022}, \n publisher = {The Open Journal}, \n volume = {7}, \n number = {76}, \n pages = {4508}, \n journal = {Journal of Open Source Software} \n} \n```\n\n## What's new!\nv2.9.0\n* Fixing issue when applying/propagating common-mask parameters (e.g. from a coadd) to other images\n* Updated error propagation for Legacy Survey with inverse-variance maps (using it as a weight mask now)\n* Bumping up the DR version of VIKING and VIDEO for VISTA\n\nv2.8.0\n* Fix SED plotting with negative or too large values/errors, and improve plotting aesthetics\n* Fix problem downloading some 2MASS images giving internal server error (no image overlap)\n* Adding UKIDSS, SPLUS and SkyMapper surveys. WARNINGS: SkyMapper photometry (DR2) is not very accurate with extended sources!\n* The marker showing the galaxy position on images has changed colour for better visualization\n* Adding functions to easily load previously saved parameteres from pickle files\n* Adding missing extinction correction for flux (not magnitudes)\n* Including exposure time into flux for PS1, VISTA and UKIDSS surveys\n* Adding SDSS ZP offsets into flux\n* Output zeropoint together with the photometry\n* Updating LegacySurvey errors, taken from inverse-variance maps and ZP uncertainty\n* Adding missing offsets to unWISE W1 and W2 bands into fluxes\n* Kron radius is no longer \"optimized\", just the scale, which doesn't have any effect in practice for the user\n\nv2.7.1\n* Adding SED plotting\n* Fixed plotting angle of masked object \n\nv2.7.0\n* MAJOR BUG: Convertion factor between different pixel scales fixed (it was previously inverted). This affects the common aperture photometry between different surveys!\n* Moving font family to `_constant.py` file\n\nv2.6.2\n* Prettier plots (now using `aplpy`), but also more informative!\n* Scale of the apertures for the masks is now a parameter (`r`) \n* Raise exception is now `True` by default when calculating photometry\n\nv2.6.1\n* 2MASS cutouts improved (picking largest image)\n\nv2.6.0:\n* HST (WFC3 only - pseudo-trial) included\n* 2MASS cutouts fixed (it now downloads the image closest to the given coordinates)\n\nv2.5.1:\n* Using sfdmap2 instead of sfdmap to avoid issues with numpy version (requires Python>=3.9)\n\nv2.5.0:\n* Systematic error floor added to PS1 photometry\n* Added missing uncertainties in the error budget of DES (~5 mmag) \n* Flux/counts have been added to output photometry\n* GALEX now downloads images with largest exposure time by default\n* Fixed image realignment/orientation between different surveys when using common apertures (for masking and global photometry)\n* Added option to output mask parameters, and also aperture parameters for global photometry\n* Option added to set a distant threshold to identify the host galaxy in the image (by default use the nearest object)\n* Slight change in the column names of the local photometry output file\n* Offsets in SDSS zeropoints to place it in the AB system\n* overwrite set to True by default when downloading image cutouts\n* Other minor bugs fixed\n\nv2.4.0:\n* Fixed and improved GALEX cutouts\n* Better galaxy identification\n* Better output plots for masked images\n* Option to return NaN or raise an exception when getting photometry\n\nv2.3.2:\n* Improved download of GALEX images (download even if they seem to be just background noise)\n\n\n## Acknowledgements\n\nI thank Yuchen LIU for helping me adding Spitzer as part of AstroHackWeek 2022.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Global and local photometry of galaxies hosting supernovae or other transients",
"version": "2.9.0",
"project_urls": {
"Homepage": "https://github.com/temuller/hostphot"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "910cbfe46c5659daf1f804f3bb5d1d2a0c8624f1b131f65dd40dd543434e2795",
"md5": "76d37223cf6af803515649653badc410",
"sha256": "4ab80111e875b555aa40e3bd96719577b5216b3306c2f2a40547ea1cd2e02155"
},
"downloads": -1,
"filename": "hostphot-2.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76d37223cf6af803515649653badc410",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 1917259,
"upload_time": "2023-11-24T12:09:08",
"upload_time_iso_8601": "2023-11-24T12:09:08.922088Z",
"url": "https://files.pythonhosted.org/packages/91/0c/bfe46c5659daf1f804f3bb5d1d2a0c8624f1b131f65dd40dd543434e2795/hostphot-2.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d53b1ad86784a1898f4952a78321eada13886819dfb85befa2116b184318ec6",
"md5": "4fb431c8fa7f0c67c8145ed08c3ddd01",
"sha256": "4b88de2283d8ea99dff3bc8780e6152a6e742e6d8a21d26f35cf5ccc07a9e7fb"
},
"downloads": -1,
"filename": "hostphot-2.9.0.tar.gz",
"has_sig": false,
"md5_digest": "4fb431c8fa7f0c67c8145ed08c3ddd01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1879968,
"upload_time": "2023-11-24T12:09:11",
"upload_time_iso_8601": "2023-11-24T12:09:11.422381Z",
"url": "https://files.pythonhosted.org/packages/4d/53/b1ad86784a1898f4952a78321eada13886819dfb85befa2116b184318ec6/hostphot-2.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 12:09:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "temuller",
"github_project": "hostphot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pip",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "pickle5",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "aplpy",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
},
{
"name": "astropy",
"specs": []
},
{
"name": "reproject",
"specs": []
},
{
"name": "photutils",
"specs": []
},
{
"name": "astroquery",
"specs": []
},
{
"name": "extinction",
"specs": []
},
{
"name": "sfdmap2",
"specs": []
},
{
"name": "pyvo",
"specs": []
},
{
"name": "sep",
"specs": []
},
{
"name": "ipywidgets",
"specs": []
},
{
"name": "ipykernel",
"specs": []
},
{
"name": "ipympl",
"specs": []
},
{
"name": "ipython",
"specs": []
},
{
"name": "pytest",
"specs": []
}
],
"lcname": "hostphot"
}
JSON
