#!/bin/bash
#==========================================================================
# CFTR2 Variant Integration and Ensembl Formatter Pipeline
#==========================================================================
#
# STEP 0: PREREQUISITE FILES
#
#   1. Download the most recent CFTR2 variant list from:
#         http://cftr2.org/mutations_history
#      (Filename: CFTR2_25September2024.xlsx)
#
#   2. Prepare the Variant Input File for Downstream Analysis:
#      Create an Excel file named "Variant_Name_Input.xlsx" with the following three columns:
#         - "Variant cDNA name"
#         - "Variant legacy name"
#         - "Allele frequency"
#
#      Populate "Variant_Name_Input.xlsx" by copying the corresponding columns from
#      CFTR2_25September2024.xlsx:
#         * Copy the "Variant cDNA name" column.
#         * Copy the "Variant legacy name" column.
#         * Copy the "Allele frequency in CFTR2*" column and rename it to "Allele frequency".
#         * Copy the "Variant final determination 25 September 2024 (current version)" column and rename it to "Class"
#
#   3. Files generated by the preceding CFTR2 Transcript and Genomic Sequence Pipeline:
#         - CFTR_Sequence.py
#         - CFTR-201_Exon_Intron_Complete_Coordinates.csv
#
#   4. Package Dependencies:
#         - Python with packages: pandas, re, csv, argparse
#
#   5. Required Python Modules:
#         - Genomic_Coordinate_Mapping.py
#         - Germline_Ensembl_Variant_Formatter.py
#         - CFTR_Sequence.py
#         - VariantMappingAndMutantEnsemblFormatUtils.py
#         - Codon_AA.py
#
#      Ensure these utility files are available in the working directory or are
#      accessible via the Python path.
#
#   6. Required T1K Modules:
#         - ParseDatFile.pl: A Perl script for parsing .dat files in the T1K pipeline.
#
#==========================================================================
#
# STEP 1: RUN VARIANT INTEGRATION AND GENERATE ENSEMBL FORMAT
#
# This pipeline integrates CFTR2 variant data, processes cDNA variant names to
# generate mutant Ensembl-formatted coordinates, and exports the results for
# downstream analysis.
#
# Command-Line Arguments: [Optional]
#   -allelethreshold         : Allele frequency threshold for creating combined alleles 
#                              (default: 0.01)
#   -completepos_dir         : Path to the CFTR exon/intron coordinate CSV file 
#                              (default: ./CFTR-201_Exon_Intron_Complete_Coordinates.csv)
#   -variantnames_dir        : Path to the variant name list 
#                              (default: ./Variant_Names_Input.xlsx)
#   -export_kept_and_dropped : Flag to export the dropped and kept variants DataFrames 
#                              to CSV (default: do not export)
#
# To run the pipeline with default settings:
#   python3 Variant_Integration_Ensembl_Formatting.py
#
# To run with a custom allele frequency threshold and export reference CSV files:
#   python3 Variant_Integration_Ensembl_Formatting.py -allelethreshold 0.02 -export_kept_and_dropped
# 
# Output Files:
#   - CFTR_Mimic_Ensembl_Format.dat        : Final mutant data in Ensembl .dat format
#   - CFTR_cDNA_Legacy_Allele_Reference.csv: Reference file with variant names, legacy names, 
#                                            and allele identifiers
#   - Optionally, if -export_kept_and_dropped is set:
#         Combined_Variants_to_Drop.csv    : Variants excluded due to overlapping mutation regions
#         Combined_Variants_to_Keep.csv    : Variants retained for further analysis
#
#==========================================================================
# 
# EXPLANATION OF Variant_Integration_Ensembl_Formatting.py
#
# This pipeline performs the following major steps:
#    Step 1: Reads and preprocesses the variant name list.
#    Step 2: Expands the variant list by creating combined alleles.
#    Step 3: Reads CFTR exon/intron coordinates and generates a mapping between genomic DNA 
#            and cDNA positions.
#    Step 4: Excludes duplicate and overlapping variants, producing separate DataFrames for 
#            variants to keep and drop.
#    Step 5: Creates a germline Ensembl format based on base pair counts from the coordinate file.
#    Step 6: Processes each variant to generate mutant Ensembl-formatted output, exports a .dat file, 
#            and creates a reference CSV for variant names and allele identifiers.
#
#==========================================================================
#
# STEP 2: PARSE DAT FILE
#
# This step utilizes the Perl script "ParseDatFile.pl" to convert the 
# Ensembl-formatted .dat file into reference FASTA files for both DNA and RNA.
#
# To generate reference fasta for dna: 
#   perl {PATH}/ParseDatFile.pl CFTR_Mimic_Ensembl_Format.dat  --mode dna > CFTR2_dna.fa
#
# To generate reference fasta for rna: 
#   perl {PATH}/ParseDatFile.pl CFTR_Mimic_Ensembl_Format.dat  --mode rna > CFTR2_rna.fa
#
# Ensure that the "ParseDatFile.pl" script is located in the specified {PATH}
# or update {PATH} accordingly.
#
#==========================================================================
