sparclclient 1.2.8b4__py2.py3-none-any.whl → 1.3.0b1__py2.py3-none-any.whl

sparcl/Results.py

@@ -9,6 +9,7 @@ from sparcl.utils import _AttrDict
 
 # from sparcl.gather_2d import bin_spectra_records
 import sparcl.exceptions as ex
+import sparcl.specutils as su
 from warnings import warn
 import re
 
@@ -139,9 +140,7 @@ class Results(UserList):
 
         Returns:
             reordered (:class:`~sparcl.Results.Retrieved`): Contains header and
-                                                            reordered records.
-            # none_idx (:obj:`list`): List of indices where record is None.
-
+            reordered records.
         """
         if len(ids_og) <= 0:
             msg = (
@@ -198,6 +197,14 @@ class Results(UserList):
                 warn(msg, stacklevel=2)
         return Results(reordered, client=self.client)
 
+    def to_specutils(self):
+        """Convert results to a `specutils` object.
+
+        Returns:
+            to_specutils (:class:`~specutils.Spectrum`): a `specutils` object.
+        """
+        return su.to_specutils(self)
+
 
 # For results of retrieve()
 class Retrieved(Results):
@@ -209,7 +216,6 @@ class Retrieved(Results):
     def __repr__(self):
         return f"Retrieved Results: {len(self.recs)} records"
 
-
 #!    def bin_spectra(self):
 #!        """Align flux from all records by common wavelength bin.
 #!

sparcl/__init__.py

@@ -37,4 +37,5 @@ __all__ = ["client", "align_records"]
 #__version__ = "1.2.5"
 #__version__ = "1.2.6"
 #__version__ = "1.2.7"
-__version__ = "1.2.8b4"
+#__version__ = "1.2.8"
+__version__ = "1.3.0b1"

sparcl/client.py

@@ -267,11 +267,12 @@ class SparclClient:  # was SparclApi()
 
     def token_expired(self, renew=False):
         """
-        POST http://localhost:8050/sparc/renew_token/
-        Content-Type: application/json
-        {
-          "refresh_token": "..."
-        }
+        ::
+            POST http://localhost:8050/sparc/renew_token/
+            Content-Type: application/json
+            {
+            "refresh_token": "..."
+            }
 
         Returns an 'access' token
         """
@@ -308,9 +309,8 @@ class SparclClient:  # was SparclApi()
             None.
 
         Example:
-            >>>
-            >> client = SparclClient(announcement=False)
-            >> client.login('test_user@noirlab.edu', 'testpw')
+            >>> client = SparclClient(announcement=False)
+            >>> client.login('test_user@noirlab.edu', 'pw') # doctest: +SKIP
             Logged in successfully with email='test_user@noirlab.edu'
         """
 
@@ -1021,11 +1021,9 @@ class SparclClient:  # was SparclApi()
 
         Example:
             >>> client = SparclClient(announcement=False)
-            >>> sids = [5840097619402313728, -8985592895187431424]
+            >>> sids = [4753625089450465280, 1254253099313293312]
             >>> inc = ['specid', 'flux', 'wavelength', 'model']
             >>> ret = client.retrieve_by_specid(specid_list=sids, include=inc)
-            >>> len(ret.records[0].wavelength)
-            4617
 
         """
         #!specid_list = list(specid_list)

sparcl/specutils.py

