asteroid_spinprops 0.2.31__py3-none-any.whl → 1.0.0__py3-none-any.whl

asteroid_spinprops/ssolib/utils.py

@@ -1,15 +1,21 @@
 import numpy as np
-import pandas as pd
-import asteroid_spinprops.ssolib.ssptools as ssptools
-import os
-
-import pickle
-import requests
-import io
 import astropy.constants as const
 
 
 def is_sorted(a):
+    """
+    Check whether a 1D array is sorted in non-decreasing order.
+
+    Parameters
+    ----------
+    a : array_like
+        Input array to test.
+
+    Returns
+    -------
+    bool
+        True if `a` is sorted in non-decreasing order, False otherwise.
+    """
     return np.all(a[:-1] <= a[1:])
 
 
@@ -32,42 +38,6 @@ def sigma_condition_func(data):
     return (data > mean_val - 3 * std_val) & (data < mean_val + 3 * std_val)
 
 
-def get_atlas_ephem(pdf, name, path_to_cached_ephems=None):
-    # TODO: include midtime obs timeshift
-    """
-    Get the ephemerides for a SSO from the ATLAS catalogue
-
-    Parameters
-    -----------------------------
-    name: str
-        Name of the object
-    jd: float or list
-        Julian Date(s) of the ephemerides requested
-    pdf: pd.DataFrame
-        Dataframe containing the name and the JDs of the observations of the object
-    path_to_cached_ephems: str
-        Path to already computed ephemerids
-
-    Returns
-    -----------------------------
-    ephem: pd.DataFrame
-        Ephemerides for the provided JDs
-    """
-
-    namecond = pdf["name"] == name
-    jd = pdf[namecond]["cjd"].tolist()[0].tolist()
-    if path_to_cached_ephems is not None:
-        ephem_file = os.path.join(path_to_cached_ephems, name)
-        if os.path.exists(ephem_file):
-            eph = pd.read_csv(ephem_file)
-        else:
-            eph = ssptools.ephemcc(name, jd, tcoor=5, observer="500")
-            eph.to_csv(path_to_cached_ephems + "/" + name)
-    else:
-        eph = ssptools.ephemcc(name, jd, tcoor=5, observer="500")
-    return eph
-
-
 def find_nearest(array, value):
     """
     Find the nearest value of an array to a given value.
@@ -104,31 +74,6 @@ def flatten_list(xss):
     return np.array(flat_list)
 
 
-def c2rd(x, y, z):
-    """
-    Geocentric cartesian to RA/DEC
-
-    Parameters
-    -----------------------------
-    x, y, z : float/np.array
-        x, y, z coordinates
-
-    Returns
-    -----------------------------
-    ra, dec : float/np.array
-        RA & DEC in degrees from x, y, z
-    """
-
-    ra_rad = np.arctan2(y, x)
-    ra = np.degrees(ra_rad) % 360
-
-    r = np.sqrt(x**2 + y**2 + z**2)
-    dec_rad = np.arcsin(z / r)
-    dec = np.degrees(dec_rad)
-
-    return ra, dec
-
-
 def calculate_reduced_magnitude(magnitude, D_observer, D_sun):
     """
     Calculate reduced magnitude
@@ -149,30 +94,6 @@ def calculate_reduced_magnitude(magnitude, D_observer, D_sun):
     return magnitude - 5 * np.log10(D_observer * D_sun)
 
 
