emscan 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
emscan/main.py ADDED
@@ -0,0 +1,591 @@
1
+ import click
2
+
3
+ import emscan
4
+
5
+
6
+ @click.group(
7
+ name="emscan",
8
+ context_settings={"help_option_names": ["-h", "--help"], "show_default": True},
9
+ )
10
+ @click.version_option(version=emscan.__version__)
11
+ @click.option(
12
+ "--db-path",
13
+ type=click.Path(dir_okay=True, file_okay=False),
14
+ default="~/.emdb_projections/",
15
+ help="Where to save/find the database of projections.",
16
+ )
17
+ @click.option(
18
+ "-f", "--overwrite", is_flag=True, help="Overwrite outputs if they exist."
19
+ )
20
+ @click.option("-d", "--dry-run", is_flag=True)
21
+ @click.option(
22
+ "-v",
23
+ "--verbose",
24
+ count=True,
25
+ help="Verbosity level (can be passed multiple times).",
26
+ )
27
+ @click.pass_context
28
+ def cli(ctx, db_path, overwrite, verbose, dry_run):
29
+ """Scan EMDB entries for similar 2D classes by comparing projections."""
30
+ import logging
31
+ from pathlib import Path
32
+
33
+ from rich.logging import RichHandler
34
+
35
+ ctx.ensure_object(dict)
36
+
37
+ ctx.obj["db_path"] = Path(db_path).expanduser().resolve()
38
+ ctx.obj["overwrite"] = overwrite
39
+ ctx.obj["dry_run"] = dry_run
40
+
41
+ logging.basicConfig(
42
+ level=40 - max(verbose * 10, 0),
43
+ format="%(message)s",
44
+ datefmt="[%X]",
45
+ handlers=[RichHandler()],
46
+ )
47
+ log = logging.getLogger("emscan")
48
+ ctx.obj["log"] = log
49
+
50
+
51
+ @cli.command()
52
+ @click.option(
53
+ "-t",
54
+ "--threads",
55
+ default=0,
56
+ help="How many threads to use for projection. If <= 0, guess a good number.",
57
+ )
58
+ @click.option(
59
+ "-h", "--headers", is_flag=True, help="Download or update the entry headers."
60
+ )
61
+ @click.option(
62
+ "-d", "--database", is_flag=True, help="Update the database table itself."
63
+ )
64
+ @click.option(
65
+ "-m",
66
+ "--maps",
67
+ is_flag=True,
68
+ help="Download or update the emdb maps from the available headers.",
69
+ )
70
+ @click.option(
71
+ "-p",
72
+ "--projections",
73
+ is_flag=True,
74
+ help="Generate projections for all the available maps.",
75
+ )
76
+ @click.option(
77
+ "--keep-maps",
78
+ is_flag=True,
79
+ help="Keep the downloaded maps after projecting (for development purposes).",
80
+ )
81
+ @click.pass_context
82
+ def gen_db(
83
+ ctx,
84
+ threads,
85
+ headers,
86
+ database,
87
+ maps,
88
+ projections,
89
+ keep_maps,
90
+ ):
91
+ """Generate the projection database.
92
+
93
+ If none of l, d, m, or p optionns are passed, all are executed.
94
+ Otherwise, only the the options passed.
95
+ """
96
+ import os
97
+ from itertools import chain
98
+
99
+ import pandas as pd
100
+ from rich.progress import Progress, ProgressColumn
101
+ from rich.text import Text
102
+
103
+ from emscan._functions import (
104
+ download_headers,
105
+ fetch_maps,
106
+ generate_db_summary,
107
+ get_entries_to_process,
108
+ project_maps,
109
+ )
110
+
111
+ db_path = ctx.obj["db_path"]
112
+ overwrite = ctx.obj["overwrite"]
113
+ log = ctx.obj["log"]
114
+ dry_run = ctx.obj["dry_run"]
115
+
116
+ full = not any((headers, database, maps, projections))
117
+
118
+ threads = threads if threads > 0 else max(1, (os.cpu_count() or 1) // 4)
119
+
120
+ class CompletedColumn(ProgressColumn):
121
+ """Add progress count even when no total is available."""
122
+
123
+ def render(self, task):
124
+ if task.total is None:
125
+ return Text(f"{task.completed}/?", style="cyan")
126
+ return Text("")
127
+
128
+ with Progress(*Progress.get_default_columns(), CompletedColumn(), disable=False) as prog:
129
+ if full or headers:
130
+ no_header = download_headers(prog, db_path=db_path, dry_run=dry_run)
131
+ if no_header:
132
+ for entry_id in no_header:
133
+ log.info(f"entry {entry_id} failed.")
134
+
135
+ if full or database:
136
+ generate_db_summary(prog=prog, db_path=db_path, log=log, dry_run=dry_run)
137
+
138
+ if full or maps or projections:
139
+ to_download, to_extract, to_project, to_delete = get_entries_to_process(
140
+ prog=prog,
141
+ db_path=db_path,
142
+ log=log,
143
+ overwrite=overwrite,
144
+ )
145
+ if (full or projections) and not keep_maps:
146
+ if dry_run:
147
+ print(f"Will delete {len(to_delete)} maps with existing projections")
148
+ else:
149
+ for map_path in to_delete:
150
+ map_path.unlink(missing_ok=True)
151
+
152
+ if full or maps:
153
+ failed = []
154
+ fetched = fetch_maps(
155
+ prog=prog,
156
+ db_path=db_path,
157
+ to_download=to_download,
158
+ to_extract=to_extract,
159
+ dry_run=dry_run,
160
+ threads=threads,
161
+ failed=failed,
162
+ )
163
+ if full or projections:
164
+ # project previously extracted maps first, then the downloaded ones as they arrive
165
+ extracted = {gz.with_suffix("") for gz in to_extract}
166
+ to_project_ordered = chain((m for m in to_project if m not in extracted), fetched)
167
+ project_maps(
168
+ prog=prog,
169
+ maps=to_project_ordered,
170
+ log=log,
171
+ dry_run=dry_run,
172
+ threads=threads,
173
+ keep_maps=keep_maps,
174
+ total=len(to_project),
175
+ )
176
+ else:
177
+ for _ in fetched:
178
+ pass
179
+
180
+ if failed:
181
+ log.warning("some headers are outdated, updating database")
182
+ for entry_id in failed:
183
+ log.info(f"deleting missing entry: {entry_id}")
184
+ header = db_path / f"emd-{entry_id:04}-v30.xml"
185
+ map_path = db_path / f"emd_{entry_id:04}.map"
186
+ proj_path = db_path / f"{entry_id:04}.pt"
187
+
188
+ header.unlink(missing_ok=True)
189
+ map_path.unlink(missing_ok=True)
190
+ proj_path.unlink(missing_ok=True)
191
+
192
+ db = pd.read_csv(
193
+ db_path / "database_summary.csv", sep="\t", index_col=0
194
+ )
195
+ db.drop(failed, inplace=True)
196
+ db.to_csv(
197
+ db_path / "database_summary.csv",
198
+ sep="\t",
199
+ header=True,
200
+ index=True,
201
+ na_rep="NaN",
202
+ )
203
+
204
+ elif projections:
205
+ project_maps(
206
+ prog=prog,
207
+ maps=to_project,
208
+ log=log,
209
+ dry_run=dry_run,
210
+ threads=threads,
211
+ keep_maps=keep_maps,
212
+ total=len(to_project),
213
+ )
214
+
215
+
216
+ @cli.command()
217
+ @click.argument(
218
+ "classes", type=click.Path(exists=True, dir_okay=False, resolve_path=True)
219
+ )
220
+ @click.option(
221
+ "-a",
222
+ "--angle",
223
+ type=float,
224
+ default=2,
225
+ help="Angle step in degrees for cross correlation rotational search",
226
+ )
227
+ @click.option(
228
+ "--fraction",
229
+ type=float,
230
+ default=1,
231
+ )
232
+ @click.pass_context
233
+ def scan(
234
+ ctx,
235
+ classes,
236
+ angle,
237
+ fraction,
238
+ ):
239
+ """Find emdb entries similar to the given 2D classes."""
240
+ from concurrent.futures import ProcessPoolExecutor, as_completed
241
+ from pathlib import Path
242
+
243
+ import pandas as pd
244
+ import torch
245
+ from rich import print
246
+ from rich.progress import Progress
247
+ from torch.multiprocessing import set_start_method
248
+
249
+ from emscan._functions import compute_ncc
250
+
251
+ db_path = ctx.obj["db_path"]
252
+ overwrite = ctx.obj["overwrite"]
253
+ log = ctx.obj["log"]
254
+
255
+ output = Path(classes).with_suffix(".csv")
256
+
257
+ print("Loading database list...")
258
+ db = pd.read_csv(db_path / "database_summary.csv", sep="\t", index_col=0)
259
+ entries = [db_path / f"{entry_id:04}.pt" for entry_id in db.index]
260
+
261
+ add_header = True
262
+ if output.exists():
263
+ if overwrite:
264
+ log.warning(f"{output.name} exists and will be overwritten.")
265
+ else:
266
+ exist = pd.read_csv(output, sep="\t", index_col=0).index
267
+ log.warning(
268
+ f"{output.name} already esists: ({len(exist)}/{len(entries)}) entries already processed."
269
+ )
270
+
271
+ entries = [entry for entry in entries if int(entry.stem) not in exist]
272
+ add_header = False
273
+
274
+ set_start_method("spawn", force=True)
275
+ use_cuda = torch.cuda.is_available()
276
+ devices = torch.cuda.device_count() if use_cuda else 1
277
+
278
+ errors = []
279
+ with Progress() as prog:
280
+ task = prog.add_task(description="Correlating...", total=len(entries))
281
+ # with Pool(processes=devices) as pool:
282
+ with ProcessPoolExecutor(max_workers=devices) as pool:
283
+ # submit in batches so the pending queue stays small on large databases
284
+ batch_size = max(devices * 4, 1)
285
+ for start in range(0, len(entries), batch_size):
286
+ batch = entries[start : start + batch_size]
287
+ futures = {
288
+ pool.submit(
289
+ compute_ncc,
290
+ classes,
291
+ entry,
292
+ angle,
293
+ f"cuda:{idx % devices}" if use_cuda else "cpu",
294
+ fraction,
295
+ ): entry
296
+ for idx, entry in enumerate(batch, start)
297
+ }
298
+ for fut in as_completed(futures):
299
+ entry_id = futures[fut].stem
300
+ if fut.exception():
301
+ err = fut.exception()
302
+ err.add_note(entry_id)
303
+ errors.append(err)
304
+ log.warning(f"failed correlating {entry_id}: {err}")
305
+ else:
306
+ cc_dict = fut.result()
307
+ log.info(f"finished correlating to {entry_id}")
308
+ for k, v in cc_dict.items():
309
+ if k != "values":
310
+ out = output.with_stem(f"{output.stem}_{k}")
311
+ else:
312
+ out = output
313
+ if out.exists() and overwrite:
314
+ out.unlink()
315
+ df = pd.DataFrame(
316
+ v, index=pd.Index([entry_id], name="entry")
317
+ )
318
+ df.to_csv(
319
+ out, sep="\t", header=add_header, index=True, mode="a"
320
+ )
321
+ add_header = False # so we only add once
322
+ overwrite = False
323
+ prog.update(task, advance=1)
324
+
325
+ if errors:
326
+ raise ExceptionGroup("Some correlations failed", errors)
327
+
328
+
329
+ @cli.command()
330
+ @click.argument(
331
+ "class_image",
332
+ type=click.Path(exists=True, dir_okay=False, resolve_path=True),
333
+ )
334
+ @click.option(
335
+ "-s",
336
+ "--selected-classes",
337
+ type=str,
338
+ help="comma separated list of classes to select. All if empty.",
339
+ )
340
+ @click.option("-n", "--top-n", default=30, type=int, help="How many top hits to show.")
341
+ @click.option(
342
+ "--fraction",
343
+ type=float,
344
+ default=1,
345
+ )
346
+ @click.option(
347
+ "-r",
348
+ "--resolution-threshold",
349
+ type=float,
350
+ help="discard entries with resolution worse than this threshold",
351
+ )
352
+ @click.pass_context
353
+ def show(
354
+ ctx,
355
+ class_image,
356
+ selected_classes,
357
+ top_n,
358
+ fraction,
359
+ resolution_threshold,
360
+ ):
361
+ """Parse correlation results and show related emdb entries and plots."""
362
+ import webbrowser
363
+ from inspect import cleandoc
364
+ from pathlib import Path
365
+
366
+ import mrcfile
367
+ import napari
368
+ import numpy as np
369
+ import pandas as pd
370
+ import torch
371
+ from rich import print
372
+
373
+ from emscan._functions import load_class_data, pad_to, rotate_by
374
+
375
+ db_path = ctx.obj["db_path"]
376
+ ctx.obj["overwrite"]
377
+
378
+ correlation_results = Path(class_image).with_suffix('.csv')
379
+ df = pd.read_csv(correlation_results, sep="\t", index_col="entry")
380
+ df_indices = pd.read_csv(
381
+ correlation_results.with_stem(f"{correlation_results.stem}_indices"),
382
+ sep="\t",
383
+ index_col="entry",
384
+ )
385
+ df_angles = pd.read_csv(
386
+ correlation_results.with_stem(f"{correlation_results.stem}_angles"),
387
+ sep="\t",
388
+ index_col="entry",
389
+ )
390
+
391
+ if resolution_threshold is not None:
392
+ db = pd.read_csv(db_path / "database_summary.csv", sep="\t", index_col=0)
393
+ keep = db.index[db["resolution"] <= resolution_threshold] # also excludes NaNs
394
+ keep = keep[keep.isin(df.index)]
395
+ df = df.loc[keep]
396
+
397
+ df.dropna(how="any", inplace=True)
398
+
399
+ df_indices = df_indices.loc[df.index]
400
+ df_angles = df_angles.loc[df.index]
401
+
402
+ df_selected = pd.DataFrame()
403
+ if not selected_classes:
404
+ selected_classes = "all"
405
+ selected = list(df.columns)
406
+ else:
407
+ selected = selected_classes.split(",")
408
+
409
+ df_selected[selected_classes] = df[selected].mean(axis=1)
410
+
411
+ # select best scoring hits from angles and indices
412
+ # (see https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#looking-up-values-by-index-column-labels)
413
+ best_hits = df[selected].idxmax(axis=1)
414
+ df_indices["col"] = best_hits
415
+ idx, selected = pd.factorize(df_indices["col"])
416
+ df_indices["best"] = df_indices.reindex(selected, axis=1).to_numpy()[
417
+ np.arange(len(df_indices)), idx
418
+ ]
419
+ df_angles["col"] = best_hits
420
+ idx, selected = pd.factorize(df_angles["col"])
421
+ df_angles["best"] = df_angles.reindex(selected, axis=1).to_numpy()[
422
+ np.arange(len(df_angles)), idx
423
+ ]
424
+
425
+ df_top = pd.DataFrame()
426
+ df_top.index.name = "rank"
427
+ for col in df_selected:
428
+ top_n_idx = df_selected[col].sort_values()[::-1].index[:top_n]
429
+ top_n_entries = df_selected[col].loc[top_n_idx].reset_index()
430
+ df_top[[f"{col}_entry", f"{col}_cc"]] = top_n_entries
431
+
432
+ print(df_top)
433
+ v = napari.Viewer()
434
+
435
+ # preserve order with pd.unique
436
+ uniq_entries = pd.unique(df_top.iloc[:, 0])
437
+
438
+ imgs = {}
439
+ for entry in uniq_entries:
440
+ img = torch.load(db_path / f"{entry:04}.pt", weights_only=True)
441
+ img = img[df_indices.loc[entry, "best"]]
442
+ angle = df_angles.loc[entry, "best"]
443
+ if np.sign(angle) == -1:
444
+ img = img.T
445
+ imgs[entry] = rotate_by(img, -np.abs(angle))
446
+
447
+ max_size = np.max([img.shape for img in imgs.values()], axis=0)
448
+ for entry, img in imgs.items():
449
+ imgs[entry] = np.array(pad_to(img, max_size, dim=(0, 1))).real.squeeze()
450
+
451
+ classes_data = load_class_data(class_image, device="cpu", fraction=fraction)
452
+ classes_data = np.array(pad_to(classes_data, (1, *max_size), dim=(1, 2)).real)
453
+ for i, d in enumerate(classes_data):
454
+ if str(i) in selected:
455
+ layer = v.add_image(d, name=f"class {i}", interpolation2d="spline36")
456
+ layer.name_overlay.visible = True
457
+
458
+ for entry, img in imgs.items():
459
+ layer = v.add_image(img, name=f"{entry:04}", interpolation2d="spline36")
460
+ layer.name_overlay.visible = True
461
+
462
+ def get_correct_entry(viewer, event):
463
+ event.handled = True
464
+ if event.viewbox == (0, 0):
465
+ return None
466
+ layers = viewer.canvas.grid.contents_at(event.viewbox, viewer.layers)
467
+ if layers:
468
+ return viewer.layers[layers[0]].name
469
+ return None
470
+
471
+ def open_entry(viewer, event):
472
+ if event.modifiers:
473
+ return
474
+ entry = get_correct_entry(viewer, event)
475
+ if entry is None:
476
+ return
477
+ webbrowser.open(f"https://www.ebi.ac.uk/emdb/EMD-{entry}")
478
+
479
+ def make_proj_mrc(viewer, event):
480
+ if "Control" not in event.modifiers:
481
+ return
482
+ entry = get_correct_entry(viewer, event)
483
+ if entry is None:
484
+ return
485
+ filename = f"emdb_{entry}_projections.mrc"
486
+ img = torch.load(db_path / f"{int(entry):04}.pt", weights_only=True)
487
+ with mrcfile.new(filename, data=np.array(img)) as mrc:
488
+ mrc.voxel_size = 4
489
+ mrc.set_image_stack()
490
+ napari.utils.notifications.show_info(f"Saved projections as {filename}")
491
+
492
+ def open_stack(viewer, event):
493
+ if "Shift" not in event.modifiers:
494
+ return
495
+ entry = get_correct_entry(viewer, event)
496
+ if entry is None:
497
+ return
498
+ img = torch.load(db_path / f"{int(entry):04}.pt", weights_only=True)
499
+ v_ = napari.Viewer()
500
+ for sl in img:
501
+ v_.add_image(np.array(sl), interpolation2d="spline36")
502
+ v_.canvas.grid.enabled = True
503
+
504
+ print(
505
+ cleandoc(
506
+ """
507
+ TIPS:
508
+ - double click an image to open its emdb page
509
+ - ctrl+click to create projection stack
510
+ - shift+click to open stack exploded in new window
511
+ """
512
+ )
513
+ )
514
+
515
+ v.mouse_double_click_callbacks.append(open_entry)
516
+ v.mouse_drag_callbacks.append(make_proj_mrc)
517
+ v.mouse_drag_callbacks.append(open_stack)
518
+
519
+ v.canvas.grid.enabled = True
520
+ v.reset_view()
521
+ napari.run()
522
+
523
+
524
+ @cli.command()
525
+ @click.argument(
526
+ "entries",
527
+ nargs=-1,
528
+ type=str,
529
+ )
530
+ @click.option(
531
+ "-c",
532
+ "--class-image",
533
+ type=click.Path(exists=True, dir_okay=False, resolve_path=True),
534
+ help="Image to load to compare to.",
535
+ )
536
+ @click.pass_context
537
+ def view_entries(ctx, entries, class_image):
538
+ """Display projections for the requested entries."""
539
+ import napari
540
+ import numpy as np
541
+ import torch
542
+
543
+ from ._functions import load_class_data, pad_to
544
+
545
+ db_path = ctx.obj["db_path"]
546
+
547
+ v = napari.Viewer()
548
+
549
+ imgs = {}
550
+ if class_image is not None:
551
+ classes_data = load_class_data(class_image, device="cpu")
552
+ for i, d in enumerate(classes_data):
553
+ imgs[f"class {i}"] = d[None]
554
+ for entry in entries:
555
+ key = f"{int(entry):04}"
556
+ imgs[key] = torch.load(db_path / f"{key}.pt", weights_only=True)
557
+ max_size = np.max([img.shape for img in imgs.values()], axis=0)
558
+ for entry, img in imgs.items():
559
+ img = np.array(pad_to(img, max_size, dim=(1, 2))).real.squeeze()
560
+ layer = v.add_image(img, name=entry, interpolation2d="spline36")
561
+ layer.name_overlay.visible = True
562
+
563
+ v.canvas.grid.enabled = True
564
+ v.reset_view()
565
+ napari.run()
566
+
567
+
568
+ @cli.command()
569
+ @click.argument(
570
+ "map_file",
571
+ type=click.Path(exists=True, dir_okay=False, resolve_path=True),
572
+ )
573
+ @click.pass_context
574
+ def project(ctx, map_file):
575
+ """Generate rotated templates from the given map."""
576
+ from pathlib import Path
577
+
578
+ from ._functions import _project_map
579
+
580
+ overwrite = ctx.obj["overwrite"]
581
+
582
+ map_file = Path(map_file)
583
+ proj = map_file.with_stem(map_file.stem + "_proj")
584
+ if proj.exists() and not overwrite:
585
+ raise FileExistsError(proj)
586
+
587
+ _project_map(map_file, proj, save_as_mrc=True)
588
+
589
+
590
+ if __name__ == "__main__":
591
+ cli()
@@ -0,0 +1,121 @@
1
+ Metadata-Version: 2.5
2
+ Name: emscan
3
+ Version: 1.0.0
4
+ Summary: package description.
5
+ Project-URL: homepage, https://github.com/brisvag/emscan
6
+ Project-URL: repository, https://github.com/brisvag/emscan
7
+ Author-email: Lorenzo Gaifas <brisvag@gmail.com>
8
+ License: GPLv3
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
12
+ Classifier: Natural Language :: English
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Requires-Python: >=3.11
18
+ Requires-Dist: click
19
+ Requires-Dist: morphosamplers>=0.0.13
20
+ Requires-Dist: mrcfile
21
+ Requires-Dist: napari[all]>=0.10.0
22
+ Requires-Dist: numpy
23
+ Requires-Dist: pandas
24
+ Requires-Dist: pydantic
25
+ Requires-Dist: pyopengl-accelerate
26
+ Requires-Dist: rich
27
+ Requires-Dist: scipy
28
+ Requires-Dist: sh
29
+ Requires-Dist: torch
30
+ Requires-Dist: torchvision
31
+ Requires-Dist: xmltodict
32
+ Provides-Extra: dev
33
+ Requires-Dist: black; extra == 'dev'
34
+ Requires-Dist: ipython; extra == 'dev'
35
+ Requires-Dist: pdbpp; extra == 'dev'
36
+ Requires-Dist: pre-commit; extra == 'dev'
37
+ Requires-Dist: pytest; extra == 'dev'
38
+ Requires-Dist: pytest-cov; extra == 'dev'
39
+ Requires-Dist: rich; extra == 'dev'
40
+ Requires-Dist: ruff; extra == 'dev'
41
+ Provides-Extra: test
42
+ Requires-Dist: pytest-cov; extra == 'test'
43
+ Requires-Dist: pytest>=6.0; extra == 'test'
44
+ Description-Content-Type: text/markdown
45
+
46
+ # emscan
47
+
48
+ [![License](https://img.shields.io/pypi/l/emscan.svg?color=green)](https://github.com/brisvag/emscan/raw/main/LICENSE)
49
+ [![PyPI](https://img.shields.io/pypi/v/emscan.svg?color=green)](https://pypi.org/project/emscan)
50
+ [![Python Version](https://img.shields.io/pypi/pyversions/emscan.svg?color=green)](https://python.org)
51
+ [![CI](https://github.com/brisvag/emscan/actions/workflows/ci.yml/badge.svg)](https://github.com/brisvag/emscan/actions/workflows/ci.yml)
52
+ [![codecov](https://codecov.io/gh/brisvag/emscan/branch/main/graph/badge.svg)](https://codecov.io/gh/brisvag/emscan)
53
+
54
+ emscan is a command line and GUI tool that can be used to cross-correlate 2D projections of unkown objects against the entirety[^1] of the [EMDB](https://www.ebi.ac.uk/emdb). For example, it can be used to find existing homologous (also partial) complexes of unknown particle picks from a cell-extract shotgun cryo-em experiment:
55
+
56
+ <img width="1091" height="656" alt="Results of a scan with a limited database subset containing a real hit." src="https://github.com/user-attachments/assets/d3b23e9e-09d0-4514-972d-a06cbb9814d3" />
57
+
58
+ [^1]: not _quite_: some entries are (clearly) discarded in a few specific cases; some parameters allow tweaking this selection.
59
+
60
+ ## _Disclaimer_
61
+
62
+ emscan requires a lot of time to set up (~days for the first gen-db run) and a large amount of space. While you won't store the whole EMDB (entries are stored downsampled, pre-projected and with limited rotational resolution), it will still use up potentially up to TBs of space.
63
+
64
+ ## Installation
65
+
66
+ Install from pypi via pip (ideally in a new virtual environment):
67
+
68
+ ```sh
69
+ pip install emscan
70
+ ```
71
+
72
+ To verify the installation and print out the usage, run:
73
+
74
+ ```sh
75
+ emscan -h
76
+ ```
77
+
78
+ or for a specific subcommand:
79
+
80
+ ```sh
81
+ emscan gen-db -h
82
+ ```
83
+
84
+ Read the help messages for more specific information on the various parameters.
85
+
86
+ ### Locked dependencies
87
+
88
+ If you read this from the future (hi!) and are having dependency issues, you might prefer to install from source with `uv sync`, using the uv.lock in the repository.
89
+
90
+ ## Usage
91
+
92
+ Using emscan requires a 3 step process:
93
+ 1. Database generation (downloading, extracting, projecting). This requires the longest time and biggest space on dist.
94
+ 2. Scanning (comparing the input 2D image against the whole database). Faster than generation but still a heavy job.
95
+ 3. Inspecting results (visually comparing best hits and investigating the most promising ones). Very fast.
96
+
97
+ Note that all need to know _where_ your database lives. By default it will be put into your home directory under `~/.emdb_projections`, but you might want to provide a different path via `--db-path` to _all commands_.
98
+
99
+ To do so, the 3 main commands are:
100
+
101
+ ```sh
102
+ emscan --db-path <my_db_path> gen-db
103
+ emscan --db-path <my_db_path> scan <some_2d_class>.mrc
104
+ emscan --db-path <my_db_path> show <some_2d_class>.mrc
105
+ ```
106
+
107
+ Note that `<some_2d_class.mrc>` can actually be a stack of 2D classes!
108
+
109
+ Since `scan` saves the correlation results for each class individually, you can mix and match various cross-correlation results when running `show`.
110
+ For example, if you suspect that two or more different classes might be different views of the same object, put all of them in a stack, e.g. `stack.mrc`. In that case:
111
+
112
+ ```sh
113
+ emscan --db-path <my_db_path> show stack.mrc
114
+ ```
115
+
116
+ will show the *combined score* of all classes, meaning that EMDB entries that can match well against *all* classes will be at the top. You can select a different subset (eg, the 0th and 3rd one) of classes to see different combinations with:
117
+
118
+ ```sh
119
+ emscan --db-path <my_db_path> show stack.mrc -s 0,3
120
+ ```
121
+