JSOCClient#
- class sunpy.net.jsoc.JSOCClient[source]#
Bases:
BaseClient
Provides access to the JSOC Data Export service.
It exposes a similar API to the VSO client, although the underlying model is more complex. The JSOC stages data before you can download it, so a JSOC query is a three stage process. First you query the JSOC for records, a table of these records is returned. Then you can request these records to be staged for download and then you can download them. The last two stages of this process are bundled together into the
fetch()
method, but they can be separated if you are performing a large or complex query.Warning
JSOC requires you to register your email address before requesting data. See this on how to register.
Notes
The full list of
Series
is available via ` this page <http://jsoc.stanford.edu/JsocSeries_DataProducts_map.html>`__.JSOC requires a validated email address, you can pass in your validated email address using the
Notify
attribute. You have to register your email address with JSOC beforehand here.The backend of SunPy’s JSOC Client uses drms package. The tutorials can be found here. This can be used to build complex queries, by directly inputting the query string.
Examples
Example 1
Query JSOC for some HMI data at 45 second cadence:
>>> from sunpy.net import jsoc >>> from sunpy.net import attrs as a >>> client = jsoc.JSOCClient() >>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'), ... a.jsoc.Series('hmi.m_45s'), a.jsoc.Notify("sunpy@sunpy.org")) The response object holds the records that your query will return: >>> print(response) T_REC TELESCOP INSTRUME WAVELNTH CAR_ROT ----------------------- -------- ---------- -------- ------- 2014.01.01_00:00:45_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:01:30_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:02:15_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:03:00_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:03:45_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:04:30_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:05:15_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:06:00_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:06:45_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:07:30_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:08:15_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:09:00_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:09:45_TAI SDO/HMI HMI_FRONT2 6173.0 2145 2014.01.01_00:10:30_TAI SDO/HMI HMI_FRONT2 6173.0 2145
You can then make the request and download the data:
>>> res = client.fetch(response)
This returns a Results instance which can be used to watch the progress of the download.
Note
A registered email address is not required if you only need to query for data, it is used only if you need to make an export request. For example,:
>>> client = jsoc.JSOCClient() >>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'), ... a.jsoc.Series('hmi.m_45s'))
The above is a successful query operation, and will return query responses as before.
But, this response object cannot be used to make an export request and will throw an error if done so:
>>> res = client.fetch(response) ValueError: Email address is invalid or not registered
Example 2
Query the JSOC for some AIA 171 data, and separate out the staging and the download steps:
>>> import astropy.units as u >>> from sunpy.net import jsoc >>> from sunpy.net import attrs as a >>> client = jsoc.JSOCClient() >>> response = client.search(a.Time('2014/1/1T00:00:00', '2014/1/1T00:00:36'), ... a.jsoc.Series('aia.lev1_euv_12s'), a.jsoc.Segment('image'), ... a.Wavelength(171*u.AA), a.jsoc.Notify("sunpy@sunpy.org")) The response object holds the records that your query will return: >>> print(response) T_REC TELESCOP INSTRUME WAVELNTH CAR_ROT -------------------- -------- -------- -------- ------- 2014-01-01T00:00:01Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:13Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:25Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:37Z SDO/AIA AIA_3 171 2145
You can then make the request:
>>> requests = client.request_data(response)
This returns a list of all the ExportRequest objects for your query. You can get the ExportRequest ID
>>> requests.id 'JSOC_20171205_372'
You can also check the status of the request, which will print out a status message and return you the status code, a code of 1 means it is not ready to download and a code of 0 means the request is staged and ready. A code of 6 means an error, which is commonly that the request has not had time to get into the queue:
>>> requests.status 2
The status codes represent the following:
0: Completed, ready to download. 2: Pending, but downloadable. 6: Not found.
Once the status code is 0 or 2, you can download the data using the
get_request
method:>>> res = client.get_request(requests)
This returns a Results instance which can be used to watch the progress of the download:
>>> res.wait(progress=True)
Attributes Summary
This should return a string that is a URL to the data server or documentation on the data being served.
Methods Summary
Makes a network call to the VSO API that returns what keywords they support.
fetch
(jsoc_response[, path, progress, ...])Make the request for the data in a JSOC response and wait for it to be staged and then download the data.
get_request
(requests[, path, overwrite, ...])Query JSOC to see if the request(s) is ready for download.
We take this list and register all the keywords as corresponding Attrs.
This enables the client to register what kind of Attrs it can use directly.
request_data
(jsoc_response[, method])Request that JSOC stages the data for download.
search
(*query, **kwargs)Build a JSOC query and submit it to JSOC for processing.
Attributes Documentation
- default_max_conn = 1#
- info_url#
Methods Documentation
- static create_parse_jsoc_values()[source]#
Makes a network call to the VSO API that returns what keywords they support. We take this list and register all the keywords as corresponding Attrs.
- fetch(
- jsoc_response,
- path=None,
- progress=True,
- overwrite=False,
- downloader=None,
- wait=True,
- sleep=10,
- max_conn=1,
- **kwargs,
Make the request for the data in a JSOC response and wait for it to be staged and then download the data.
Note
Only complete searches can be downloaded from JSOC, this means that no slicing operations performed on the results object will affect the number of files downloaded.
- Parameters:
jsoc_response (
JSOCResponse
object) – A response objectpath (
str
) – Path to save data to, defaults to SunPy download dirprogress (
bool
, optional) – IfTrue
show a progress bar showing how many of the total files have been downloaded. IfFalse
, no progress bar will be shown.overwrite (
bool
orstr
, optional) – Determine how to handle downloading if a file already exists with the same name. IfFalse
the file download will be skipped and the path returned to the existing file, ifTrue
the file will be downloaded and the existing file will be overwritten, if'unique'
the filename will be modified to be unique.max_conn (
int
) – Maximum number of download connections.downloader (
parfive.Downloader
, optional) – The download manager to use.wait (
bool
, optional) – IfFalse
downloader.download()
will not be called. Only has any effect ifdownloader
is notNone
.sleep (
int
) – The number of seconds to wait between calls to JSOC to check the status of the request.
- Returns:
results (a
parfive.Results
instance) – Aparfive.Results
object.
- get_request(
- requests,
- path=None,
- overwrite=False,
- progress=True,
- downloader=None,
- wait=True,
- max_conn=1,
- **kwargs,
Query JSOC to see if the request(s) is ready for download.
If the request is ready for download, it will then download it.
- Parameters:
requests (
ExportRequest
,str
,list
) –ExportRequest
objects orstr
request IDs or lists returned byrequest_data
.path (
str
) – Path to save data to, defaults to SunPy download dir.progress (
bool
, optional) – IfTrue
show a progress bar showing how many of the total files have been downloaded. IfFalse
, no progress bar will be shown.overwrite (
bool
orstr
, optional) – Determine how to handle downloading if a file already exists with the same name. IfFalse
the file download will be skipped and the path returned to the existing file, ifTrue
the file will be downloaded and the existing file will be overwritten, if'unique'
the filename will be modified to be unique.downloader (
parfive.Downloader
, optional) – The download manager to use.wait (
bool
, optional) – IfFalse
downloader.download()
will not be called. Only has any effect ifdownloader
is notNone
.
- Returns:
res (
parfive.Results
) – Aparfive.Results
instance orNone
if no URLs to download
- static load_jsoc_values()[source]#
We take this list and register all the keywords as corresponding Attrs.
- Returns:
dict – The constructed Attrs dictionary ready to be passed into Attr registry.
- classmethod register_values()[source]#
This enables the client to register what kind of Attrs it can use directly.
- Returns:
dict
– A dictionary with key values of Attrs and the values are a tuple of (“Attr Type”, “Name”, “Description”).
- request_data(jsoc_response, method='url', **kwargs)[source]#
Request that JSOC stages the data for download. This method will not wait for the request to be staged.
- Parameters:
jsoc_response (
JSOCResponse
object) – The results of a querymethod ({
"url"
,"url-tar"
,"url-quick"
}) – Method for requesting JSOC data, can be ‘url-tar’, ‘url’ (the default) and ‘url-quick’ If ‘url-tar’ it will request JSOC to provide single .tar file which contains all data If ‘url’ it will request JSOC to provide all data as separate .fits files If ‘url-quick’ (only with protocol ‘as-is’) provide all data as separate files, but only if data is online.
- Returns:
requests (
ExportRequest
object or) – a list ofExportRequest
objects Request Id can be accessed by requests.id Request status can be accessed by requests.status
- search(*query, **kwargs)[source]#
Build a JSOC query and submit it to JSOC for processing.
Takes a variable number of
attrs
as parameters, which are chained together using the AND (&
) operator.Complex queries to be easily formed using logical operators such as
&
and|
, in the same way as the VSO client.- Parameters:
*query (a variable number of
attrs
) – as parameters, which are chained together using theAND
(&
) operator.- Returns:
response (
JSOCResponse
object) – A collection of records that the query returns.
Examples
Example 1
Request all AIA 304 image data between 2014-01-01T00:00 and 2014-01-01T01:00:
>>> import astropy.units as u >>> from sunpy.net import jsoc >>> from sunpy.net import attrs as a >>> client = jsoc.JSOCClient() >>> response = client.search(a.Time('2017-09-06T12:00:00', '2017-09-06T12:02:00'), ... a.jsoc.Series('aia.lev1_euv_12s'), a.Wavelength(304*u.AA), ... a.jsoc.Segment('image')) >>> print(response) T_REC TELESCOP INSTRUME WAVELNTH CAR_ROT -------------------- -------- -------- -------- ------- 2017-09-06T11:59:59Z SDO/AIA AIA_4 304 2194 2017-09-06T12:00:11Z SDO/AIA AIA_4 304 2194 2017-09-06T12:00:23Z SDO/AIA AIA_4 304 2194 2017-09-06T12:00:35Z SDO/AIA AIA_4 304 2194 2017-09-06T12:00:47Z SDO/AIA AIA_4 304 2194 2017-09-06T12:00:59Z SDO/AIA AIA_4 304 2194 2017-09-06T12:01:11Z SDO/AIA AIA_4 304 2194 2017-09-06T12:01:23Z SDO/AIA AIA_4 304 2194 2017-09-06T12:01:35Z SDO/AIA AIA_4 304 2194 2017-09-06T12:01:47Z SDO/AIA AIA_4 304 2194 2017-09-06T12:01:59Z SDO/AIA AIA_4 304 2194
Example 2
Request keyword data of “hmi.v_45s” and show specific columns only:
>>> import astropy.units as u >>> from sunpy.net import jsoc >>> from sunpy.net import attrs as a >>> client = jsoc.JSOCClient() >>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:10:00'), ... a.jsoc.Series('hmi.v_45s')) >>> print(response.show('T_REC', 'WAVELNTH', 'CAR_ROT')) T_REC WAVELNTH CAR_ROT ----------------------- -------- ------- 2014.01.01_00:00:45_TAI 6173.0 2145 2014.01.01_00:01:30_TAI 6173.0 2145 2014.01.01_00:02:15_TAI 6173.0 2145 2014.01.01_00:03:00_TAI 6173.0 2145 2014.01.01_00:03:45_TAI 6173.0 2145 2014.01.01_00:04:30_TAI 6173.0 2145 2014.01.01_00:05:15_TAI 6173.0 2145 2014.01.01_00:06:00_TAI 6173.0 2145 2014.01.01_00:06:45_TAI 6173.0 2145 2014.01.01_00:07:30_TAI 6173.0 2145 2014.01.01_00:08:15_TAI 6173.0 2145 2014.01.01_00:09:00_TAI 6173.0 2145 2014.01.01_00:09:45_TAI 6173.0 2145 2014.01.01_00:10:30_TAI 6173.0 2145
Example 3
Request data of
aia.lev1_euv_12s
on the basis of PrimeKeys other thanT_REC
:>>> import astropy.units as u >>> from sunpy.net import jsoc >>> from sunpy.net import attrs as a >>> client = jsoc.JSOCClient() >>> response = client.search(a.Time('2014-01-01T00:00:00', '2014-01-01T00:01:00'), ... a.jsoc.Series('aia.lev1_euv_12s'), ... a.jsoc.PrimeKey('WAVELNTH','171')) >>> print(response) T_REC TELESCOP INSTRUME WAVELNTH CAR_ROT -------------------- -------- -------- -------- ------- 2014-01-01T00:00:01Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:13Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:25Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:37Z SDO/AIA AIA_3 171 2145 2014-01-01T00:00:49Z SDO/AIA AIA_3 171 2145 2014-01-01T00:01:01Z SDO/AIA AIA_3 171 2145