MAST catalog query documentation missing explanations
- 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
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