@@ -0,0 +1,311 @@
+"""Functions for converting SPARCL results to specutils objects.
+"""
+import warnings
+import numpy as np
+try:
+    # specutils >= 2.0
+    from specutils import Spectrum
+except ImportError:
+    from specutils import Spectrum1D as Spectrum
+from specutils import SpectrumCollection, SpectrumList
+from astropy.nddata import InverseVariance
+import astropy.units as u
+
+def _validate_records(records, r0, collection):
+    """Validate that records can be converted to Spectrum.
+
+    Parameters
+    ----------
+    records : list of dict
+        All records to validate.
+    r0 : dict
+        First record, used as reference for validation.
+    collection: bool
+        If ``True``, attempt to convert to a
+        :class:`~specutils.SpectrumCollection` instead.
+
+    Raises
+    ------
+    ValueError
+        If records lack 'wavelength' attribute.
+        If records have different data releases.
+        If wavelength array lengths differ (suggests using SpectrumList).
+        If wavelength pixel values differ and collection=False
+        (suggests using SpectrumCollection).
+
+    Warnings
+    --------
+    UserWarning
+        If records come from different data releases.
+    """
+
+    # Check if the first record has wavelength data
+    if 'wavelength' not in r0:
+        raise ValueError("Results do not have a wavelength attribute. "
+                         "Conversion is not possible.")
+
+    # Check if all records come from the same data release
+    if not all([r.data_release == r0.data_release for r in records]):
+        warnings.warn("Results are not all from the same data release, "
+                      "conversion may not be possible.", UserWarning)
+
+    # Check if all records have the same number of wavelength points
+    if not all([len(r.wavelength) == len(r0.wavelength) for r in records]):
+        raise ValueError("Results do not have the same wavelength solution. "
+                         "Consider using .to_SpectrumList instead.")
+
+    # If not creating a SpectrumCollection, check that wavelength values
+    # are identical across all records
+    if not collection and not all([(r.wavelength == r0.wavelength).all()
+                                   for r in records]):
+        raise ValueError("Results do not have the same wavelength pixels. "
+                         "Consider using SpectrumCollection instead.")
+
+def _extract_record_data(records, flux, uncertainty, mask, model, redshift,
+                         meta, spectral_axis, has_model, has_redshift,
+                         collection, single_record):
+    """Extract all data from records into arrays. This function modifies
+    arrays in-place rather than returning values.
+
+    Parameters
+    ----------
+    records: list of dict
+        Records containing flux, ivar, mask, wavelength, and optional
+        model/redshift.
+    flux : np.ndarray
+        Pre-allocated array for flux values. Shape: (n_pixels,) if
+        single_record, else (n_records, n_pixels).
+    uncertainty : np.ndarray
+        Pre-allocated array for inverse variance.
+    mask : np.ndarray
+        Pre-allocated array for data quality masks.
+    model : np.ndarray or None
+        Pre-allocated array for model values if has_model=True.
+    redshift : list
+        Empty list to populate with redshift values.
+    meta : dict
+        Empty dict to populate with metadata.
+    spectral_axis : np.ndarray
+        For collections, pre-allocated 2D array to store wavelength grids.
+        For non-collections, this is just r0.wavelength (not modified).
+    has_model : bool
+        Whether records contain 'model' attribute.
+    has_redshift : bool
+        Whether records contain 'redshift' attribute.
+    collection : bool
+        If True, stores wavelength arrays for each record in spectral_axis.
+    single_record : bool
+        If True, treats arrays as 1D. If False, treats as 2D with row per
+        record.
+
+    Returns
+    -------
+    None
+        All outputs are written to the input arrays/containers in-place.
+    """
+    for k, record in enumerate(records):
+        if single_record:
+            # For single record, assign directly (1D)
+            flux[:] = record.flux
+            uncertainty[:] = record.ivar
+            mask[:] = record.mask
+            if has_model:
+                model[:] = record.model
+        else:
+            # For multiple records, assign to row (2D)
+            flux[k, :] = record.flux
+            uncertainty[k, :] = record.ivar
+            mask[k, :] = record.mask
+            if has_model:
+                model[k, :] = record.model
+
+        # Store redshift values if available
+        if has_redshift:
+            redshift.append(record.redshift)
+
+        # For collections, each record can have its own wavelength grid
+        if collection:
+            spectral_axis[k, :] = record.wavelength
+
+        # Extract all additional metadata attributes
+        for attribute, value in record.items():
+            if attribute not in ('flux', 'ivar', 'mask', 'model', 'redshift',
+                                 'wavelength'):
+                if single_record:
+                    # For single record, store metadata values as scalars
+                    meta[attribute] = value
+                else:
+                    # For multiple records, accumulate metadata values into
+                    # lists (creates list on first encounter, then appends)
+                    meta.setdefault(attribute, []).append(value)
+
+def to_Spectrum(results, *, collection=False):
+    """Convert `results` to :class:`specutils.Spectrum`.
+
+    Parameters
+    ----------
+    results : :class:`sparcl.Results.Retrieved`
+        Retrieved results, or a single record from a set of results.
+    collection : bool, optional
+        If ``True``, attempt to convert to a
+        :class:`~specutils.SpectrumCollection` instead.
+
+    Returns
+    -------
+    :class:`~specutils.Spectrum` or :class:`~specutils.SpectrumCollection`
+        The requested object.
+
+    Raises
+    ------
+    ValueError
+        If `results` can't be converted to a :class:`~specutils.Spectrum`
+        object in a valid way. For example, if some of the spectra have a
+        different wavelength solution.
+    """
+    # Prepare records
+    if isinstance(results, dict):
+        records = [results]
+        r0 = results
+    else:
+        try:
+            records = results.records
+            if len(records) == 0:
+                raise ValueError("No records found in results. Cannot "
+                                 "convert empty results to Spectrum.")
+            r0 = results.records[0]
+        except (IndexError, AttributeError) as e:
+            raise ValueError("No records found in results. Cannot "
+                             "convert empty results to Spectrum.") from e
+
+    # Validate
+    _validate_records(records, r0, collection)
+
+    # Determine which optional data components exist in records
+    has_redshift = 'redshift' in r0
+    has_model = 'model' in r0
+    n_pixels = r0.flux.shape[0]
+    single_record = len(records) == 1
+
+    # Set flux shape based on number of records
+    if single_record:
+        flux_shape = (n_pixels,)
+    else:
+        flux_shape = (len(records), n_pixels)
+
+    # Build spectral axis
+    if collection:
+        spectral_axis = np.empty((len(records), r0.wavelength.shape[0]),
+                                 dtype=r0.wavelength.dtype)
+    else:
+        spectral_axis = r0.wavelength
+
+    # Initialize arrays
+    flux = np.empty(flux_shape, dtype=r0.flux.dtype)
+    uncertainty = np.empty(flux_shape, dtype=r0.ivar.dtype)
+    mask = np.empty(flux_shape, dtype=r0.mask.dtype)
+    model = np.empty(flux_shape, dtype=r0.model.dtype) if has_model else None
+    redshift = []
+    meta = {}
+
+    # Populate arrays by iterating through records
+    _extract_record_data(records, flux, uncertainty, mask, model, redshift,
+                         meta, spectral_axis, has_model, has_redshift,
+                         collection, single_record)
+
+    # Convert redshift list to numpy array if exists
+    if has_redshift:
+        redshift = np.array(redshift)
+        if single_record and len(redshift) == 1:
+            # Convert to scalar if single record
+            redshift = redshift[0]
+    else:
+        redshift = None
+
+    # Add model to metadata if exists
+    if has_model:
+        meta['model'] = model
+
+    # Prepare arguments common to both Spectrum and SpectrumCollection
+    common_args = {
+        'flux': flux * 10**-17 * u.Unit('erg cm-2 s-1 AA-1'),
+        'spectral_axis': spectral_axis * u.AA,
+        'uncertainty': InverseVariance(uncertainty),
+        'mask': mask,
+        'meta': meta}
+
+    if collection:
+        return SpectrumCollection(**common_args)
+
+    return Spectrum(**common_args, redshift=redshift)
+
+def to_SpectrumList(results):
+    """Convert `results` to :class:`specutils.SpectrumList`.
+
+    Parameters
+    ----------
+    results : :class:`sparcl.Results.Retrieved`
+        Retrieved results.
+
+    Returns
+    -------
+    :class:`~specutils.SpectrumList`
+        The requested object.
+    """
+    s = SpectrumList()
+    if isinstance(results, dict):
+        records = [results]
+    else:
+        records = results.records
+    for r in records:
+        if 'redshift' in r:
+            redshift = r.redshift
+        else:
+            redshift = None
+        meta = dict()
+        for attribute in r:
+            if attribute not in ('flux', 'wavelength', 'ivar',
+                                 'redshift', 'mask'):
+                meta[attribute] = r[attribute]
+        s1 = Spectrum(flux=r.flux*10**-17*u.Unit('erg cm-2 s-1 AA-1'),
+                      spectral_axis=r.wavelength*u.AA,
+                      uncertainty=InverseVariance(r.ivar),
+                      redshift=redshift,
+                      mask=r.mask,
+                      meta=meta)
+        s.append(s1)
+    return s
+
+def to_specutils(results):
+    """Convert `results` to a specutils object.
+
+    Parameters
+    ----------
+    results : :class:`sparcl.Results.Retrieved`
+        Retrieved results.
+
+    Returns
+    -------
+    :class:`~specutils.Spectrum` or :class:`~specutils.SpectrumCollection`
+    or :class:`~specutils.SpectrumList`
+        The most natural conversion to a specutils object.
+
+    Raises
+    ------
+    ValueError
+        If no valid conversion can be performed.
+    """
+    try:
+        # Try standard Spectrum conversion first
+        s = to_Spectrum(results)
+    except ValueError as ve:
+        # Check the error message to determine appropriate alternative
+        if 'SpectrumList' in str(ve):
+            # Different wavelength array lengths use SpectrumList
+            s = to_SpectrumList(results)
+        elif 'SpectrumCollection' in str(ve):
+            # Same wavelength length but diff pixels use SpectrumCollection
+            s = to_Spectrum(results, collection=True)
+        else:
+            raise ValueError("Could not find a valid conversion to "
+                             "specutils objects!")
+    return s

