Archives

NEIDArchive and EXPRESArchive are the two classes you will use directly. Instantiate one, call a query_* method to search the archive, and optionally call download on the result. Every query returns an astropy.table.Table.

For guidance on which query method to reach for, see Choosing a query. For a description of each archive’s data products and access rules, see NEID and EXPRES.

BaseArchive (below) is the shared abstract base class both archives inherit from. Most users never instantiate it directly; it is documented here as the authoritative reference for inherited behaviour.

NEIDArchive

class nexsci_rv.NEIDArchive(*, server=None, cookie_path=None, timeout=None, conf=None)

Bases: BaseArchive

Client for the NEID archive at IPAC.

Example

>>> from nexsci_rv import NEIDArchive
>>> neid = NEIDArchive()
>>> tbl = neid.query_datetime("l2", ("2024-11-01", "2024-11-06"))

Authentication is only required for proprietary data; public observations are queryable without login().

Parameters:

  • server (str | None)

  • cookie_path (Path | None)

  • timeout (float | None)

  • conf (Conf | None)

EXPRESArchive

class nexsci_rv.EXPRESArchive(*, server=None, cookie_path=None, timeout=None, conf=None)

Bases: BaseArchive

Client for EXPRES solar data hosted on the NEID/IPAC TAP service.

Example

>>> from nexsci_rv import EXPRESArchive
>>> expres = EXPRESArchive()
>>> sun = expres.query_datetime(
...     "solarl2",
...     ("2024-11-01", "2024-11-06"),
...     columns=["l2filename", "obsdate", "v", "e_v", "dvrms", "extsnr"],
... )

All EXPRES solar data is public; login() is not required and raises NotApplicable if called.

EXPRES solar rows carry sentinel qrad/qdecd values of -99.9, so query_position(), query_object(), and query_qobject() all raise NotApplicable.

Parameters:

  • server (str | None)

  • cookie_path (Path | None)

  • timeout (float | None)

  • conf (Conf | None)

query_position(data_level, coord, radius, *, columns=None, where=None, maxrec=None, output_format='votable')

Return rows whose (ra, dec) lies within radius of coord.

Parameters:

  • data_level (str)

  • coord (CoordInput)

  • radius (RadiusInput)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (OutputFormat)

Return type:

Table

query_object(data_level, name, radius=<Quantity 30. arcsec>, **kw)

Resolve name via Simbad/NED, then run a position search.

Parameters:

  • data_level (str)

  • name (str)

  • radius (RadiusInput)

  • kw (Any)

Return type:

Table

query_qobject(data_level, qobject, *, columns=None, where=None, maxrec=None, output_format='votable')

Search by the QOBJECT column (typically a Gaia DR2 ID).

Unlike query_object(), no name resolution is performed — this is a direct column match.

Parameters:

  • data_level (str)

  • qobject (str)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (OutputFormat)

Return type:

Table

query_pi(data_level, pi_name, *, columns=None, where=None, maxrec=None, output_format='votable')

Search by the PINAME column (exact match).

Parameters:

  • data_level (str)

  • pi_name (str)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (OutputFormat)

Return type:

Table

query_criteria(criteria, *, columns=None, maxrec=None, output_format='votable')

Combine multiple constraints in a single ADQL round-trip.

Accepted keys (besides the required data_level):

  • datetime: (start, end) tuple — same form as query_datetime()

  • position: (coord, radius) tuple

  • object: name → resolved via Simbad/NED, with optional radius

  • qobject: exact match on the QOBJECT column

  • program: exact match on PROGRAM

  • pi_name: exact match on PINAME

  • where: raw ADQL fragment ANDed with the above

Parameters:

  • criteria (dict[str, Any])

  • columns (list[str] | None)

  • maxrec (int | None)

  • output_format (OutputFormat)

Return type:

Table

BaseArchive

class nexsci_rv.BaseArchive(*, server=None, cookie_path=None, timeout=None, conf=None)

Bases: ABC

Common surface for all archive backends.

Parameters:

  • server (str | None)

  • cookie_path (Path | None)

  • timeout (float | None)

  • conf (Conf | None)

