One author wrote all 46 commits, 46 of 48 first-parent commits were pushed directly to main, and the repository has no LICENSE file (the README says "MIT — see LICENSE"), no tests, no releases and no CI beyond a documentation deployment. The README still describes the removed csv_convert/ and full-sim-pipeline/ directories, and the pipeline code now lives in an unlicensed submodule (JeffersonLab/msf-simulation-pipeline) outside the eic organization. The established practices are a hosted VitePress site that documents the pipeline, the background mixing and the trk_hits CSV schema, and a dataset catalog that tracks the ePIC campaigns on Rucio up to 26.07.1.
Assessment by criterion
Code health & engineering practices 0.6
1
Initial · confidence high
The history is public, but only 2 of 48 first-parent commits in 12 months came from PRs (both Dependabot), no PR was reviewed, and main has no branch protection or ruleset.
Evidence (4)
Gaps to the next level
- Under 80% of default-branch changes arrive through PRs.
- No merged PR has a review from someone other than the author.
Actions
- high S Enable a ruleset on
main that requires a pull request with one approving review, and route all changes through PRs.
1
Continuous integration eng.ci
Initial · confidence high
The only workflow builds and deploys the VitePress docs on pushes to main; it has no pull_request trigger and runs no Python tests or scripts.
Evidence (3)
Gaps to the next level
- No workflow runs on pull requests.
- CI does not run any test suite or the analysis scripts.
Actions
- medium S Add
.github/workflows/test.yml triggered on pull_request and push to main that runs uv sync and uv run pytest. - low S Add a
pull_request trigger with a build-only job (no deploy) to .github/workflows/documentation.yml.
0
Absent · confidence high
The repository contains no test files and no test framework; scripts/check_podio_files.py validates data files and is not a test of the code.
Evidence (2)
code.test_files = 0code.test_frameworks = []
Gaps to the next level
- No automated tests for the scripts in
scripts/ or analyses/.
Actions
- high S Add pytest tests in
tests/ for concat_runs_with_unique_events in scripts/merge_reco_particles_to_feather.py and the DID grouping in scripts/summarize_rucio_dids.py, using small fixture CSV and text files.
0
Absent · confidence high
No formatter, linter, type checker or pre-commit configuration exists; pandas-stubs is declared as a dependency but no mypy configuration uses it.
Evidence (3)
files.python_lint = []files.pre_commit = []files.mypy = []
Gaps to the next level
- No formatter or linter configured or enforced.
Actions
- high S Add
.pre-commit-config.yaml with ruff and ruff-format hooks and enable pre-commit.ci on the repository.
1
Architecture & language standards eng.modularity
Initial · confidence medium
pyproject.toml defines a uv environment requiring Python 3.12 or later, but it has no build-system or package, and the code is a set of standalone argparse scripts with no shared module or installable entry points.
Evidence (3)
Gaps to the next level
- Scripts are not organized as an installable package with defined interfaces.
- The background campaign config in the submodule hard-codes a user directory and a local
.sif image.
Actions
- medium M Add a
[build-system] table and move scripts/*.py into a package with [project.scripts] entry points.
Documentation & usability 1.0
1
Initial · confidence high
The hosted docs give run commands for the converters and the time-vs-z analysis, but the README describes csv_convert/ and full-sim-pipeline/ directories that no longer exist, and no dependency versions or eic-shell install route are given for the Python tools.
Evidence (4)
Gaps to the next level
- README layout and quick start refer to removed directories.
- Install instructions do not name dependency versions or document setup inside eic-shell.
docs/full-sim-pipeline.md links the submodule as eic/simulation-pipeline, which returns 404.
Actions
- high S Rewrite the README layout and quick start for the current tree (
simulation-pipeline/, scripts/, analyses/) and add an "Installation" section covering uv sync and eic-shell with versions. - low S Fix the submodule link in
docs/full-sim-pipeline.md to the URL in .gitmodules.
1
Developer & API documentation doc.developer
Initial · confidence high
Most scripts have module and function docstrings and the docs site has pipeline overview diagrams, but no API reference is generated.
Evidence (3)
Gaps to the next level
- No generated API documentation.
Actions
- medium M Generate API pages for
scripts/ and analyses/ (for example with mkdocstrings or pdoc) in the docs build in .github/workflows/documentation.yml.
1
Initial · confidence medium
analyses/README.md has a three-step note on adding an analysis (pointing to a removed csv_convert/pyproject.toml), and the eic organization PR and issue templates apply; there is no CONTRIBUTING file covering setup, tests, conventions or the PR process.
Evidence (3)
Gaps to the next level
- No CONTRIBUTING describing environment setup, testing, conventions and PR process.
Actions
- medium S Add
CONTRIBUTING.md covering uv sync, running scripts in eic-shell, the submodule update procedure and the PR process.
1
Initial · confidence low
No issues and no non-bot PRs were opened in 12 months, so no response time can be measured; Dependabot PR #5 has been open since 2026-08-02 without action and no triage process exists.
Evidence (3)
Gaps to the next level
- No public record of responses to issues or contributor PRs, and no labels or triage process.
Actions
- medium S Link the issue tracker from the docs site as the place to report dataset or script problems, and triage new issues with labels within a week.
0
Absent · confidence high
One author made all commits in 24 months and no external PR has been merged.
Evidence (2)
git.authors_24m = 1prs.external_fraction_12m = null
Gaps to the next level
Actions
- high M Recruit a co-developer from the ePIC background or AI/ML working group and route their changes through PRs.
0
Knowledge concentration (bus factor) com.bus-factor
Absent · confidence high
One author wrote 100% of commits in 24 months and nobody else has reviewed or merged changes.
Evidence (3)
git.bus_factor_50_24m = 1git.top_author_share_24m = 1.0prs.distinct_reviewers_12m = 0
Gaps to the next level
- No second person reviews, merges or is named as owner.
Actions
- high S Add
CODEOWNERS naming two maintainers and have the second maintainer review every PR.
0
Absent · confidence medium
Neither the README, the docs site nor a CODEOWNERS file names the maintainers, and there is no decision process, roadmap or milestone.
Evidence (2)
files.codeowners = []files.governance = []
Gaps to the next level
- Maintainers are not identified in the repository.
Actions
- high S Add a "Maintainers" section to the README naming the maintainers and the owning ePIC working group.
1
Code of conduct & user support com.conduct
Initial · confidence medium
The eic organization issue-template configuration links the ePIC Mattermost for questions, but no code of conduct applies at repository or organization level.
Evidence (2)
Gaps to the next level
- No code of conduct with a reporting contact.
Actions
- high S Add
CODE_OF_CONDUCT.md with a reporting contact, or link the ePIC collaboration code of conduct from the README.
Infrastructure & distribution 0.8
1
Initial · confidence low
The Python tools run from the repository through uv run against pyproject.toml, as the docs show, but there is no package or recipe in any package manager.
Evidence (3)
Gaps to the next level
- No package recipe (PyPI, eic-spack, conda-forge).
Actions
- medium M After packaging the scripts, publish the package to PyPI from a tag-triggered release workflow.
0
Absent · confidence high
The repository has no tags or releases; users consume main.
Evidence (2)
releases.count_total = 0git.tags_total = 0
Gaps to the next level
Actions
- high S Tag a first release (for example
v0.1.0, matching pyproject.toml) with generated release notes, and state the version scheme in the README.
Dependencies are listed in pyproject.toml without version constraints except keras>=3.0; several (keras, jax, scikit-learn, duckdb, submitit) are not imported anywhere, and pyarrow, needed by to_feather, is missing.
Evidence (4)
Gaps to the next level
- No minimum versions on Python dependencies and no Python lockfile.
- Declared set does not match what the code uses.
Actions
- medium S Add minimum versions to every dependency in
pyproject.toml, drop unused ones, add pyarrow, and commit uv.lock.
1
Initial · confidence medium
The docs describe pinned containers and per-job seeds, and the submodule config config-off-26-06.yaml pins eic_xl:26.06.0-stable, but the background campaign config uses a non-public .sif in a user directory and the Python environment has no lockfile.
Evidence (4)
Gaps to the next level
- Not every campaign environment is publicly reproducible, and the Python environment is not locked.
- Seeds and configuration are not recorded in the produced CSV outputs.
Actions
- medium S Pin every campaign config to a public
eic_xl tag on CVMFS and commit uv.lock for the Python tools.
1
Portability & heterogeneous computing dist.portability
Initial · confidence medium
Nothing beyond the docs site is built or tested in CI, and the production path documented is the JLab SLURM farm with /work and /farm_out paths set in the campaign configs.
Evidence (3)
Gaps to the next level
- No platform or Python-version matrix is tested.
Actions
- medium S Run the test workflow on Python 3.12 and 3.13 (the eic-shell version) in a matrix.
EIC ecosystem integration 1.5
2
Reuse of EIC-supported components eic.reuse
Established · confidence medium
The chain uses afterburner, npsim, EICrecon and the official background cocktails, the converters read EDM4eic through podio, and the Python tools read podio files with uproot; no parallel implementation was found, but nothing is contributed upstream or reused by other EIC software.
Evidence (3)
Gaps to the next level
- No upstream contributions or reuse by other EIC repositories.
Actions
- low M Contribute the EDM4eic-to-CSV flattening as a benchmark or tool in an EIC repository such as
eic/detector_benchmarks.
1
Data formats & interoperability eic.data-model
Initial · confidence medium
Inputs are EDM4eic/EDM4hep podio files, but the CSV outputs have a documented schema only for trk_hits; the other converters are documented as "read their .cxx headers".
Evidence (2)
Gaps to the next level
- CSV schemas for the reco_particles, calo_clusters, mc_particles and other roles are undocumented.
Actions
- medium S Document the column layout of every converter role in
docs/data-format.md, including the EDM4eic version of the source files.
1
Initial · confidence medium
The docs say to run the converters inside the eic_xl container, but the Python tools use a separate uv environment and no CI runs in an eic container image.
Evidence (2)
Gaps to the next level
- No CI job runs in an eic container image.
- Running the Python tools in eic-shell is not documented.
Actions
- medium S Add a CI job using
eic/run-cvmfs-osg-eic-shell that runs the tests and scripts/check_podio_files.py on a small EDM4eic sample.
2
Currency with the EIC stack eic.currency
Established · confidence low
The dataset catalog covers the 26.07.1 ePIC campaign and the CSV campaign config pins eic_xl:26.06.0-stable; no incompatibility issues exist, but no CI checks new stack releases.
Evidence (2)
Gaps to the next level
- Adaptation to new component releases is not checked automatically.
Actions
- medium S Run the eic-shell CI job against
eic_xl:nightly on a weekly schedule.
Impact & long-term viability 0.2
1
Initial · confidence medium
The README and docs footer state MIT, but no LICENSE file exists, no SPDX identifier is detected, and the bundled simulation-pipeline submodule has no license.
Evidence (3)
Gaps to the next level
- No LICENSE file with the MIT text, and no license in
pyproject.toml. - The submodule code has no license.
Actions
- high S Add
LICENSE with the MIT text, set license = "MIT" in pyproject.toml, and ask the submodule owners to add a license.
0
Absent · confidence high
There is no CITATION.cff, DOI, author list or citation request.
Evidence (2)
files.citation_cff = []files.zenodo_json = []
Gaps to the next level
Actions
- high S Add
CITATION.cff listing the authors and enable the Zenodo–GitHub integration.
0
Adoption & downstream use via.adoption
Absent · confidence medium
No EIC repository, benchmark or campaign references the project; the only code search hit is the shared pipeline README, and the single fork has no commits of its own.
Evidence (3)
Gaps to the next level
- No public evidence of use beyond the author.
Actions
- high S List the analyses and groups using the datasets in the README and link the docs site from the ePIC background working group pages.
0
Institutional backing & continuity via.support
Absent · confidence low
The repository is in the eic organization, but no maintainer, affiliation, owning ePIC body or funding is stated, and no commit email domain is recorded.
Evidence (2)
Gaps to the next level
- No identifiable maintainer affiliation or institutional commitment.
Actions
- high S State the maintainers' institutions and the owning ePIC working group in the README.