Hash PLINK export filenames by content-affecting selection parameters to prevent collisions

[rehanxt5]

Summary

The PLINK export methods currently generate output filenames from only a subset of their input parameters. As a result, different export requests can resolve to the same filename prefix even when they produce different data.

This affects:

1. biallelic_snps_to_plink()
2. biallelic_snps_ld_pruned_to_plink()

Problem

At the moment, the filename prefix is built from parameters such as region-level SNP filtering, but it excludes several parameters that also affect the exported dataset contents, including:

• sample_sets
• sample_query
• sample_query_options
• sample_indices
• site_mask
• random_seed

Because these parameters are not reflected in the filename, two calls with different sample-selection inputs can write to the same .bed/.bim/.fam prefix.

Example collision

Two calls such as:

api.biallelic_snps_to_plink(
    output_dir="/plink",
    region="2L",
    n_snps=1000,
    sample_sets=["set_a"],
    random_seed=42,
)

and

api.biallelic_snps_to_plink(
    output_dir="/plink",
    region="2L",
    n_snps=1000,
    sample_sets=["set_b"],
    random_seed=42,
)

can currently generate the same output prefix, despite exporting different sample cohorts.

Why this is a problem

• Different exports can silently overwrite each other.
• Cached/exported file paths are not a stable identifier of dataset contents.
• The risk increases when users run multiple exports into the same output_dir.

[Mowblow]

Hi, I'm interested in working on this fix. I've looked at the biallelic_snps_to_plink function and can see where the filename prefix is being built — it currently only includes region, n_snps, min_minor_ac, max_missing_an, and thin_offset, leaving out sample_sets, sample_query, sample_indices, site_mask, and random_seed.

Before I proceed, @jonbrenas, is there a preferred approach to handling these in the filename? For example, sample_sets can be a list and sample_query can be a long string, so I want to make sure the filename stays clean and consistent with how the rest of the codebase handles similar cases.

I'm also planning to apply for GSoC 2026 and would love for this to be my first contribution to the project.

[jonbrenas]

Hi @Mowblow,

There isn't a preferred approach. You need to show me why your approach is the one that we should prefer.

[mithil27360]

@Mowblow

Nice fix , hashing the sample selection parameters makes sense and keeps filenames short.

One small question: should list inputs like sample_sets be canonicalized (e.g., sorted(sample_sets)) before hashing? Two calls with ["set_a","set_b"] vs ["set_b","set_a"] would currently produce different filenames even though the resulting cohort would be identical.

Also curious if there was a reason for choosing MD5 instead of something like truncated SHA256.

Happy to help add tests or refine the approach if useful.

[Mowblow]

Thanks for the feedback @mithil27360

On sorting, that's a valid point I missed. Sorting list inputs like sample_sets before hashing would make the filename stable regardless of order, since ["set_a", "set_b"] and ["set_b", "set_a"] represent the same cohort. Good catch.

On MD5 vs SHA256, no strong reason, MD5 was straightforward for this use case. SHA256 would be a reasonable choice too.

That said, I want to flag that there's already an existing PR addressing this same issue that I wasn't aware of when I started — it wasn't referenced in the issue thread. That PR appears to be more complete, includes tests, and uses the existing _hash_params() utility already in the codebase. I'd recommend looking at that one instead of spending more time refining this PR. I'm happy to close this in its favour.

I'm a GSoC 2026 applicant still learning the codebase, I'll find another issue to contribute to.

[mithil27360]

Appreciate the work you put into exploring the issue anyway.Good luck with your GSoC application!

[khushthecoder]

Hi @jonbrenas,

Why this matters: Without this fix, two exports that differ only in sample_sets or random_seed silently overwrite each other. This is especially dangerous when users run multiple exports into the same output_dir, as downstream analysis would unknowingly use the wrong dataset.

My approach: I kept the change minimal and consistent with existing patterns:

• Reused the existing _hash_params() utility from util.py
• Added canonicalization (sorted lists, numpy→Python type conversion) so semantically identical inputs produce the same hash
• Updated the existing integration test to use the API return value (more robust than hardcoding the path format)
• Added 3 focused unit tests for collision prevention, random seed sensitivity, and list-order canonicalization

All pre-commit hooks pass cleanly.

Looking forward to your feedback!
I have opened a PR for this issue. Could you please review it? #1158

[jonbrenas]

Hi all,

Thank you for all the effort. I think the onus on avoiding collisions should be on the user, i.e., the solution should be to have a parameter that lets the user choose the name of the file they are writing. Your approaches work in the case where the user doesn't do that, and I think they are valuable, but collision prevention isn't as important if it is clearly the users responsibility.

[khushthecoder]

Hi @jonbrenas,

Thank you for the feedback! That makes complete sense — explicit over implicit is definitely the better design choice here. Giving the user direct control over the output filename is a much cleaner solution than relying entirely on complex automatic hashing.

If you agree, I'd be happy to pivot this PR to implement your suggestion. We could add an optional

out
or filename_prefix parameter to the relevant PLINK export methods (like biallelic_snps_to_plink).
If the user provides it: We use their exact string (e.g., ag3.biallelic_snps_to_plink(..., out="my_custom_export") creates my_custom_export.bed/bim/fam).
If the user omits it: We can fall back to the existing default behavior (perhaps with the hash appended to prevent accidental overwrites, as a secondary safety net).
Does this API approach sound good to you? If so, I can go ahead and update my implementation to focus on adding the explicit filename overriding parameter.

[jonbrenas]

Thanks @khushthecoder, yes, I think it is the way to go.