rms-starcat 0.0.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

rms_starcat-1.0.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.1
+Name: rms-starcat
+Version: 1.0.0
+Summary: Star catalog database
+Maintainer-email: "Robert S. French" <rfrench@seti.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/SETI/rms-starcat
+Project-URL: Repository, https://github.com/SETI/rms-starcat
+Project-URL: Source, https://github.com/SETI/rms-starcat
+Project-URL: Issues, https://github.com/SETI/rms-starcat/issues
+Keywords: UCAC4,YBSC,star
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Natural Language :: English
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cspyce
+Requires-Dist: numpy
+
+[![GitHub release; latest by date](https://img.shields.io/github/v/release/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/releases)
+[![GitHub Release Date](https://img.shields.io/github/release-date/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/releases)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/SETI/rms-starcat/run-tests.yml?branch=main)](https://github.com/SETI/rms-starcat/actions)
+[![Documentation Status](https://readthedocs.org/projects/rms-starcat/badge/?version=latest)](https://rms-starcat.readthedocs.io/en/latest/?badge=latest)
+[![Code coverage](https://img.shields.io/codecov/c/github/SETI/rms-starcat/main?logo=codecov)](https://codecov.io/gh/SETI/rms-starcat)
+<br />
+[![PyPI - Version](https://img.shields.io/pypi/v/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Format](https://img.shields.io/pypi/format/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rms-starcat)](https://pypi.org/project/rms-starcat)
+<br />
+[![GitHub commits since latest release](https://img.shields.io/github/commits-since/SETI/rms-starcat/latest)](https://github.com/SETI/rms-starcat/commits/main/)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/commits/main/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/commits/main/)
+<br />
+[![Number of GitHub open issues](https://img.shields.io/github/issues-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/issues)
+[![Number of GitHub closed issues](https://img.shields.io/github/issues-closed-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/issues)
+[![Number of GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/pulls)
+[![Number of GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/pulls)
+<br />
+![GitHub License](https://img.shields.io/github/license/SETI/rms-starcat)
+[![Number of GitHub stars](https://img.shields.io/github/stars/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/stargazers)
+![GitHub forks](https://img.shields.io/github/forks/SETI/rms-starcat)
+
+# Introduction
+
+`starcat` is a set of classes for reading and searching star catalogs. Currently NAIF SPICE
+star catalogs, the Yale Bright Star Catalog (YBSC), and UCAC4 are supported.
+
+`starcat` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).
+
+# Installation
+
+The `starcat` module is available via the `rms-starcat` package on PyPI and can be installed with:
+
+```sh
+pip install rms-starcat
+```
+
+# Getting Started
+
+The `starcat` module provides the `StarCatalog` class, which is the superclass for classes
+that handle specific star catalogs. Each star catalog class takes an optional directory
+path to point at the root of the star catalog data; if no directory path is provided,
+the contents of an environment variable is used instead. Each path can be a full URL
+as supported by [`rms-filecache`](https://rms-filecache.readthedocs.io/en/latest/),
+allowing the catalog data to be downloaded (and cached locally) at runtime.
+
+- `SpiceStarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing NAIF SPICE
+    kernels.
+  - Otherwise, the environment variable `SPICE_PATH`, if defined, must contain a `Stars`
+    subdirectory with NAIF SPICE kernels.
+  - Otherwise, the environment variable `OOPS_RESOURCES` must contain a `SPICE/Stars`
+    subdirectory.
+- `YBSCStarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing the file
+    `catalog`.
+  - Otherwise, the environment variable `YBSC_PATH` must point to that directory.
+- `UCAC4StarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing the directory
+    `u4b`.
+  - Otherwise, the environment variable `UCAC4_PATH` must point to that directory.
+
+Each star catalog returns stars as a class that is a subclass of `Star`. Each subclass
+contains the attributes provided by that star catalog, and none are guaranteed to be
+filled in for all stars:
+
+- `SpiceStar`
+- `YBSCStar`
+- `UCAC4Star`
+
+Details of each class are available in the [module documentation](https://rms-starcat.readthedocs.io/en/latest/module.html).
+
+Basic operation is as follows:
+
+```python
+from starcat import YBSCStarCatalog
+import numpy as np
+cat = YBSCStarCatalog()
+ra_vega = 279.2333
+dec_vega = 38.7836
+vega_list = list(cat.find_stars(ra_min=np.radians(ra_vega-0.1),
+                                ra_max=np.radians(ra_vega+0.1),
+                                dec_min=np.radians(dec_vega-0.1),
+                                dec_max=np.radians(dec_vega+0.1)))
+
+assert len(vega_list) == 1
+print(vega_list[0])
+```
+
+yields:
+
+```
+UNIQUE ID 7001 | RA 279.2345833° (18h36m56.300s) | DEC 38.7836111° (+038d47m1.000s)
+VMAG  0.030  | PM RA 259.135 mas/yr  | PM DEC 286.000 mas/yr
+TEMP 10800 | SCLASS A0Va
+Name "3Alp Lyr" | Durch "BD+38 3238" | Draper 172167 | SAO 67174 | FK5 699
+IR 1 Ref NASA | Multiple " " | Aitken 11510 None | Variable "Alp Lyr"
+SCLASS Code   | Galactic LON 67.44 LAT 19.24
+B-V 0.0 | U-B -0.01 | R-I -0.03
+Parallax TRIG 0.1230000 arcsec | RadVel -14.0 km/s V  | RotVel (v sin i) 15.0 km/s
+Double mag diff 10.40 Sep 62.80 arcsec Components AB # 5
+```
+
+# Contributing
+
+Information on contributing to this package can be found in the
+[Contributing Guide](https://github.com/SETI/rms-starcat/blob/main/CONTRIBUTING.md).
+
+# Links
+
+- [Documentation](https://rms-starcat.readthedocs.io)
+- [Repository](https://github.com/SETI/rms-starcat)
+- [Issue tracker](https://github.com/SETI/rms-starcat/issues)
+- [PyPi](https://pypi.org/project/rms-starcat)
+
+# Licensing
+
+This code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-starcat/blob/main/LICENSE).

rms_starcat-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+starcat/__init__.py,sha256=-MdUUzR86srX3uhw-FXBaVYXP5lgnZ82Oyefecm5WuE,749
+starcat/_version.py,sha256=DGJ4pj32xs3_DRJhSzQwCiRNnAQrMgo09USYpyMZsKc,411
+starcat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+starcat/spice.py,sha256=oisWst7g2aH5otRqNvWYt4j_GdDdLbtu2Eoe70iJ1FM,3286
+starcat/starcatalog.py,sha256=01jIdgVsJsKx1AeYpwxMQBhkDKWwGKm4TAuYvp_6iJc,17139
+starcat/ucac4.py,sha256=WW7m7ZN7Lx21UC5hcz8-uQ2mFtiOdFE34LlouymAhnQ,51372
+starcat/ybsc.py,sha256=yNPWH_6DmBJaRuzKDGYowhvb6iQPwx_Q_hPwLgNt0i0,25999
+rms_starcat-1.0.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+rms_starcat-1.0.0.dist-info/METADATA,sha256=qpuD_M2_DkbDWPA3_eAbKG7GiMkZppgkD7oPzOWCiMw,7423
+rms_starcat-1.0.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+rms_starcat-1.0.0.dist-info/top_level.txt,sha256=9_BfZoZasqtspX07JKebH3RqlssKXS1EUX22j-m2D48,8
+rms_starcat-1.0.0.dist-info/RECORD,,

{rms_starcat-0.0.1.dist-info → rms_starcat-1.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.3)
+Generator: setuptools (75.6.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

starcat/__init__.py

@@ -2,11 +2,25 @@
 # starcat/__init__.py
 ################################################################################
 
-from starcat.spice import *
-from starcat.ucac4 import *
-from starcat.ybsc import *
+from starcat.starcatalog import Star, StarCatalog  # noqa: F401
+from starcat.spice import SpiceStar, SpiceStarCatalog  # noqa: F401
+from starcat.ucac4 import UCAC4Star, UCAC4StarCatalog  # noqa: F401
+from starcat.ybsc import YBSCStar, YBSCStarCatalog  # noqa: F401
 
+# Version
 try:
-    from _version import __version__
-except ImportError as err:
+    from ._version import __version__
+except ImportError:
     __version__ = 'Version unspecified'
+
+__all__ = [
+    'Star',
+    'StarCatalog',
+    'SpiceStar',
+    'SpiceStarCatalog',
+    'UCAC4Star',
+    'UCAC4StarCatalog',
+    'YBSCStar',
+    'YBSCStarCatalog',
+    '__version__'
+]

starcat/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.1'
-__version_tuple__ = version_tuple = (0, 0, 1)
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)

starcat/spice.py

@@ -2,96 +2,93 @@
 # starcat/spice.py
 ################################################################################
 
-from __future__ import print_function
-
-try:
-    from starcatalog import *
-except:
-    from .starcatalog import *
-import numpy as np
-import os.path
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Iterator, Optional
+
 import cspyce
+from filecache import FCPath
+
+from .starcatalog import Star, StarCatalog
+
 
 class SpiceStar(Star):
     """A holder for star attributes.
 
-    This class includes attributes unique to the SPICE catalogs."""
+    This class includes attributes unique to stars in SPICE catalogs.
 
-    def __init__(self):
-        # Initialize the standard fields
-        Star.__init__(self)
+    A SpiceStar only supports these attributes: `unique_number`, `ra`, `ra_sigma`, `dec`,
+    `dec_sigma`, `vmag`, `spectral_class`, `temperature`
+    """
 
-        # Initialize the SPICE-specific fields
-        self.spectral_class = None
-        """The spectral class"""
+    def __init__(self) -> None:
+        # Initialize the standard fields
+        super().__init__()
 
 
 class SpiceStarCatalog(StarCatalog):
-    def __init__(self, name):
-        self.filename = os.path.join(os.environ["SPICE_PATH"], "Stars", name+'.bdb')
-        self.catalog = cspyce.stcl01(self.filename)[0]
-        self.debug_level = 0
-
-        # (ra, dec, ra_uncertainty, dec_uncertainty,
-        #  catalog_number, spectral_type, v_magnitude)
-
-    def _find_stars(self, ra_min, ra_max, dec_min, dec_max, **kwargs):
-        """Yield the results for all stars in the RA,DEC range."""
-        vmag_min = kwargs.get('vmag_min', None)
-        vmag_max = kwargs.get('vmag_max', None)
-
-        nstars = cspyce.stcf01(self.catalog, ra_min, ra_max, dec_min, dec_max)
+    def __init__(self,
+                 name: str,
+                 dir: Optional[str | Path | FCPath] = None) -> None:
+        """Create a SpiceStarCatalog.
+
+        Parameters:
+            name: The name of the SPICE catalog without the extension, such as
+                ``hipparcos``, ``ppm``, or ``tycho2``.
+            dir: The path to the star catalog directory (may be a URL). Within
+                this directory should be the kernels for the requested name
+                (``name.dbd`` and ``name.xdb``).
+        """
+
+        super().__init__()
+        if dir is None:
+            try:
+                dir = FCPath(os.environ['SPICE_PATH']) / 'Stars'
+            except KeyError:
+                dir = FCPath(os.environ['OOPS_RESOURCES']) / 'SPICE' / 'Stars'
+            except KeyError:
+                raise RuntimeError(
+                    'SPICE_PATH and OOPS_RESOURCES environment variables not set')
+        else:
+            dir = FCPath(dir)
+        self._filename = dir / f'{name}.bdb'
+        local_path = self._filename.retrieve()
+        self._catalog = cspyce.stcl01(local_path)[0]
+
+    def _find_stars(self,
+                    ra_min: float,
+                    ra_max: float,
+                    dec_min: float,
+                    dec_max: float,
+                    vmag_min: Optional[float] = None,
+                    vmag_max: Optional[float] = None,
+                    full_result: bool = True,
+                    **kwargs: Any) -> Iterator[SpiceStar]:
+
+        nstars = cspyce.stcf01(self._catalog, ra_min, ra_max, dec_min, dec_max)
 
         for i in range(nstars):
             star = SpiceStar()
             result = tuple(cspyce.stcg01(i))
             (star.ra, star.dec, star.ra_sigma, star.dec_sigma,
              star.unique_number, star.spectral_class, star.vmag) = result
-            if vmag_min is not None and star.vmag < vmag_min:
-                if self.debug_level:
-                    print('SKIPPED VMAG', star.vmag)
-                continue
-            if vmag_max is not None and star.vmag > vmag_max:
-                if self.debug_level:
-                    print('SKIPPED VMAG', star.vmag)
-                continue
-
-            star.temperature = self.temperature_from_sclass(star.spectral_class)
-            if self.debug_level:
-                print('OK!')
-            yield star
-
-
-
-#===============================================================================
-# UNIT TESTS
-#===============================================================================
-
-import unittest
-
-class Test_SpiceStarCatalog(unittest.TestCase):
-
-    def runTest(self):
-        cat = SpiceStarCatalog('hipparcos')
-
-        num_all = cat.count_stars()
-        self.assertEqual(num_all, 117955)
-
-        num_vmag_lim = cat.count_stars(vmag_max=10)
-        self.assertGreater(num_all, num_vmag_lim)
-
-        # Compare slicing directions
-        num_dec = 0
-        for idec in range(20):
-            num_dec += cat.count_stars(dec_min=0.2*idec*RPD,
-                                       dec_max=0.2*(idec+1)*RPD,
-                                       ra_min=60*RPD, ra_max=70*RPD)
-        num_ra = 0
-        for ira in range(10):
-            num_ra += cat.count_stars(dec_min=0., dec_max=4.*RPD,
-                                      ra_min=(ira+60)*RPD, ra_max=((ira+1)+60)*RPD)
-        self.assertEqual(num_dec, num_ra)
+            if star.vmag is not None:
+                if vmag_min is not None and star.vmag < vmag_min:
+                    if self.debug_level:
+                        print('SKIPPED VMAG', star.vmag)
+                    continue
+                if vmag_max is not None and star.vmag > vmag_max:
+                    if self.debug_level:
+                        print('SKIPPED VMAG', star.vmag)
+                    continue
+
+            if full_result:
+                star.temperature = Star.temperature_from_sclass(star.spectral_class)
 
+            if self.debug_level:
+                print(star)
+                print('-' * 80)
 
-if __name__ == '__main__':
-    unittest.main(verbosity=2)
+            yield star