Metadata-Version: 2.4
Name: janas
Version: 2.1.6
Summary: Pipeline for per-particle selection and 3D class reassignment in single-particle cryo-EM.
Home-page: https://gitlab.com/topf-lab/janas
Author: Mauro Maiorca
Author-email: mauro.maiorca@cssb-hamburg.de
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.2
Requires-Dist: scipy>=1.6
Requires-Dist: scikit-image>=0.18
Requires-Dist: matplotlib>=3.3
Requires-Dist: seaborn>=0.11
Requires-Dist: toml>=0.10
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == "gpu"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<p align="center">
  <img src="docs/images/janasLogo.png" alt="JANAS logo" width="200">
</p>

<h1 align="center">JANAS</h1>
<p align="center"><strong>Joint ANAlysis of Stacks for CryoEM</strong></p>

<p align="center">
  <a href="https://pypi.org/project/janas/"><img src="https://img.shields.io/pypi/v/janas" alt="PyPI"></a>
  <a href="https://pypi.org/project/janas/"><img src="https://img.shields.io/pypi/pyversions/janas" alt="Python"></a>
</p>

<p align="center">
  <a href="#installation">Installation</a> &bull;
  <a href="docs/index.md">Documentation</a> &bull;
</p>

---

JANAS is a command-line toolkit for particle ranking, subset selection and class reassignment in single-particle cryo-EM workflows.

It uses the per-particle Structural Cross-correlation Index (SCI) to rank particles by their contribution to local map quality.

## Quick access

- [Install from PyPI](https://pypi.org/project/janas/) — install JANAS with `pip install janas`.
- [Source code](https://gitlab.com/topf-lab/janas) — main GitLab repository.
- [Documentation](docs/) — installation, workflows, command reference and utilities.
- [Quick start](docs/quick-start.md) — minimal commands to start using JANAS.
- [Particle selection workflow](docs/workflows/selection.md) — SCI-based ranking and subset selection.
- [3D class reassignment workflow](docs/workflows/classification.md) — reassignment of particles across predefined 3D classes.
- [Demo bundle](demo_bundle/) — self-contained software-testing bundle with example inputs, scripts, expected outputs, run-time information and documentation for particle selection and 3D class reassignment.
- [JANAS application datasets and analysis outputs](https://doi.org/10.5281/zenodo.20417605) — deposited particle selections, class reassignments, refined maps, models, metadata and SCI characterisation files.

The demo package contains small example inputs, scripts, expected outputs and run-time information for testing the two core workflows. These examples are intended for installation checks and end-to-end command validation. The simulated examples are provided to test installation and command execution; the scientific analyses are based on experimental cryo-EM datasets. The Zenodo record contains datasets associated with the application of JANAS, including particle selections, class reassignments, refined maps, models, metadata, local-resolution analyses and SCI characterisation files. Raw particle stacks from public EMPIAR entries are not duplicated there and should be obtained from the corresponding EMPIAR records.

## Core workflows

| Workflow | Purpose |
|----------|---------|
| [Iterative particle selection](docs/ITERATIVE_SELECTION.md)  | Score, rank and select particle subsets that maximise local resolution. |
| [Custom selected stacks](docs/custom_selected_stacks.md)  | Extract an ad-hoc top-`N` best-ranked subset from a converged selection, e.g. as input for JANAS-based repicking. |
|  [3D class reassignment](docs/CLASS_REASSIGNMENT.md)  | Assign particles to pre-computed classes using per-map SCI scores. |


## Monitoring a running session

JANAS records the outcome of every selection iteration in `overview.txt` and the timing of every individual processing step in `runtime/step_timings.csv`. While the session runs it also keeps an HTML dashboard, `progress.html`, in sync with the latest state. See [Monitoring a running session](docs/progress_dashboard.md) for how to view it locally or over SSH from a remote browser.


## Interoperability workflows

| Workflow | Purpose |
|----------|---------|
| [CryoSPARC particle STAR recovery](docs/workflows/cryosparc_star_recovery.md) | Convert CryoSPARC `.cs` particle metadata to RELION/JANAS STAR format, adjust stack references, and restore original source particle image names after stack-based processing. |

## Accessory utils

| Utility | Purpose |
|---------|---------|
| [sigma_estimate](docs/sigma_estimate.md) | Estimate a Gaussian sigma for SCI scoring from a pair of half-maps. |
| [compare_maps](docs/accessory_utils.md#compare_maps) | Compare two 3D maps using cross-correlation and related similarity measures. |
| [csparc2star-stack](docs/accessory_utils.md#csparc2star-stack) | Convert a CryoSPARC `.cs` file to a RELION STAR and assemble a consolidated `.mrcs` stack. |
| [clip blur](docs/accessory_utils.md#clip-blur) | Gaussian-blur a 3D volume (sigma in Ångström). |
| [clip bfac](docs/accessory_utils.md#clip-bfac) | B-factor weighting (sharpening) of a 3D volume, automatic or user-driven. |
| [fsc](docs/accessory_utils.md#fsc) | Compute Fourier Shell Correlation (FSC) between half-map pairs. |
| [locres](docs/accessory_utils.md#locres) | Compute a local-resolution map from a pair of half-maps. |
| [project_map](docs/accessory_utils.md#project_map) | Project a 3D reference map at each particle pose, writing 2D reprojections. |
| [janas_reconstructor](docs/accessory_utils.md#janas_reconstructor) | Internal 3D reconstruction from scored particles (GPU or CPU). |

## Installation

Requires Python 3.8+, a C++ compiler, and CMake 3.10+.

```bash
pip install janas
```

We recommend installing in an isolated environment:

```bash
python3 -m venv ~/.janas_env
source ~/.janas_env/bin/activate
pip install janas
```

Verify:

```bash
janas --version
```

See the [Installation Guide](docs/installation.md) for conda, pipx, troubleshooting, and building from source.


## Documentation

- [Documentation index](docs/index.md)
- [Installation](docs/installation.md)
- [Quick start](docs/quick-start.md)
- [Iterative particle selection](docs/workflows/selection.md)
- [3D class reassignment](docs/workflows/classification.md)
- [CryoSPARC integration](docs/workflows/cryosparc.md)
- [CLI command reference](docs/reference/cli.md)
- [Accessory utilities](docs/accessory_utils.md)
  - [sigma_estimate](docs/sigma_estimate.md)
- [STAR file operations](docs/reference/star-operations.md)
- [Computational requirements](docs/reference/computational-requirements.md)
- [Tutorial: EMPIAR-10308](docs/examples/empiar-10308.md)
- [Troubleshooting](docs/troubleshooting.md)


## Contact

For questions or issues: mauro.maiorca@cssb-hamburg.de
