Fix #1113: Add out parameter to biallelic_snps_to_plink() for user-controlled filenames

Per maintainer feedback, the onus on avoiding filename collisions should
be on the user. Added an optional 'out' parameter that lets the user
specify a custom output file prefix. When provided, PLINK files are
written as {output_dir}/{out}.bed/.bim/.fam. When omitted, the existing
auto-generated prefix from SNP selection parameters is used.

Author: khushthecoder

malariagen_data/anoph/plink_params.py

@@ -16,3 +16,14 @@
     A string indicating the desired output file location.
     """,
 ]
+
+out: TypeAlias = Annotated[
+    str,
+    """
+    A string specifying the output file path prefix. The PLINK output files
+    will be written as ``{output_dir}/{out}.bed``, ``{output_dir}/{out}.bim``,
+    and ``{output_dir}/{out}.fam``. If not provided, a default prefix is
+    generated from the SNP selection parameters (region, n_snps,
+    min_minor_ac, max_missing_an, thin_offset).
+    """,
+]

malariagen_data/anoph/to_plink.py

@@ -69,14 +69,18 @@ def biallelic_snps_to_plink(
         random_seed: base_params.random_seed = 42,
         inline_array: base_params.inline_array = base_params.inline_array_default,
         chunks: base_params.chunks = base_params.native_chunks,
+        out: Optional[plink_params.out] = None,
     ):
         # Check that either sample_query xor sample_indices are provided.
         base_params._validate_sample_selection_params(
             sample_query=sample_query, sample_indices=sample_indices
         )
 
-        # Define output files
-        plink_file_path = f"{output_dir}/{region}.{n_snps}.{min_minor_ac}.{max_missing_an}.{thin_offset}"
+        # Use user-provided prefix or fall back to auto-generated default
+        if out is not None:
+            plink_file_path = f"{output_dir}/{out}"
+        else:
+            plink_file_path = f"{output_dir}/{region}.{n_snps}.{min_minor_ac}.{max_missing_an}.{thin_offset}"
 
         bed_file_path = f"{plink_file_path}.bed"