-def find_sso_in_pqdict(sso_name, pqdict):
-    """
-    Search for a specific SSO name within a dictionary containing names of parquet files as keys
-    and lists of sso names as values.
-
-    Parameters
-    -----------------------------
-    sso_name : str
-        The name of the solar system object to search for.
-    pqdict : dict
-        A dictionary where keys are filenames,
-        and values are lists of SSO names contained in each pqfile.
-
-    Returns
-    -----------------------------
-    pqfile : str or None
-        The name of the pqfile that contains the specified SSO
-    """
-
-    for pqfile in list(pqdict.keys()):
-        if sso_name in pqdict[pqfile]:
-            return pqfile
-
-
 def sort_by_cjd(data):
     """
     Function to sort data containing a `cjd` column by this column.
@@ -196,72 +117,6 @@ def sort_by_cjd(data):
     return data
 
 
-# sns.set_context('talk')
-def sexa_to_deg(ra_list, dec_list):
-    """
-    Convert 2 lists of RA and DEC angles from sexagesimal format to degrees.
-
-    Parameters
-    ----------
-    ra_list : list
-        List of RA angles.
-    dec_list : list
-        List of Dec angles
-
-    Returns
-    -------
-    ra_degrees: np.array
-        np.array of RA angles in degrees
-    dec_degrees
-        np.array of DEC angles in degrees
-    """
-    ra_array = np.asarray(ra_list, dtype=str)
-    dec_array = np.asarray(dec_list, dtype=str)
-
-    ra_signs = np.where(np.char.startswith(ra_array, "-"), -1, 1)
-    dec_signs = np.where(np.char.startswith(dec_array, "-"), -1, 1)
-
-    ra_array = np.char.lstrip(ra_array, "+-")
-    dec_array = np.char.lstrip(dec_array, "+-")
-
-    ra_h, ra_m, ra_s = np.array([s.split(":") for s in ra_array], dtype=float).T
-    dec_d, dec_m, dec_s = np.array([s.split(":") for s in dec_array], dtype=float).T
-
-    ra_degrees = ra_signs * (ra_h * 15 + ra_m * 15 / 60 + ra_s * 15 / 3600)
-    dec_degrees = dec_signs * (dec_d + dec_m / 60 + dec_s / 3600)
-
-    return ra_degrees, dec_degrees
-
-
-def get_obejct_from_fink(name):
-    """
-    Queries FINK portal for SSO
-
-    Parameters
-    -----------
-    name: str
-        Name of the object
-
-    Returns
-    --------
-    dframe: pd.DataFrame
-        Contains all necessary values for sHG1G2 fit (and previous models)
-    """
-    r = requests.post(
-        "https://api.fink-portal.org/api/v1/sso",
-        json={
-            "n_or_d": name,
-            "withEphem": False,
-            "withResiduals": True,
-            "output-format": "json",
-        },
-    )
-    dframe = pd.read_json(
-        io.BytesIO(r.content),
-    )
-    return dframe
-
-
 def get_apparition_indices(dates, threshold=100):
     """
     Identify indices where there is a significant time gap (>threshold days).
@@ -281,30 +136,23 @@ def get_apparition_indices(dates, threshold=100):
     return np.concatenate(([0], np.where(np.diff(dates) > threshold)[0], [len(dates)]))
 
 
-def pq_folder_to_dictionary(path, save=False):
-    sso_in_pq = {}
-    for pq_file in os.listdir(path):
-        if pq_file.__contains__(".parquet"):
-            file_path = os.path.join(path, pq_file)
-            sso_names = pd.read_parquet(file_path)["name"]
-            sso_in_pq[pq_file] = [n for n in sso_names]
-    if save is True:
-        with open("ssoname_keys.pkl", "wb") as f:
-            pickle.dump(sso_in_pq, f)
-    return sso_in_pq
-
-
-def calc_radec_for_epoch(data, epoch):
-    eph = ssptools.ephemcc(
-        data["name"].values[0], epoch.tolist(), tcoor=1, observer="500"
-    )
-    ra, dec = sexa_to_deg(eph["RA"].values, eph["DEC"].values)
-    ra, dec = np.radians(ra), np.radians(dec)
-    return ra, dec
+def flip_spin(ra0, dec0):
+    """
+    Compute the antipodal (spin-flip) direction for a given RA/Dec.
 
+    Parameters
+    ----------
+    ra0 : float or array_like
+        Right ascension in degrees.
+    dec0 : float or array_like
+        Declination in degrees.
 
-def flip_spin(ra0, dec0):
-    # degree in degree out
+    Returns
+    -------
+    tuple of float or array_like
+        `(ra_alt, dec_alt)` giving the antipodal right ascension and
+        declination in degrees.
+    """
     ra0 = np.radians(ra0)
     dec0 = np.radians(dec0)
     ra_alt = (ra0 + np.pi) % (2 * np.pi)
