asteroid_spinprops 0.2.32__tar.gz → 1.0.1__tar.gz

asteroid_spinprops-1.0.1/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: asteroid_spinprops
+Version: 1.0.1
+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.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Requires-Dist: astropy (>=6.0)
+Requires-Dist: fink-utils (>=0.47.0)
+Requires-Dist: nifty-ls (>=1.1.0)
+Requires-Dist: pandas (>=2.3)
+Requires-Dist: pyarrow (>=18.1)
+Requires-Dist: sbpy (>=0.5.0)
+Requires-Dist: scipy (>=1.10)
+Requires-Dist: tqdm (>=4.67)
+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
+```
+
+## Input column requirements and preprocessing
+
+`asteroid_spinprops` expects photometric measurements to follow the **Fink alert schema**.  
+If your DataFrame uses different column names, they must be renamed to the standard format before analysis.
+
+The package maps common input columns to Fink-style fields:
+
+| Expected name | Description | 
+|---------------|-------------|
+| `cjd`         | Observation time (JD) |
+| `cmagpsf`     | PSF magnitude |
+| `csigmapsf`   | Magnitude uncertainty | 
+| `cfid`        | Filter identifier | 
+| `ra`          | Right ascension (deg) | 
+| `dec`         | Declination (deg) |
+| `Phase`       | Solar phase angle (deg) | 
+
+### Additional columns created during preprocessing
+
+The preprocessing step also adds the following fields:
+
+- **`cmred` — Reduced magnitude**
+
+  Computed from the heliocentric and observer-centric distances:
+
+
+$$
+\mathrm{cmred} = \mathrm{cmagpsf} - 5\log_{10}\!\left(\frac{r\,\Delta}{\mathrm{AU}^2}\right)
+$$  
+where `Obj_Sun_LTC_km` = \(r\) and `Range_LTC_km` = \(\Delta\).
+
+- **`jd_ltc` — Light-time–corrected Julian Date**
+
+  First converts MJD → JD (`+ 2400000.5`), then applies the correction
+
+  $$
+  JD_\mathrm{ltc} = JD - \frac{\Delta}{c},
+  $$    
+
+  using the one-way light-travel time in days.
+
+```python
+pdf.rename(
+    columns={
+        "Your_JD_column": "cjd",
+        "Your_magnitudes_column": "cmagpsf",
+        "Your_phase_angle_column": "Phase",
+        "Your_RA_column": "ra",
+        "Your_Dec_column": "dec",
+        "Your_magnitude_uncertainty_column": "csigmapsf",
+        "Your_filter_column": "cfid",
+    },
+    inplace=True,
+)
+
+# Add missing columns
+pdf["cmred"] = pdf["cmagpsf"] - 5 * np.log10(
+    pdf["Observer_SSO_distance_column"] * pdf["Sun_SSO_distance_column"] / (au**2)
+)
+
+# LT correction
+pdf["cjd"] = pdf["cjd"] + 2400000.5  # MJD to JD
+pdf["jd_ltc"] = pdf["cjd"] - pdf["Observer_SSO_distance_column"] / c_kmday  # light time correction
+
+```
+
+### Required inputs
+
+Your input DataFrame must therefore include:
+
+- time of observation  
+- PSF magnitude and uncertainty  
+- filter ID  
+- RA, Dec  
+- phase angle  
+- heliocentric distance (`Obj_Sun_LTC_km`)  
+- observer-centric distance (`Range_LTC_km`)
+
+The preprocessing step renames these fields to the Fink schema, computes reduced magnitudes, and applies the light-time correction to the observation timestamps.
+
+
+## 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.1/README.md

@@ -0,0 +1,157 @@
+# 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
+```
+
+## Input column requirements and preprocessing
+
+`asteroid_spinprops` expects photometric measurements to follow the **Fink alert schema**.  
+If your DataFrame uses different column names, they must be renamed to the standard format before analysis.
+
+The package maps common input columns to Fink-style fields:
+
+| Expected name | Description | 
+|---------------|-------------|
+| `cjd`         | Observation time (JD) |
+| `cmagpsf`     | PSF magnitude |
+| `csigmapsf`   | Magnitude uncertainty | 
+| `cfid`        | Filter identifier | 
+| `ra`          | Right ascension (deg) | 
+| `dec`         | Declination (deg) |
+| `Phase`       | Solar phase angle (deg) | 
+
+### Additional columns created during preprocessing
+
+The preprocessing step also adds the following fields:
+
+- **`cmred` — Reduced magnitude**
+
+  Computed from the heliocentric and observer-centric distances:
+
+
+$$
+\mathrm{cmred} = \mathrm{cmagpsf} - 5\log_{10}\!\left(\frac{r\,\Delta}{\mathrm{AU}^2}\right)
+$$  
+where `Obj_Sun_LTC_km` = \(r\) and `Range_LTC_km` = \(\Delta\).
+
+- **`jd_ltc` — Light-time–corrected Julian Date**
+
+  First converts MJD → JD (`+ 2400000.5`), then applies the correction
+
+  $$
+  JD_\mathrm{ltc} = JD - \frac{\Delta}{c},
+  $$    
+
+  using the one-way light-travel time in days.
+
+```python
+pdf.rename(
+    columns={
+        "Your_JD_column": "cjd",
+        "Your_magnitudes_column": "cmagpsf",
+        "Your_phase_angle_column": "Phase",
+        "Your_RA_column": "ra",
+        "Your_Dec_column": "dec",
+        "Your_magnitude_uncertainty_column": "csigmapsf",
+        "Your_filter_column": "cfid",
+    },
+    inplace=True,
+)
+
+# Add missing columns
+pdf["cmred"] = pdf["cmagpsf"] - 5 * np.log10(
+    pdf["Observer_SSO_distance_column"] * pdf["Sun_SSO_distance_column"] / (au**2)
+)
+
+# LT correction
+pdf["cjd"] = pdf["cjd"] + 2400000.5  # MJD to JD
+pdf["jd_ltc"] = pdf["cjd"] - pdf["Observer_SSO_distance_column"] / c_kmday  # light time correction
+
+```
+
+### Required inputs
+
+Your input DataFrame must therefore include:
+
+- time of observation  
+- PSF magnitude and uncertainty  
+- filter ID  
+- RA, Dec  
+- phase angle  
+- heliocentric distance (`Obj_Sun_LTC_km`)  
+- observer-centric distance (`Range_LTC_km`)
+
+The preprocessing step renames these fields to the Fink schema, computes reduced magnitudes, and applies the light-time correction to the observation timestamps.
+
+
+## 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.1/asteroid_spinprops/ssolib/dataprep.py

