Metadata-Version: 2.4
Name: saxs_assistant
Version: 0.1.4
Summary: SAXS Assistant: Automated analysis of SAXS data including Guinier, PDDF, and ML-based Dmax prediction
Author: Cesar Ramirez
Author-email: cr828@scarletmai.rutgers.edu
Project-URL: Tutorial, https://github.com/C3344/SAXS-Assistant/blob/main/Supplemental%20Data/Tutorial%20PDF.pdf
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: pandas==2.2.2
Requires-Dist: joblib==1.5.1
Requires-Dist: matplotlib==3.10.3
Requires-Dist: numba<0.62,>=0.59
Requires-Dist: numpy<3.0.0,>=2.0.0
Requires-Dist: scikit-learn==1.6.1
Requires-Dist: scipy==1.15.3
Requires-Dist: tqdm==4.67.1
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pillow==11.2.1
Requires-Dist: requests<3,>=2.32
Requires-Dist: natsort
Provides-Extra: music
Requires-Dist: playsound==1.2.2; extra == "music"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


#  SAXS Assistant

**SAXS Assistant** is a plug-and-play Python package for automating SAXS (Small-Angle X-ray Scattering) data analysis. It streamlines the entire process — from file preparation to result visualization — with a single command.

---

##  Installation

### Standard
```bash
pip install saxs-assistant

***For Google Colab use
!pip install saxs-assistant 
```

### With optional music playback  (for local environments only- not for colab)
```bash
pip install saxs-assistant[music]
```

---

##  Quick Start

### 1. Analyze Your Data

```python
from saxs_assistant import analyze_and_plot_all

plot_data, results = analyze_and_plot_all("path/to/input_file.xlsx")
```

This will:
- Run analysis on all entries in the input file
- Save plots and results in a `return/` folder
- Print status updates and return:
  - `plot_data`: dictionary for visualizations
  - `results`: pandas dataframe of SAXS outputs
  - solved_only: pandas dataframe of SAXS outputs without any files that have "Fatal Flag" entry or missing Pr/Guinier Rg
  -unsolved_only: Dataframe having only the files that werent solved
  -plots folder: This has the raw graph data for the solved files will be saved in the same directory to where the PDF summary plots are solved

#### Optional arguments
```python
analyze_and_plot_all(
    df_path="input_file.xlsx",
    start_index=50,     # Start analysis at row 50 of the input file
    end_index=100,      # End at row 100 (non-inclusive)
    output_dir="my_results",  # Override output folder
    music=True          # Play background music (if installed locally)
)
```

---

### 2. Generate an Input File

Use this if you don’t already have a dataframe:
```python
from saxs_assistant import prepare_dataframe

df = prepare_dataframe(folder_path="path/to/folder", angular_unit="1/A")
```

This scans your folder and creates an Excel input file containing:
- File names and paths
- Angular unit (must be `'1/A'` or `'1/nm'`)

Saved as: `input_df_<date>.xlsx` in the parent folder.

---

### 3. Combine Multiple Sessions (Optional)

If you run `analyze_and_plot_all()` multiple times, each run will create folders like:
- `return/`
- `return_1/`
- `return_2/`  
...in the same parent directory.

To merge the results:
```python
from saxs_assistant.organizer import combine_sessions

combine_sessions(base_path="path/to/folder")
```

This will:
- Combine all `results.xlsx` and `plot_data.joblib` into a single file
- Save them as:
  - `final_results.xlsx`
  - `final_results_Plots.joblib`
- Move original `return*` folders into a subdirectory called `partials/`

---

##  Expected Input Format

Your Excel input file must contain:
- `file name`: Name of each SAXS file
- `path`: Folder containing the file
- `Angular unit`: Either `1/A` or `1/nm`

You can generate this automatically using `prepare_dataframe()` or create it manually.

---

##  Output

All outputs are stored in a `/return/` folder unless otherwise specified:
- `results.xlsx`: All extracted parameters
- `plot_data.joblib`: Data dictionary for visualization
- `summary_plots.pdf`: Auto-generated plots of good fits
- `flagged_plots.pdf`: Highlighted issues or low-quality data

---

##  Optional: Music Playback

Add a little ambiance during analysis:
```python
analyze_and_plot_all("input.xlsx", music=True)
```

Note:
- Only works on local machines
- Automatically skipped in cloud environments (e.g., Colab)

---

##  Example Use Case

```python
# Step 1: Prepare input
prepare_dataframe(folder_path="saxs_data", angular_unit="1/A")

# Step 2: Run analysis
analyze_and_plot_all("input_df_Jun_25_25.xlsx", music=True)

# (optional) Step 3: Combine results from multiple sessions
combine_sessions(base_path="saxs_data")
```

---

##  Dependencies

Automatically installed via `setup.py`.  
To install manually:
```bash
pip install -r requirements.txt
```

For music playback:
```bash
pip install playsound
```

---

##  License

MIT License

---

##  Acknowledgments

Developed for efficient SAXS exploration — may it help others find structure in the scatter.
SAXS Assisant does not offer warranty-- use at your own risk and evaluate the results carefully.
If you use SAXS Assistant Please Cite RAW and BIFT

Hansen, S. Journal of Applied Crystallography (2000) 33, 1415-1421. DOI: 10.1107/S0021889800012930

https://doi.org/10.1107/S1600576723011019
https://doi.org/10.1107/S0021889809023863