login(username=None, password=None)

Authenticate against the archive’s login endpoint.

Raises:

NotApplicable – if the archive does not support login.

Parameters:

  • username (str | None)

  • password (str | None)

Return type:

None

logout()

Drop the in-memory session and delete the cookie file.

Return type:

None

property is_authenticated: bool

True if a session cookie is loaded.

query_datetime(data_level, date_range, *, columns=None, where=None, maxrec=None, output_format='votable')

Return rows whose observation datetime is in date_range.

date_range is an inclusive (start, end) pair; either side may be None for an open-ended interval.

Parameters:

  • data_level (str)

  • date_range (DateRange)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (OutputFormat)

Return type:

Table

query_position(data_level, coord, radius, *, columns=None, where=None, maxrec=None, output_format='votable')

Return rows whose (ra, dec) lies within radius of coord.

Parameters:

  • data_level (str)

  • coord (adql.CoordInput)

  • radius (adql.RadiusInput)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (OutputFormat)

Return type:

Table

query_object(data_level, name, radius=<Quantity 30. arcsec>, **kw)

Resolve name via Simbad/NED, then run a position search.

Parameters:

  • data_level (str)

  • name (str)

  • radius (adql.RadiusInput)

  • kw (Any)

Return type:

Table

query_qobject(data_level, qobject, *, columns=None, where=None, maxrec=None, output_format='votable')

Search by the QOBJECT column (typically a Gaia DR2 ID).

Unlike query_object(), no name resolution is performed — this is a direct column match.

Parameters:

  • data_level (str)

  • qobject (str)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (Literal['ipac', 'csv', 'votable'])

Return type:

Table

query_program(data_level, program, *, columns=None, where=None, maxrec=None, output_format='votable')

Search by the PROGRAM column (exact match).

Parameters:

  • data_level (str)

  • program (str)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (Literal['ipac', 'csv', 'votable'])

Return type:

Table

query_pi(data_level, pi_name, *, columns=None, where=None, maxrec=None, output_format='votable')

Search by the PINAME column (exact match).

Parameters:

  • data_level (str)

  • pi_name (str)

  • columns (list[str] | None)

  • where (str | None)

  • maxrec (int | None)

  • output_format (Literal['ipac', 'csv', 'votable'])

Return type:

Table

query_criteria(criteria, *, columns=None, maxrec=None, output_format='votable')

Combine multiple constraints in a single ADQL round-trip.

Accepted keys (besides the required data_level):

  • datetime: (start, end) tuple — same form as query_datetime()

  • position: (coord, radius) tuple

  • object: name → resolved via Simbad/NED, with optional radius

  • qobject: exact match on the QOBJECT column

  • program: exact match on PROGRAM

  • pi_name: exact match on PINAME

  • where: raw ADQL fragment ANDed with the above

Parameters:
Return type:

Table

query_adql(adql_query, *, maxrec=None, output_format='votable')

Raw ADQL escape hatch — caller is responsible for the query string.

Parameters:

  • adql_query (str)

  • maxrec (int | None)

  • output_format (Literal['ipac', 'csv', 'votable'])

Return type:

Table

list_tables()

Names of tables this backend knows about (static).

Return type:

list[str]

describe_table(table)

Query TAP_SCHEMA for column metadata of table.

Parameters:

table (str)

Return type:

Table

submit_async(adql_query, *, maxrec=None, output_format='votable')

Submit an async ADQL job; returns an AsyncJob handle.

Parameters:

  • adql_query (str)

  • maxrec (int | None)

  • output_format (Literal['ipac', 'csv', 'votable'])

Return type:

AsyncJob

download(result_table, outdir='.', *, data_level=None, workers=None, resume=True, progress=True)

Download all FITS files referenced by result_table.

Returns the list of successfully downloaded paths. Partial failures raise DownloadError after best-effort completion.

Tables returned by the query_* methods remember their data level, so data_level is normally unnecessary. It is required for tables from query_adql() or built by hand, unless exactly one data level matches the table’s filename columns.

Parameters:
Return type:

list[Path]