opus-et-agentBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: opus-et-analysis
description: Use when the user has OPUS-ET training output and wants to interpret it: PCA or k-means over the latent codes of an epoch, volumes for cluster centres or principal components, per-state STAR files, pose parsing, the original pixel size, a training command for a new run, or a molecule mask and gold-standard FSC between half maps after Gate 3 or 4. Also use for state-vs-template and per-tomogram state-consistency checks.
---

# opus-et Analysis

Process and analyze cryo-ET training results from opus-et.

## Agent Rules — read before acting

- **Do only what the user asks.** Don't anticipate, extend, or fix unreported issues — even obvious ones. One change at a time.
- **Read before editing.** Always read the current file/script before describing or modifying it. Don't rely on remembered content — the codebase changes.
- **Verify before asserting.** If uncertain how a tool, flag, or script behaves, check (`--help`, API docs, actual output) rather than inferring from naming. Wrong documentation is worse than no documentation.
- **Enumerate scope before acting.** For multi-file changes, use `grep` to find all affected files and confirm scope with the user before making any edits.
- **Show before and after for every edit.** Before modifying a script or config, quote the relevant current lines. After editing, summarize exactly what changed — not just "done."
- **Don't chain changes.** Renaming a variable in one place does NOT mean you should rename it everywhere — confirm scope first.
- **Don't redesign.** Apparent inconsistencies may be intentional. Respect the existing pattern unless the user asks to change it.
- **When in doubt, show the current state and ask.** "Here's what I see. Do you want me to change X, Y, or both?"


## Training Command Generation
`scripts/generate_train_cmd.py --help` generates the training script -- the template it emits is reproduced verbatim in the reference, with every parameter explained; prefer the script to hand-editing. Full text: `references/training_command.md`.

## Helper Scripts

The following helper scripts ship with this skill and are located in the skill's `scripts/` directory (not the project directory):

```
<skill-dir>/scripts/
```

`<skill-dir>` is the directory where this skill is installed. When invoking the scripts from a project working directory, replace `<skill-dir>` with the actual skill path, or copy/symlink the scripts into your project. Examples below use `<skill-dir>` as a placeholder.

### `generate_train_cmd.py`
Generates training commands with automatic pose pkl generation.
```bash
python <skill-dir>/scripts/generate_train_cmd.py [options]
```

### `extract_config.py`
Extracts configuration parameters from config.pkl.
```bash
python <skill-dir>/scripts/extract_config.py config.pkl
```

### `exclude_stars.py`
Checks overlap between two star files based on 3D coordinates.
```bash
python <skill-dir>/scripts/exclude_stars.py <reference.star> <query.star>
```

**Pixel size:** Auto-detected from `config.pkl` in the current directory (`Apix * downfrac`). Falls back to 3.37 Å if no config.pkl is found.

**Distance threshold:** `136/angpix` voxels = **136 Å** (constant physical distance regardless of pixel size).

## Determining the Original Pixel Size

The original data pixel size (needed for `parse_pose_star`, `exclude_stars.py`, etc.) can be found two ways:

**From config.pkl** (recommended):
```python
import pickle
config = pickle.load(open('config.pkl', 'rb'))
original_Apix = config['model_args']['Apix'] * config['dataset_args']['downfrac']
```

**From the star file** (alternative):
Check `_rlnDetectorPixelSize` (column 9) in the star file header — this is the original pixel size of the raw data.

The two values should agree closely. The star file value is the authoritative original; the config.pkl derivation is the training pipeline's record of it.

Use `<skill-dir>/scripts/extract_config.py` to extract config values including `original_Apix`.

## Quick Reference

Key parameters from `config.pkl`:
- `Apix = config['model_args']['Apix']` (training-effective pixel size)
- `downfrac = config['dataset_args']['downfrac']` (downsampling fraction)
- `original_Apix = Apix * downfrac` (original data pixel size — use for `parse_pose_star` and other original-data operations)
- `D = config['lattice_args']['D'] - 1` (effective box size is lattice D minus 1)
- `particles = config['dataset_args']['particles']` (original star file)

**Important:** The `Apix` stored in `config.pkl` is the training-effective pixel size. For operations on the original star file (e.g., `dsd parse_pose_star`), multiply by `downfrac` to get the original data pixel size:
```python
import pickle
config = pickle.load(open('config.pkl', 'rb'))
apix = config['model_args']['Apix'] * config['dataset_args']['downfrac']
```

Use `<skill-dir>/scripts/extract_config.py` to extract these values.

## Multi-Body Training

To enable multi-body deformation modeling, add `--masks <path_to_mask_params.pkl>` to the training command. The `mask_params.pkl` file contains rigid body definitions:

| Key | Description |
|-----|-------------|
| `com_bodies` | Centers of mass for each rigid body (shape: `[num_bodies, 3]`) |
| `principal_axes` | Principal axes defining body orientations |
| `orient_bodies` | Body orientation matrices |
| `rotate_directions` | Allowed rotation directions for each body |
| `in_relatives` | Rotation reference body index - body *i* rotates relative to body `in_relatives[i]` |
| `radii_bodies` | Radii for each body |

### Parameter Clarification

- **`ZDIM`**: Composition latent space dimension - captures structural/compositional heterogeneity
- **`--zaffinedim`**: Conformation latent space dimension - captures continuous conformational changes (independent of deformation modeling)
- **`--masks`**: Enables rigid body deformation modeling using the body definitions in `mask_params.pkl`

These three mechanisms operate independently:
- **

BLOCKgrade D · trust 61/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

declared (2 observation(s))

Shell

declared (3 observation(s))

Dependencies

not all pinned

Secrets in source

none-found

Findings (24)

labels = np.asarray(pickle.load(f)).ravel()

config = pickle.load(f)

cluster_of_particle = np.asarray(pickle.load(f)).ravel()

print(f"warning: no checkpoint matched {gate!r} (token {token!r}).")

Then open <http://127.0.0.1:8080>.

"../../../etc/passwd", "/etc/passwd", "species.conf; rm -rf /",

"../../etc/passwd", "/etc/passwd", "qc/../../secret.png", "qc/not_listed.png",

"../../../etc/passwd", "/etc/passwd", "species.conf; rm -rf /",

"../../etc/passwd", "a/b", "has space", "semi;colon", "$(id)", "", "-" * 40,

"../../etc/passwd", "/etc/passwd", "qc/../../secret.png", "qc/not_listed.png",

"TS_999", "../../etc/passwd", "TS_026; rm -rf /", "$(id)", "",

out = sources.parse_qc_list("qc/ok.png\n../../etc/passwd\n/abs/path.png\nqc/../x.png\n")

Then open <http://127.0.0.1:8080>. `--host` is any SSH alias that already works without a password prompt; `--work-dir` is the run directory on the cluster. Where `python3` is not on `PATH` in a non-i

yield f"http://127.0.0.1:{port}", editor

yield f"http://127.0.0.1:{httpd.server_address[1]}"

base = f"http://127.0.0.1:{httpd.server_address[1]}"

return base64.b64decode(res.stdout)

png = base64.b64decode(out['image'])

pytest, starfile, pandas, numpy, mrcfile, scipy, matplotlib

demo/qc/finale/fas_TS028_scan.gif

demo/qc/finale/fas_TS028_scan.mp4

demo/qc/finale/fas_raw_context.png

demo/qc/finale/finale_insitu.gif

demo/qc/finale/finale_insitu.mp4

Gates applied: no_behavioural_pass.