Reformatting the software toward a distributable version

[JohannesGawron]

This pull request reformats the software to support pixi and a distribution as a package. The most important changes are grouped below by theme:

Documentation Overhaul:

• Completely rewrote and expanded the main README.md to provide a clear project overview, installation instructions, detailed usage for CLI tools, repository structure, development workflow, and badges for linting, license, and Python version. This makes onboarding and usage much more accessible.
• Removed the outdated and redundant mixmax/README.md, consolidating all relevant information into the main README.md.
• Removed placeholder content from benchmarking_pipeline/config/README.md to clean up the repository and avoid confusion.

Notebook Management:

• Updated .gitignore in notebooks/ to exclude Quarto build artifacts and output files, ensuring a clean repository and avoiding accidental commits of generated content.

Restructuring of project

[Copilot]

Pull request overview

Repackages mixmax for distribution, expands documentation/tutorials, and adds a benchmarking workflow with supporting scripts and tests.

Changes:

• Adds modern packaging, dependency, linting, typing, and version configuration.
• Introduces three Quarto tutorials and expanded project/workflow documentation.
• Adds a Snakemake benchmarking pipeline, simulation utilities, fixtures, and tests.

Reviewed changes

Copilot reviewed 22 out of 68 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
.gitignore	Expands generated-file exclusions
README.md	Rewrites installation and usage docs
benchmarking_pipeline/config/README.md	Removes placeholder documentation
mixmax/README.md	Removes superseded documentation
notebooks/.gitignore	Ignores Quarto artifacts
notebooks/_quarto.yml	Configures tutorial website
notebooks/01_introduction.qmd	Adds Bayesian introduction
notebooks/02_kalman_filter.qmd	Adds Kalman filter tutorial
notebooks/03_diagnostics.qmd	Adds posterior diagnostics tutorial
pixi.toml	Defines environment and tasks
pyproject.toml	Adds package/build configuration
pyrightconfig.json	Configures local type checking
src/mixmax/__init__.py	Exposes package version
src/mixmax/_version.py	Adds version loading
src/mixmax/_version_generated.py	Adds generated version data
src/mixmax/create_demultiplexing_scheme.py	Revises CLI input handling
src/mixmax/match_samples.py	Adds sample-matching CLI
tests/pools_test.txt	Adds pooling fixture
tests/sample_list_test.txt	Adds sample-list fixture
tests/split_loom_data_test_split1.loom	Adds split fixture
tests/split_loom_data_test_split2.loom	Adds split fixture
tests/test_common.py	Tests workflow helpers
tests/test_create_demultiplexing_scheme.py	Tests scheme generation
tests/test_mosaic_processing.py	Tests pseudobulk VAF handling
tests/test_split_loom_files.py	Tests Loom splitting
workflow/README.md	Documents benchmarking workflow
workflow/Snakefile	Defines benchmarking pipeline
workflow/config/template.yaml	Adds workflow configuration template
workflow/envs/loom.yml	Defines Loom environment
workflow/envs/mosaic.yml	Defines mosaic environment
workflow/envs/sample_assignment.yml	Defines assignment environment
workflow/launch_pipeline.py	Adds Slurm launcher
workflow/launcher_loop.sh	Launches multiple seeded runs
workflow/rules/common.smk	Adds shared workflow helpers
workflow/sandbox/compute_performance_score.py	Computes simulation metrics
workflow/sandbox/figure3.py	Generates performance figures
workflow/sandbox/figure4.py	Generates parameter figures
workflow/sandbox/generate_parameter_space.py	Generates parameter combinations
workflow/sandbox/parameter_space.tsv	Defines benchmark parameters
workflow/sandbox/results_for_non_robust.csv	Adds non-robust results
workflow/sandbox/results_for_robust.csv	Adds robust results
workflow/scripts/__init__.py	Marks scripts package
workflow/scripts/assign_subsample_simulation.py	Clarifies output format
workflow/scripts/compare_distances.py	Improves boolean parsing and plots
workflow/scripts/create_demultiplexing_scheme.py	Improves boolean parsing
workflow/scripts/demo_tape.py	Adds demultiplexing implementation
workflow/scripts/demultiplex_distance.py	Adds library-depth visualization
workflow/scripts/find_multiplexing_scheme_ILP.py	Adds ILP scheme optimization
workflow/scripts/get_input_samples.py	Adds seeded sample selection
workflow/scripts/gurobi.log	Adds generated optimizer log
workflow/scripts/split_loom_files.py	Adds Loom splitting utility

Suppressed comments (8)

src/mixmax/create_demultiplexing_scheme.py:194

• When --input_samples is omitted (the documented --n_samples mode), input_samples is never assigned, yet it is always passed here, so the CLI raises UnboundLocalError instead of writing a scheme. Define the intended output for a count-only invocation, or require and validate the sample list before this call.
  src/mixmax/match_samples.py:62
• type=bool treats every non-empty CLI string as true, including "False"; therefore the README's --robust False command runs robust matching. Parse accepted boolean spellings explicitly, as done in workflow/scripts/compare_distances.py.
  src/mixmax/match_samples.py:83
• This f-string uses the same quote character inside and outside the expression, which is a SyntaxError on Python 3.10 and 3.11 even though both are declared supported. Use different outer quotes so the module can be parsed on all supported versions.
  src/mixmax/match_samples.py:208
• For a valid one-pool input, plt.subplots(1, 1) returns a single Axes, not a 2-D array, so axes[i, j] raises TypeError. Normalize the result to two dimensions before indexing.
  src/mixmax/match_samples.py:226
• For one input pool, this subplots call returns a scalar Axes, so the following axes[i] indexing fails. Normalize it to a one-dimensional array as the workflow copy now does.
  src/mixmax/create_demultiplexing_scheme.py:165
• Adding --input_samples as an alternative does not make --n_samples optional: the parser still declares --n_samples with required=True, so the README's input-file-only invocation is rejected before this branch runs. Make these inputs mutually exclusive and require exactly the mode(s) the implementation supports.
  src/mixmax/create_demultiplexing_scheme.py:160
• --input_dir is now optional, but main always passes it to select_samples_for_pooling, which performs input_dir / filename; omitting it therefore produces a TypeError. Either keep it required whenever concrete sample paths are emitted or define a count-only output mode.
  src/mixmax/match_samples.py:292
• Reassigning sorted_ratios inside a for ... in sorted_ratios loop does not change the iterator already being consumed, so the claimed dynamic reprioritization never occurs; all remaining matrix pairs are processed in the original order. Drive this with a while loop that selects from the newly computed list (and recompute ratios from the still-unused rows/columns).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.