.. _astroquery.esa.hsa: *************************************************** ESA Herschel Science Archive (`astroquery.esa.hsa`) *************************************************** `Herschel `__ was the fourth cornerstone in ESA's Horizon 2000 science programme, designed to observe the 'cool' universe. It performed photometry and spectroscopy in the poorly explored 55-670 µm spectral range with a 3.5 m diameter Cassegrain telescope, providing unique observing capabilities and bridging the gap between earlier infrared space missions and groundbased facilities. Herschel successfully performed ~37000 science observations and ~6600 science calibration observations which are publicly available to the worldwide astronomical community through the Herschel Science Archive. This package allows the access to the `Herschel Science Archive `_. Examples ======== 1. Getting Herschel data ------------------------ .. Skipping becuase of how long the download takes .. doctest-skip:: >>> from astroquery.esa.hsa import HSA >>> >>> HSA.download_data(observation_id='1342195355', retrieval_type='OBSERVATION', ... instrument_name='PACS') Downloading URL http://archives.esac.esa.int/hsa/whsa-tap-server/data?&retrieval_type=OBSERVATION&observation_id=1342195355&instrument_name=PACS to 1342195355.tar ... [Done] '1342195355.tar' This will download the products of the observation '1342195355' with the instrument 'PACS' and it will store them in a tar called '1342195355.tar'. The parameters available are detailed in the API. For more details of the parameters check the section 6 of the ``Direct Product Access using TAP`` in the `HSA users guide `_. For more details about the products check: https://www.cosmos.esa.int/web/herschel/data-products-overview 2. Getting Observation Products ------------------------------- .. Skipping becuase of how long the download takes .. doctest-skip:: >>> from astroquery.esa.hsa import HSA >>> >>> HSA.get_observation('1342195355', instrument_name='PACS') Downloading URL http://archives.esac.esa.int/hsa/whsa-tap-server/data?&retrieval_type=OBSERVATION&observation_id=1342195355&instrument_name=PACS to 1342195355.tar ... [Done] '1342195355.tar' This will download the product of the observation '1342195355' with the instrument 'PACS' and it will store them in a tar called '1342195355.tar'. The parameters available are detailed in the API. .. Note:: There is no difference between the product retrieved with this method and `~astroquery.esa.hsa.HSAClass.download_data`. `~astroquery.esa.hsa.HSAClass.download_data` is a more generic interface that allows the user to retrieve any product or metadata and `~astroquery.esa.hsa.HSAClass.get_observation` allows the user to retrieve only observation products. For more information check the section 6.1 of the of the ``Direct Product Access using TAP`` in the `HSA users guide`_. For more details of the parameters check the section 6.2 of the ``Direct Product Access using TAP`` in the `HSA users guide`_. 3. Getting Herschel Postcard ---------------------------- .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> >>> HSA.get_postcard('1342195355', instrument_name='PACS') # doctest: +IGNORE_OUTPUT Downloading URL http://archives.esac.esa.int/hsa/whsa-tap-server/data?&retrieval_type=POSTCARD&observation_id=1342195355&instrument_name=PACS to /home/dev/.astropy/cache/astroquery/HSA/data?&retrieval_type=POSTCARD&observation_id=1342195355&instrument_name=PACS ... [Done] '1342195355.jpg' This will download the postcard (static representation in JPG-format of the final product) of the observation '1342195355' with the instrument 'PACS' and it will store them in a tar called '1342195355.jpg'. The parameters available are detailed in the API. For more details of the parameters check the section 6.2 of the ``Direct Product Access using TAP`` in the `HSA users guide`_. 4. Getting Herschel metadata through TAP ---------------------------------------- This function provides access to the Herschel Science Archive database using the Table Access Protocol (TAP) and via the Astronomical Data Query Language (`ADQL `__). .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> >>> result = HSA.query_hsa_tap("select top 10 * from hsa.v_active_observation", ... output_format='csv', output_file='results.csv') >>> result.pprint(max_width=100) aor bii ... target_name urn_version --------------------------------------- ------------------- ... -------------- ----------- PP2-SWa-NGC3265 28.797292629881316 ... NGC3265 915907 PRISMAS_W33a_hifi3b_898GHz_A_D2O -17.86672520275456 ... W33A 806737 GOODS-S_70_d+8+8_forward_r3_shortaxis -27.80919396603746 ... GOODS-S d+8+8 894819 PSP2_HStars-Set12f - RedRectangle -10.637417697356986 ... Red Rectangle 800938 SPIRE-A - G126.24-5.52 57.195030974713134 ... G126.24-5.52 810242 PSP1_PRISMAS_W31C_hifi6a_1477GHz_A_D2H+ -19.93074108498436 ... W31C 920099 Spire Level-2 GOODS-S 37 - copy -27.81104151290488 ... GOODS-S 898135 PSP2_HStars-Set13 - 10216 13.27923027337195 ... IRC+10216 801364 PACS-A - G345.39-3.97 -43.47405026924179 ... G345.39-3.97-1 883176 PRISMAS_g34_hifi7b_1897GHz_B_C3 1.2495150652937468 ... G34.3+0.1 921086 This will execute an ADQL query to download the first 10 observations in the `Herschel Science Archive`_. The result of the query will be stored in the file ``results.csv``. 5. Getting table details of HSA TAP ----------------------------------- .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> >>> HSA.get_tables() INFO: Retrieving tables... [astroquery.utils.tap.core] INFO: Parsing tables... [astroquery.utils.tap.core] INFO: Done. [astroquery.utils.tap.core] ['hpdp.latest_observation_hpdp', 'hpdp.vizier_links', 'hpdp.unique_observation_hpdp', 'hpdp.latest_unique_observation_requests', 'hpdp.files', 'hpdp.latest_requests', 'public.dual', 'public.image_formats', 'tap_schema.tables', 'tap_schema.columns', 'tap_schema.keys', 'tap_schema.schemas', 'tap_schema.key_columns', 'hsa.observation_science', 'hsa.proposal_coauthor', 'hsa.proposal_observation', 'hsa.instrument', 'hsa.observing_mode_per_instrument', 'hsa.spire_spectral_feature_finder_catalogue', 'hsa.hifi_spectral_line_smoothed', 'hsa.publication', 'hsa.quality_flag', 'hsa.v_active_observation', 'hsa.proposal_info', 'hsa.pacs_point_source_070', 'hsa.observing_mode', 'hsa.proposal', 'hsa.proposal_pi_user', 'hsa.spire_point_source_350', 'hsa.spire_point_source_250', 'hsa.v_publication', 'hsa.spire_point_source_500', 'hsa.pacs_point_source_100', 'hsa.v_proposal_observation', 'hsa.hifi_spectral_line_native', 'hsa.pacs_point_source_160', 'hsa.ancillary', 'hsa.metadata_expert_panels', 'pubtool.institutions', 'pubtool.v_first_pub_date', 'pubtool.v_first_pub_date_single', 'pubtool.archival_type', 'pubtool.publication', 'pubtool.publication_details', 'pubtool.authors_institutions', 'pubtool.publication_observation', 'pubtool.authors', 'updp2.latest_observation_updp', 'updp2.vizier_links', 'updp2.latest_unique_observation_requests', 'updp2.files', 'updp2.latest_requests', 'updp2.unique_observation_updp'] This will show the available tables in HSA TAP service in the `Herschel Science Archive`_. 6. Getting columns details of HSA TAP ------------------------------------- .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> >>> HSA.get_columns('hsa.v_active_observation') INFO: Retrieving tables... [astroquery.utils.tap.core] INFO: Parsing tables... [astroquery.utils.tap.core] INFO: Done. [astroquery.utils.tap.core] ['aor', 'bii', 'dec', 'duration', 'end_time', 'fov', 'global_science_area', 'icon_image', 'icon_location', 'image_2_5_location', 'image_location', 'ingest_queue_oid', 'instrument_oid', 'is_active_version', 'is_public', 'lii', 'naif_id', 'num_publications', 'observation_id', 'observation_oid', 'observer', 'observing_mode_oid', 'obsstate', 'od_number', 'pa', 'polygon_fov', 'position', 'prop_end', 'proposal_id', 'quality_report_location', 'ra', 'science_area', 'science_category', 'spg_id', 'start_time', 'status', 'target_name', 'urn_version'] This will show the column details of the table ``'hsa.v_active_observation'`` in HSA TAP service in the `Herschel Science Archive`_. 7. Query Region --------------- .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> from astropy.coordinates import SkyCoord >>> from astropy import units as u >>> >>> c = SkyCoord(ra=100.2417*u.degree, dec=9.895*u.degree, frame='icrs') >>> result = HSA.query_region(c, 0.5) >>> result.pprint(max_width=100) aor bii ... target_name urn_version ... ------------------------------------------- ------------------ ... ---------------- ----------- KPOT_wlanger_1-HPoint-0007 - CII_G202.6+2.0 10.062774289985356 ... CII_G202.6+2.0-1 921022 n2264-o 9.45754288889945 ... NGC2264 919399 n2264-n 9.45754288889945 ... NGC2264 919398 n2264-n 9.450299102175919 ... NGC2264 898497 n2264-o 9.450499719127244 ... NGC2264 898535 Retrieve a VOTable with the observations metadata of a given region. 8. Query Observations --------------------- .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> from astropy.coordinates import SkyCoord >>> from astropy import units as u >>> >>> c = SkyCoord(ra=100.2417*u.degree, dec=9.895*u.degree, frame='icrs') >>> HSA.query_observations(c, 0.5) observation_id object -------------- 1342219315 1342205057 1342205056 1342205056 1342205057 Retrieve a VOTable with the observation IDs of a given region. 9. Procedure example -------------------- First retrieve the observation IDs based on a position on the sky. To achive this, query the TAP service. .. doctest-remote-data:: >>> from astroquery.esa.hsa import HSA >>> >>> HSA.query_hsa_tap("select top 10 observation_id from hsa.v_active_observation where " ... "contains(point('ICRS', hsa.v_active_observation.ra, hsa.v_active_observation.dec), " ... "circle('ICRS', 100.2417,9.895, 1.1))=1", output_format='csv', output_file='results.csv')
observation_id int64 -------------- 1342228342 1342228371 1342228372 1342219315 1342205057 1342205056 1342205058 1342205056 1342205057 In this example we are doing a circle search of 1.1 degrees in an ICRS (Right ascension [RA], Declination [DEC]) position (100.2417, 9.895). For more information on how to use ADQL see: 'https://www.ivoa.net/documents/latest/ADQL.html' After obtaining the desire ID, download the product of the observation '1342205057' with the instrument 'PACS'. .. doctest-skip:: >>> HSA.download_data(observation_id='1342205057', retrieval_type='OBSERVATION', instrument_name='PACS') Downloading URL http://archives.esac.esa.int/hsa/whsa-tap-server/data?&retrieval_type=OBSERVATION&observation_id=1342205057&instrument_name=PACS to 1342205057.tar ... [Done] '1342205057.tar' Troubleshooting =============== If you are repeatedly getting failed queries, or bad/out-of-date results, try clearing your cache: .. code-block:: python >>> from astroquery.esa.hsa import HSA >>> HSA.clear_cache() If this function is unavailable, upgrade your version of astroquery. The ``clear_cache`` function was introduced in version 0.4.7.dev8479. Reference/API ============= .. automodapi:: astroquery.esa.hsa :no-inheritance-diagram: .. testcleanup:: >>> from astroquery.utils import cleanup_saved_downloads >>> cleanup_saved_downloads(['1342195355*', 'results.csv'])