astropy / astropy/astroquery

MAST catalog query documentation missing explanations

Open
#2,715 1 comment 0 reactions 0 assignees View on GitHub
Documentation mast
Dominant language
Python
Stars
791
Forks
451
Avg merge
1d 3h
Merged PRs (30d)
4

Description

From the [documentation](https://astroquery.readthedocs.io/en/latest/mast/mast.html), `Catalogs.query_region` receives at least `catalog`, `version`, `magtype`, `data_release`, and `table`. According to the docstring, the first two are arguments and the others seem to be kwargs.

1. The website's [explanation on API](https://astroquery.readthedocs.io/en/latest/api/astroquery.mast.ObservationsClass.html#astroquery.mast.ObservationsClass.query_region) seems to be outdated? `Catalogs.query_region?` shows more parameters such as `catalog` and `version`.
2. I think the explanation of these parameters/kwargs are very vague. For Gaia, `version=2` means DR2, while I should use `data_release=2` for Pan-STARRS1 DR2, and not vice versa. Where can I find information about these parameters? (Apparently, I couldn't find the information from the link in the documentation, e.g., [this](https://mast.stsci.edu/api/v0/pages.html))
3. I couldn't find the possible choices of, e.g., `table`.
4. From [MAST](https://mast.stsci.edu/api/v0/_services.html#MastCatalogsGaiaDR3Cone) I see Gaia DR3 is available (or did they just updated the documentation first?), while gaia query with different `version` values only return up to DR2. Am I missing something?

```python
import astroquery
astroquery.__version__
# '0.4.7.dev8438'
```

Contributor guide

Open the contributing guide

Research direction

Start with the MAST catalog documentation and the Catalogs.query_region docstring, then compare their parameters with the linked MAST service documentation. Document the meanings and valid choices for catalog, version, magtype, data_release, and table, and clarify the available Gaia releases and API references.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.