@@ -313,7 +161,26 @@ def flip_spin(ra0, dec0):
 
 
 def calc_atan_parameter(ra, dec, ra0, dec0):
-    # degree in
+    """
+    Compute the angular parameter used in great-circle or pole-separation geometry.
+
+    Parameters
+    ----------
+    ra : float or array_like
+        Right ascension of the target point, in degrees.
+    dec : float or array_like
+        Declination of the target point, in degrees.
+    ra0 : float or array_like
+        Reference right ascension, in degrees.
+    dec0 : float or array_like
+        Reference declination, in degrees.
+
+    Returns
+    -------
+    float or array_like
+        The atan2-based angle (in radians) describing the orientation of
+        the target point relative to the reference direction.
+    """
     ra, dec, ra0, dec0 = (
         np.radians(ra),
         np.radians(dec),
@@ -326,7 +193,8 @@ def calc_atan_parameter(ra, dec, ra0, dec0):
 
 
 def compute_ltc(jd, d_obs, filt=None):
-    """Compute the time with light travel corrected
+    """
+    Compute the time with light travel corrected
 
     Parameters
     ----------
@@ -347,6 +215,23 @@ def compute_ltc(jd, d_obs, filt=None):
 
 
 def angle_after_one_synodic_period(angle, synodic_period, rate):
+    """
+    Propagate an angle forward by one synodic period given a drift rate.
+
+    Parameters
+    ----------
+    angle : float or array_like
+        Initial angle in degrees.
+    synodic_period : float
+        Synodic period in days.
+    rate : float or array_like
+        Angular drift rate in arcseconds per minute.
+
+    Returns
+    -------
+    float or array_like
+        Angle after one synodic period, in degrees.
+    """
     angle_t1 = (
         angle + synodic_period * (60 * 24) / 3600 * rate
     )  # dRA in arcsec/min, period in days, ra_t0|1 in degrees
@@ -354,6 +239,45 @@ def angle_after_one_synodic_period(angle, synodic_period, rate):
 
 
 def estimate_sidereal_period(data, model_parameters, synodic_period):
+    """
+    Estimate the sidereal period of an object from its astrometric drift
+    over one synodic period, using both the nominal and spin-flipped
+    pole solutions.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        Table containing at least the columns:
+        - 'cjd' : float
+            Corrected Julian dates.
+        - 'ra' : float
+            Right ascension in degrees.
+        - 'dec' : float
+            Declination in degrees.
+        - 'dRA' : float
+            RA drift rate in arcseconds per minute.
+        - 'dDec' : float
+            Dec drift rate in arcseconds per minute.
+    model_parameters : dict
+        Dictionary containing pole coordinates:
+        - 'alpha0' : float
+            Reference right ascension (degrees).
+        - 'delta0' : float
+            Reference declination (degrees).
+    synodic_period : float
+        Synodic period in days.
+
+    Returns
+    -------
+    tuple
+        (sidereal_period, sidereal_period_alt, epoch1) where:
+        - sidereal_period : float
+            Sidereal period corresponding to the nominal pole.
+        - sidereal_period_alt : float
+            Sidereal period corresponding to the antipodal pole.
+        - epoch1 : float
+            Epoch of the first observation (CJD).
+    """
     ra0 = model_parameters["alpha0"]
     dec0 = model_parameters["delta0"]
 
@@ -387,40 +311,56 @@ def estimate_sidereal_period(data, model_parameters, synodic_period):
     return sidereal_period, sidereal_period_alt, epoch1
 
 
-def read_clean_data(
-    sso_name,
-    pq_dictionary,
-    clean_data_path,
-    rejected_data_path=None,
-    return_rejects=True,
-):
-    file_name = find_sso_in_pqdict(sso_name=sso_name, pqdict=pq_dictionary)
-    file_path = os.path.join(clean_data_path, file_name)
-
-    pdf = pd.read_parquet(file_path)
-
-    cond_name = pdf["name"] == sso_name
-    clean_data = pdf[cond_name].copy().reset_index(drop=True)
-    # TODO: is this a good idea? probably not...
-    if return_rejects is True:
-        rejects = pd.read_pickle(os.path.join(rejected_data_path, sso_name + ".pkl"))
-
-        return clean_data, rejects
-    else:
-        return clean_data
+def oblateness(a_b, a_c):
+    """
+    Compute a simple oblateness proxy from axis ratios.
 
+    Parameters
+    ----------
+    a_b : float or array_like
+        Intermediate-to-long axis ratio (b/a).
+    a_c : float or array_like
+        Short-to-long axis ratio (c/a).
 
-def oblateness(a_b, a_c):
+    Returns
+    -------
+    float or array_like
+        Oblateness measure defined as 0.5 * (a_b / a_c + 1 / a_b).
+    """
     return 1 / 2 * a_b / a_c + 1 / 2 * 1 / a_b
 
 
 def wrap_longitude(long):
-    """Wrap RA to [0, 360)."""
+    """
+    Wrap a longitude angle into the range [0, 360).
+
+    Parameters
+    ----------
+    long : float or array_like
+        Input longitude in degrees.
+
+    Returns
+    -------
+    float or array_like
+        Longitude wrapped to the interval [0, 360).
+    """
     return long % 360
 
 
 def wrap_latitude(lat):
-    """Wrap Dec to [-90, 90] by folding over the poles."""
+    """
+    Wrap a latitude angle into the range [-90, 90] by folding across the poles.
+
+    Parameters
+    ----------
+    lat : float or array_like
+        Input latitude in degrees.
+
+    Returns
+    -------
+    float or array_like
+        Latitude wrapped to the interval [-90, 90].
+    """
     m = (lat + 90) % 360  # shift so -90 maps to 0
     if m > 180:
         m = 360 - m
@@ -429,12 +369,25 @@ def wrap_latitude(lat):
 
 def generate_initial_points(ra, dec, dec_shift=45):
     """
-    Generate 18 initial (RA, Dec) points
+    Generate a set of 12 initial (RA, Dec) sampling points by combining
+    spin-flipped poles, RA sweeps, and latitude shifts.
+
+    Parameters
+    ----------
+    ra : float
+        Base right ascension in degrees.
+    dec : float
+        Base declination in degrees.
+    dec_shift : float, optional
+        Latitude shift (degrees) applied when generating the secondary
+        sets of points. Defaults to 45 degrees.
 
-    Parameters:
-    ra (float): base RA in degrees
-    dec (float): base Dec in degrees
-    dec_shifts (tuple): the two Dec shifts (in degrees) to try in step 2
+    Returns
+    -------
+    tuple of list
+        (ra_list, dec_list), where each list contains 18 elements
+        representing the generated right ascensions and declinations
+        in degrees.
     """
     if np.abs(2 * dec - dec_shift) < 10:
         dec_shift += 20

asteroid_spinprops-1.0.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: asteroid_spinprops
+Version: 1.0.0
+Summary: Collection of tools used for fitting sHG1G2 and SOCCA photometric models to sparse asteroid photometry
+License: MIT
+Author: Odysseas
+Author-email: odysseas.xenos@proton.me
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: astropy (==7.0.0)
+Requires-Dist: fink-utils (==0.43.0)
+Requires-Dist: nifty-ls (==1.1.0)
+Requires-Dist: pandas (==2.3.3)
+Requires-Dist: scipy (==1.16.2)
+Requires-Dist: tqdm (==4.67.1)
+Project-URL: Homepage, https://gitlab.com/odysseas_xenos/asteroid-spinprops
+Project-URL: Repository, https://gitlab.com/odysseas_xenos/asteroid-spinprops
+Description-Content-Type: text/markdown
+
+# asteroid-spinprops
+
+## Overview
+**asteroid-spinprops** is a Python package providing tools to fit SHG1G2 and SOCCA photometric models to sparse asteroid photometry.  
+It supports multiband modeling, residual analysis and shape, period and pole orientation estimation for small solar system objects.
+
+---
+
+## Installation
+Install the package via pip:
+
+```bash
+pip install asteroid_spinprops
+```
+
+## Quick Start
+```python
+import numpy as np
+import pandas as pd
+from asteroid_spinprops.ssolib import dataprep, periodest, modelfit
+
+# Suppose `pdf` is your initial asteroid DataFrame 
+# Ensure all columns are converted to the required single row format.
+pdf_s = pd.DataFrame({col: [np.array(pdf[col])] for col in pdf.columns})
+
+# Convert filter IDs to numeric
+unique_vals, inv = np.unique(pdf_s["cfid"].values[0], return_inverse=True)
+numeric_filter = inv + 1
+pdf_s["cfid"].values[0] = numeric_filter
+
+# --- Data cleaning and filtering ---
+clean_data, errorbar_rejects = dataprep.errorbar_filtering(data=pdf_s, mlimit=0.7928)
+clean_data, projection_rejects = dataprep.projection_filtering(data=clean_data)
+clean_data, iterative_rejects = dataprep.iterative_filtering(data=clean_data)
+
+# --- Fit SHG1G2 model ---
+shg1g2_params = modelfit.get_fit_params(
+    data=clean_data,
+    flavor="SHG1G2",
+)
+
+# Compute residuals for period analysis
+residuals_dataframe = modelfit.make_residuals_df(
+    clean_data, model_parameters=shg1g2_params
+)
+
+# --- Estimate rotation period ---
+p_in, k_val, p_rms, signal_peak, window_peak = periodest.get_multiband_period_estimate(
+    residuals_dataframe,
+    k_free=True,
+)
+
+# Assess period robustness via bootstrap resampling
+_, Nbs = periodest.perform_residual_resampling(
+    resid_df=residuals_dataframe,
+    p_min=0.03,
+    p_max=2,
+    k=int(k_val)
+)
+
+# --- Fit SSHG1G2 (spin + multiband) model ---
+SOCCA_params = modelfit.get_fit_params(
+    data=clean_data,
+    flavor="SSHG1G2",
+    shg1g2_constrained=True,
+    blind_scan=True,
+    period_in=p_in,
+)
+```
+
+## Models
+Photometric models from Carry et al.(2024) {2024A&A...687A..38C}
+and https://github.com/astrolabsoftware
+
+## Project status
+Under development
+

asteroid_spinprops-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+asteroid_spinprops/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asteroid_spinprops/ssolib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asteroid_spinprops/ssolib/dataprep.py,sha256=7PfkVNpLjPERkhr8dZQfN8haFCFmoeXB3fWuTSBLVuc,7848
+asteroid_spinprops/ssolib/modelfit.py,sha256=Kg5Qn0yU4wbfat9ZCvT9pYqSIo9toUm5kwhCiSvhalw,15898
+asteroid_spinprops/ssolib/periodest.py,sha256=XCBqsgPFcLFk-vreVmpYPjghJDyUyHSEeCULayqPRHg,13216
+asteroid_spinprops/ssolib/ssptools.py,sha256=DlSgYtXenztRAtEV9d4itzp5OZMjkbXkW2yZ_Qumu4U,4490
+asteroid_spinprops/ssolib/utils.py,sha256=BUeIP0DZ45tg5qAQML8LBM8Gbj1vn2d3PGzvgQvfq_I,11094
+asteroid_spinprops-1.0.0.dist-info/METADATA,sha256=LZvpOARV-nWnAkOnr5S097mzTbWufl7_qPS8zYxE6gw,3111
+asteroid_spinprops-1.0.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+asteroid_spinprops-1.0.0.dist-info/RECORD,,

asteroid_spinprops/ssolib/.ruff_cache/.gitignore

@@ -1,2 +0,0 @@
-# Automatically created by ruff.
-*

asteroid_spinprops/ssolib/.ruff_cache/CACHEDIR.TAG

@@ -1 +0,0 @@
-Signature: 8a477f597d28d172789f06886806bc55