Metadata-Version: 2.4
Name: pyatsas
Version: 0.1.0
Summary: Python wrappers and input builders for ATSAS command-line tools.
Author: blanchet
License-Expression: MIT
Project-URL: Homepage, https://git.embl.de/blanchet/pyatsas
Project-URL: ATSAS, https://www.biosaxs.com/download
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Dynamic: license-file

# pyatsas

`pyatsas` provides lightweight Python wrappers around ATSAS command-line tools
and small helpers for preparing the input files used by dialog-driven ATSAS
programs.

This package is an independent Python wrapper for ATSAS command-line tools.
ATSAS itself is not distributed with this package and must be installed
separately. `pyatsas` does not reimplement ATSAS algorithms; it focuses on
making ATSAS calls reproducible from Python code, notebooks, and automated
workflows.

## What Is Included

- Command wrappers for ATSAS programs such as `autorg`, `crysol`, `dammin`,
  `dammif`, `gnom`, `bunch`, `coral`, `ranch`, `gajoe`, `monsa`, `bodies`,
  `ffmaker`, and related utilities.
- Input builders for interactive ATSAS tools, including MONSA, RANCH/GAJOE,
  BUNCH, and CORAL.
- Small data-reading helpers for common SAXS output files.
- Unit tests that mock ATSAS execution, so the default test suite can run
  without ATSAS installed.

## ATSAS Dependency

`pyatsas` does not bundle ATSAS. Importing `pyatsas` does not require ATSAS, but
calling a wrapper requires the corresponding ATSAS executable to be available in
the process environment.

Wrappers call executables by name, for example `autorg`, `crysol`, or `coral`.
This means the ATSAS binary directory must be on `PATH`. If an executable is
missing, `pyatsas` raises `AtsasExecutableNotFoundError` with the missing program
name and a short troubleshooting message.

Useful ATSAS links:

- ATSAS download and license information: <https://www.biosaxs.com/download>
- ATSAS software overview: <https://biosaxs.com/software.html>
- EMBL Hamburg ATSAS page for older academic ATSAS 3.x information:
  <https://www.embl-hamburg.de/biosaxs/download.html>

Academic users should follow the registration and licensing instructions on the
ATSAS download page. Commercial users should follow the BIOSAXS licensing
instructions.

### Troubleshooting Missing Executables

Check that ATSAS works from the same shell or environment where Python runs:

```powershell
autorg --help
```

On Windows, add the ATSAS installation directory containing the `.exe` files to
`PATH`, then restart the terminal, IDE, notebook kernel, or Python session.

You can also check availability from Python:

```python
from pyatsas import require_atsas_executable

require_atsas_executable("autorg")
```

## Installation

For development from a local checkout:

```bash
python -m pip install -e .
```

The Python package depends on `numpy` and `pandas`. ATSAS itself must be
installed separately.

## Basic Usage

Run a command-style ATSAS wrapper:

```python
from pyatsas import autorg

result = autorg("sample.dat")
print(result["result"])
```

Build an answer script for an interactive program:

```python
from pyatsas import build_coral_answers_text, write_coral_script_file

script = build_coral_answers_text(
    project_name="model",
    description="CORAL run from Python",
    config_token="config",
    use_config=True,
    datafile="sample.dat",
)
write_coral_script_file("coral.stdin", text=script)
```

Run an interactive wrapper by passing a prepared script:

```python
from pyatsas import coral

result = coral(script_path="coral.stdin", cwd="run")
print(result["stdout"])
```

More examples are collected in
[`pyatsas/IO_BUILDERS_USAGE.md`](pyatsas/IO_BUILDERS_USAGE.md).

## Tests

The default test suite does not require ATSAS:

```bash
pytest
```

ATSAS integration tests are marked with `atsas` and are skipped by default. Run
them explicitly only in an environment where ATSAS executables are available on
`PATH`:

```bash
pytest -m atsas
```

## Development Notes

- Wrapper functions generally return a dictionary with the tool name, command,
  return code, stdout, stderr, outputs, and working directory.
- Non-zero ATSAS exits raise `subprocess.CalledProcessError`.
- Missing input files raise `FileNotFoundError`.
- Missing ATSAS executables raise `AtsasExecutableNotFoundError`.
- Dialog/input builders return plain text so generated scripts can be inspected,
  tested, and version-controlled.

## License

`pyatsas` is distributed under the MIT License. ATSAS is a separate software
package with its own license and must be obtained from the official ATSAS
distribution channels.
