Client#

class drms.Client(server='jsoc', *, email=None)[source]#

Bases: object

Client for remote DRMS server access.

Parameters:

server (str or drms.config.ServerConfig) – Registered server ID or ServerConfig instance. Defaults to JSOC.
email (str or None) – Default email address used data export requests.

Attributes Summary

email

(string) Default email address used for data export requests.

Methods Summary

`check_email`(email)	Check if the email address is registered for data export.
`export`(ds, *[, method, protocol, ...])	Submit a data export request.
`export_from_id`(requestid)	Create an `ExportRequest` instance from an existing requestid.
`info`(ds)	Get information about the content of a data series.
`keys`(ds)	Get a list of keywords that are available for a series.
`pkeys`(ds)	Get a list of primekeys that are available for a series.
`query`(ds, *[, key, seg, link, ...])	Query keywords, segments and/or links of a record set.
`series`([regex, full])	List available data series.

Attributes Documentation

email#: (string) Default email address used for data export requests.

Methods Documentation

check_email(email)[source]#

Check if the email address is registered for data export.

You can register your email for data exports from JSOC on the JSOC email registration webpage.

Parameters:: email (str) – Email address to be checked.
Returns:: result – True if the email address is valid and registered, False otherwise.
Return type:: bool

export(ds, *, method='url_quick', protocol='as-is', protocol_args=None, filenamefmt=None, n=None, email=None, requester=None, process=None)[source]#

Submit a data export request.

A registered email address is required for data exports. You can register your email address for data exports from JSOC on the JSOC email registration webpage.

An interactive webinterface and additional information is available on the JSOC data export webpage.

Note that export requests that were submitted using the webinterface can be accessed using the export_from_id() method.

Parameters:

ds (str) – Data export record set query.
method (str) – Export method. Supported methods are: ‘url_quick’, ‘url’ and ‘url-tar’. Default is ‘url_quick’.
protocol (str) – Export protocol. Supported protocols are: ‘as-is’, ‘fits’, ‘jpg’, ‘mpg’ and ‘mp4’. Default is ‘as-is’.
protocol_args (dict) – Extra protocol arguments for protocols ‘jpg’, ‘mpg’ and ‘mp4’. Valid arguments are: ‘ct’, ‘scaling’, ‘min’, ‘max’ and ‘size’. See the JSOC data export webpage for more details.
filenamefmt (str, None or bool) – Custom filename format string for exported files. This is ignored for ‘url_quick’/’as-is’ data exports. If set to None (default), the format string will be generated using the primekeys of the data series. If set to False, the filename format string will be omitted in the export request.
n (int or None) – Limits the number of records requested. For positive values, the first n records of the record set are returned, for negative values the last abs(n) records. If set to None (default), no limit is applied.
email (str or None) – Registered email address. If email is None (default), the current default email address is used, which in this case has to be set before calling export() by using the Client.email attribute.
process (dict, None) – Dictionary of processing commands. Each entry is also a dict containing all of the applicable options for that processing command. Note that only the name of the process, and not the arguments, are validated by the Client. In the case of invalid or malformed processing arguments, JSOC may still return an unprocessed image without the export request failing.
requester (str, None or bool) – Export user ID. Default is None, in which case the user name is determined from the email address. If set to False, the requester argument will be omitted in the export request.

Returns:

result

Return type:

ExportRequest

export_from_id(requestid)[source]#

Create an ExportRequest instance from an existing requestid.

Parameters:: requestid (str) – Export request ID.
Returns:: result
Return type:: ExportRequest

info(ds)[source]#

Get information about the content of a data series.

Parameters:: ds (str) – Name of the data series.
Returns:: result – SeriesInfo instance containing information about the data series.
Return type:: SeriesInfo

keys(ds)[source]#

Get a list of keywords that are available for a series. Use the info() method for more details.

Parameters:: ds (str) – Name of the data series.
Returns:: result – List of keywords available for the selected series.
Return type:: list

pkeys(ds)[source]#

Get a list of primekeys that are available for a series. Use the info() method for more details.

Parameters:: ds (str) – Name of the data series.
Returns:: result – List of primekeys available for the selected series.
Return type:: list

query(ds, *, key=None, seg=None, link=None, convert_numeric=True, skip_conversion=None, pkeys=False, rec_index=False, n=None)[source]#

Query keywords, segments and/or links of a record set. At least one of the parameters key, seg, link or pkeys needs to be specified.

Parameters:

ds (str) – Record set query.
key (str, List[str] or None) – List of requested keywords, optional. If set to None (default), no keyword results will be returned, except when pkeys is True.
seg (str, List[str] or None) – List of requested segments, optional. If set to None (default), no segment results will be returned.
link (str, List[str] or None) – List of requested Links, optional. If set to None (default), no link results will be returned.
convert_numeric (bool) – Convert keywords with numeric types from string to numbers. This may result in NaNs for invalid/missing values. Default is True.
skip_conversion (List[str] or None) – List of keywords names to be skipped when performing a numeric conversion. Default is None.
pkeys (bool) – If True, all primekeys of the series are added to the key parameter.
rec_index (bool) – If True, record names are used as index for the resulting DataFrames.
n (int or None) – Limits the number of records returned by the query. For positive values, the first n records of the record set are returned, for negative values the last abs(n) records. If set to None (default), no limit is applied.

Returns:

res_key (pandas.DataFrame, optional) – Keyword query results. This DataFrame is only returned, if key is not None or pkeys is set to True.
res_seg (pandas.DataFrame, optional) – Segment query results. This DataFrame is only returned, if seg is not None.
res_link (pandas.DataFrame, optional) – Link query results. This DataFrame is only returned, if link is not None.

series(regex=None, *, full=False)[source]#

List available data series.

Parameters:

regex (str or None, optional) – Regular expression, used to select a subset of the available series. If set to None, a list of all available series is returned.
full (bool) – If True, return a pandas.DataFrame containing additional series information, like description and primekeys. If False (default), the result is a list containing only the series names.

Returns:

result – List of series names or DataFrame containing name, primekeys and a description of the selected series (see parameter full).

Return type:

list or pandas.DataFrame