{sparclclient-1.2.8b4.dist-info → sparclclient-1.3.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sparclclient
-Version: 1.2.8b4
+Version: 1.3.0b1
 Summary: A client for getting spectra and meta-data from NOIRLab.
 Author-email: "S. Pothier" <datalab-spectro@noirlab.edu>
 Description-Content-Type: text/markdown

{sparclclient-1.2.8b4.dist-info → sparclclient-1.3.0b1.dist-info}/RECORD

@@ -1,12 +1,13 @@
-sparcl/Results.py,sha256=vnACjm8sp7MrsJ_5LTuKMuyRWqeBJxOxQM302cHmAlk,9159
-sparcl/__init__.py,sha256=OAZ72-b6xfmKNbYnM_CY6m8Zc7B9hz_PThiTsQyGla8,1170
-sparcl/client.py,sha256=C9vYeHqZvl0lzVw1BRJeGCv5zk2W2XH1aLsFtBYeYk4,40013
+sparcl/Results.py,sha256=IlnYZrDddARv3PJ3HPcyHJwTdMroqGdw-eaSrbmAA64,9290
+sparcl/__init__.py,sha256=5iJtQlT6iymXB7qJZazu4MQjt9jjci3NEArMicoTizY,1193
+sparcl/client.py,sha256=OAY9F1KbyVc5kos7twqOFnQcGtoqraNG6-CJWqmVE3o,39976
 sparcl/conf.py,sha256=GFNDelaiVIAkjNjvFlG7HAlPpU39nqZmTPohQGmOcgI,928
 sparcl/exceptions.py,sha256=sznmOMGENHvxutSXlRVWqi87bR2Qiebka7LyR3mAII0,4244
 sparcl/fields.py,sha256=NZUBqDidpbXfeX5F4b306F323xZY2CRIx8eVv-HWTVU,5127
 sparcl/gather_2d.py,sha256=YTFVQl38dRZjUu0AEUFVZtQm7zC8mU3LVvUTDGxp6u8,8722
 sparcl/resample_spectra.py,sha256=nk5HiyaGF-b9SiTmIC9yJBbYX4VYsiLFHyW186bPs2s,1310
 sparcl/sparc.ini,sha256=q_wjo9DLnCYRxWFMl0CtMYp4DD1AXfEcK6BP6cmncwo,329
+sparcl/specutils.py,sha256=9rp0P2LRsp5UC5ODNwtO2vy0cigCiVtdMtogDb5gDb0,10970
 sparcl/type_conversion.py,sha256=QmXNX9j_7QHnBu83f2ZBfREoql9wuo98ZbhQtSjRRWc,12965
 sparcl/unsupported.py,sha256=bfkkZa-PuqwN-Bqo3vCIrLupbWMDTCiTHPMNfXnqmMc,1848
 sparcl/utils.py,sha256=pDAk9roe7ezfVohnKcLMxFjjXHkp7EQLbgVNe5sSTrk,6259
@@ -15,7 +16,7 @@ sparcl/benchmarks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU
 sparcl/benchmarks/benchmarks.py,sha256=OmlSdnAPLmcvGXsr-HzGyfAAcnoqlO0JQ4EIA7JGhZc,9424
 sparcl/benchmarks/sparcl_benchmarking.ipynb,sha256=gwof2hqM9Qb49qzRX-mky7WNqXZCMSB7ry8bX8dImxc,17559
 sparcl/notebooks/sparcl-examples.ipynb,sha256=gEwMKI1x7A1YsVeCsQn1QoMO0ZuIhMUAu3qedTiQ7hM,169268
-sparclclient-1.2.8b4.dist-info/LICENSE,sha256=y10EluGMCzGs9X4oYCYyix3l6u-lawB_vlGR8qe442Q,1576
-sparclclient-1.2.8b4.dist-info/WHEEL,sha256=ssQ84EZ5gH1pCOujd3iW7HClo_O_aDaClUbX4B8bjKY,100
-sparclclient-1.2.8b4.dist-info/METADATA,sha256=Oyk3k7Xy_q_pOiHy4kNfgf5uK8nJDRyVM1R5txgzaVs,677
-sparclclient-1.2.8b4.dist-info/RECORD,,
+sparclclient-1.3.0b1.dist-info/LICENSE,sha256=y10EluGMCzGs9X4oYCYyix3l6u-lawB_vlGR8qe442Q,1576
+sparclclient-1.3.0b1.dist-info/WHEEL,sha256=ssQ84EZ5gH1pCOujd3iW7HClo_O_aDaClUbX4B8bjKY,100
+sparclclient-1.3.0b1.dist-info/METADATA,sha256=vANPyhFvOUZzx-yMf4NHsdLOmg_qvxqTZtr_BLeqapU,677
+sparclclient-1.3.0b1.dist-info/RECORD,,