@@ -0,0 +1,250 @@
+import numpy as np
+import pandas as pd
+from asteroid_spinprops.ssolib.modelfit import (
+    get_fit_params,
+    get_residuals,
+)
+
+import asteroid_spinprops.ssolib.utils as utils
+
+
+def errorbar_filtering(data, mlimit):
+    """
+    Filter out data points with large photometric uncertainties.
+
+    Parameters
+    -----------
+    data : pd.DataFrame
+        A single-row DataFrame where each column contains an array of values
+        for a solar system object.
+    mlimit : float
+        Threshold value to filter out points with uncertainties greater than mlimit / 2.
+
+    Returns
+    -------
+    data : pd.DataFrame
+        Filtered DataFrame
+    rejects : pd.DataFrame
+        DataFrame containing the rejected measurements
+    """
+    errorbar_condition = data["csigmapsf"].values[0] <= mlimit / 2
+    rejects = data.copy()
+
+    for c in data.columns:
+        if c not in ["index", "kast", "name"]:
+            rejects.at[0, c] = data[c].values[0][~errorbar_condition]
+            data.at[0, c] = data[c].values[0][errorbar_condition]
+
+    return data, rejects
+
+
+def projection_filtering(data):
+    """
+    Filters out photometric outliers in reduced magnitude space per filter using a 3 sigma criterion.
+
+    Parameters
+    -----------
+    data : pd.DataFrame
+        A single-row DataFrame where each column contains an array of values.
+    Returns
+    --------
+    data : pd.DataFrame
+        Filtered DataFrame
+    rejects : pd.DataFrame
+        DataFrame containing the rejected measurements
+    """
+    rejects = data.copy()
+    valid_indices = []
+
+    for f in np.unique(data["cfid"].values[0]):
+        filter_mask = np.array(data["cfid"].values[0]) == f
+
+        mean_val = np.mean(data["cmred"].values[0][filter_mask])
+        std_val = np.std(data["cmred"].values[0][filter_mask])
+
+        project_condition = (
+            filter_mask
+            & (data["cmred"].values[0] > mean_val - 3 * std_val)
+            & (data["cmred"].values[0] < mean_val + 3 * std_val)
+        )
+
+        valid_indices.append(np.where(project_condition)[0])
+
+    valid_indices = np.sort(
+        np.concatenate([valid_indices[n] for n in range(len(valid_indices))])
+    )
+
+    dummy = np.ones(data["cfid"].values[0].shape, dtype=bool)
+    dummy[valid_indices] = False
+
+    for c in data.columns:
+        if c not in ["index", "kast", "name"]:
+            rejects.at[0, c] = data[c].values[0][dummy]
+            data.at[0, c] = data[c].values[0][valid_indices]
+
+    return data, rejects
+
+
+def iterative_filtering(data, max_iter=10):
+    """
+    Iteratively removes outliers based on residuals from fitting the SHG1G2 mdoel until convergence.
+
+    Parameters
+    -----------
+    data : pd.DataFrame
+        A single-row DataFrame where each column contains an array of values.
+
+    max_iter : int
+        Maximum number of filtering iterations (default is 10).
+
+    Returns
+    --------
+    data : pd.DataFrame
+        Filtered DataFrame
+
+    rejects : pd.DataFrame
+        DataFrame containing the rejected measurements
+    """
+    rejects = data.copy()
+
+    mask = np.ones_like(data["cfid"].values[0], dtype=bool)
+    inloop_quants = {}
+    reject_quants = {}
+
+    for c in data.columns:
+        if c not in ["index", "kast", "name"]:
+            inloop_quants[c] = data[c].values[0]
+            reject_quants[c] = np.array([])
+
+    for niter in range(max_iter):
+        prev_len = len(inloop_quants["cfid"])
+
+        for k in inloop_quants.keys():
+            reject_quants[k] = np.append(reject_quants[k], inloop_quants[k][~mask])
+            inloop_quants[k] = inloop_quants[k][mask]
+
+        mparams = get_fit_params(pd.DataFrame([inloop_quants]), "SHG1G2")
+        try:
+            residuals = get_residuals(pd.DataFrame([inloop_quants]), mparams)
+        except KeyError:
+            break
+        mask = np.abs(residuals) < 3 * np.std(residuals)
+
+        if prev_len == len(inloop_quants["Phase"][mask]):
+            break
+
+        for c in data.columns:
+            if c not in ["index", "kast", "name"]:
+                data.at[0, c] = inloop_quants[c]
+                rejects.at[0, c] = reject_quants[c]
+    return data, rejects
+
+
+def lightcurve_filtering(data, window=10, maglim=0.6):
+    """
+    Filters out lightcurve points that deviate from the median by more than given mag limitation within time bins.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        Single-row DataFrame
+    window : float
+        Time bin size (default is 10 days).
+    maglim : float
+        Magnitude deviation threshold from the median (default is 0.4 mag).
+
+    Returns
+    -------
+    data : pd.DataFrame
+        Filtered data
+    rejects : pd.DataFrame
+        DataFrame containing the rejected measurements
+    """
+    dummym, dummyt, dummyf, dummyi = [], [], [], []
+
+    dates = data["cjd"].values[0]
+    magnitudes = data["cmred"].values[0]
+    filters = data["cfid"].values[0]
+    indices = np.array([ind for ind in range(len(data["cfid"].values[0]))])
+
+    ufilters = np.unique(filters)
+
+    mag_pfilt = {}
+
+    date0 = dates.min()
+    date0_plus_step = date0 + window
+    # TODO: Use np.digitize instead of this
+    while date0 < dates.max():
+        prev_ind = np.where(dates == utils.find_nearest(dates, date0))[0][0]
+        plus_ten_index = np.where(dates == utils.find_nearest(dates, date0_plus_step))[
+            0
+        ][0]
+
+        dummym.append(magnitudes[prev_ind:plus_ten_index])
+        dummyt.append(dates[prev_ind:plus_ten_index])
+        dummyf.append(filters[prev_ind:plus_ten_index])
+        dummyi.append(indices[prev_ind:plus_ten_index])
+
+        date0 = dates[plus_ten_index]
+        date0_plus_step = date0_plus_step + window
+
+    dummym.append(magnitudes[plus_ten_index:])
+    dummyt.append(dates[plus_ten_index:])
+    dummyf.append(filters[plus_ten_index:])
+    dummyi.append(indices[plus_ten_index:])
+
+    mag_binned, _, filt_binned, ind_binned = (
+        np.asarray(dummym, dtype=object),
+        np.asarray(dummyt, dtype=object),
+        np.asarray(dummyf, dtype=object),
+        np.asarray(dummyi, dtype=object),
+    )
+
+    for f in ufilters:
+        dummymain, dummym, dummyt, dummydiff, dummyi = [], [], [], [], []
+        for n in range(len(mag_binned)):
+            fcond = filt_binned[n] == f
+            dummymain.append(mag_binned[n][fcond])
+            dummym.append(np.median(mag_binned[n][fcond]))
+            dummydiff.append(
+                np.max(mag_binned[n][fcond], initial=0)
+                - np.min(mag_binned[n][fcond], initial=1e3)
+            )
+            dummyi.append(ind_binned[n][fcond])
+
+        dummydiff = np.array(dummydiff)
+        dummydiff[dummydiff == np.float64(-1000.0)] = 0
+
+        mag_pfilt["medimag_{}".format(f)] = dummym
+        mag_pfilt["mxmnmag_{}".format(f)] = dummydiff
+        mag_pfilt["mag_{}".format(f)] = dummymain
+        mag_pfilt["ind_{}".format(f)] = dummyi
+
+    valid_indices = []
+    reject_indices = []
+
+    rejects = data.copy()
+
+    for f in ufilters:
+        for n in range(len(mag_binned)):
+            bin_cond = (
+                mag_pfilt["mag_{}".format(f)][n]
+                > mag_pfilt["medimag_{}".format(f)][n] + maglim
+            ) | (
+                mag_pfilt["mag_{}".format(f)][n]
+                < mag_pfilt["medimag_{}".format(f)][n] - maglim
+            )
+            valid_indices.append(mag_pfilt["ind_{}".format(f)][n][~bin_cond])
+            reject_indices.append(mag_pfilt["ind_{}".format(f)][n][bin_cond])
+
+    valid_indices = np.array(utils.flatten_list(valid_indices), dtype=int)
+    reject_indices = np.array(utils.flatten_list(reject_indices), dtype=int)
+
+    for c in data.columns:
+        if c not in ["index", "kast", "name"]:
+            rejects.at[0, c] = data[c].values[0][reject_indices]
+            data.at[0, c] = data[c].values[0][valid_indices]
+
+    data = utils.sort_by_cjd(data)
+
+    return data, rejects