RefgenDetector 3.0.0__py3-none-any.whl

refgenDetector/aligment_files.py

@@ -0,0 +1,272 @@
+import os
+import sys
+# Add the parent directory to the Python path
+current_dir = os.path.dirname(os.path.abspath(__file__))
+parent_dir = os.path.dirname(current_dir)
+sys.path.insert(0, parent_dir)
+from refgenDetector.reference_genome_dictionaries import *
+from refgenDetector.exceptions.NoFileException import *
+import argparse
+import csv
+import gzip
+import pysam
+import psutil
+import time
+from rich.console import Console
+
+console = Console()
+
+def intersection_targetfile_referencerepo(dict_SN_LN, reference_genome):
+    """
+    Find the matches between the target file and the repository of unique contigs per reference genome.
+    Returns the actual matches (ln info) instead of just their count.
+    Args:
+         dict_SN_LN (dict) : dictionary with the contig (SN: key, LN: value) info from the target file
+         reference_genome (dict entry): one of the versions from major_releases
+
+    Returns:
+        matches (set) : list of lengths matching to the version currently being read
+        reference_genome["build"] (str): build of the version currently being read
+        reference_genome["species"] (str): species of the version currently being read
+    """
+    matches = set(dict_SN_LN.values()).intersection(reference_genome["ref_gen"].values())
+    return matches, reference_genome["build"], reference_genome["species"]
+
+def check_if_decoy(matches_info, target_file): 
+    """
+    Checks if there's inconsistency of the versions in the target file or if the multiple matches are random
+    Args:
+         matches_info (list): list of tuples. Each tuple have 3 positions: lengths from the contigs matching,
+         version where the contigs match, species from the version.
+         target_file (str): path of the target file
+
+    Returns:
+        If the matches to the secondary version are at least as long as the shortest chromosome of the version with
+        more matches then a message raising the incosistency is printed.
+        If the matches to the secondary version are shorter than the shortest chromosome then it assumes it's a decoy
+        contig matching another version randomly and returns:
+        incosistency = False so the code can continue in comparison() and give the results based on the version with
+        most matches.
+    """
+    incosistency_found = False
+    filtered_entries = [entry for entry in matches_info if entry[0]]  # get the multiple matches
+    match = max(filtered_entries, key=lambda ref_gen_w_macthes: len(ref_gen_w_macthes[0]))  # version with most
+    # matches with LN values
+    inconsistency_matches = []
+    for version in filtered_entries:
+        if version != match:
+            for ln in version[0]:
+                if int(ln) > min_values[match[1]]: # checks if the ln matching is more or less chr length
+                    ref_dict = globals().get(version[1])
+                    inconsistency_matches.extend([key for key, value in ref_dict.items() if value == ln])
+                    incosistency_found = True
+            if incosistency_found == True:
+                console.print(f"[bold]File:[/bold] {target_file} \n[bold][red]Error:[/bold] Inconsistency found "
+                              f"- file contains contigs from different genome versions[/red]")
+                console.print(f"[red]Contigs {inconsistency_matches} belong to {version[1]}, but the rest belongs to"
+                              f" {match[1]}[/red].")
+    return incosistency_found
+
+
+def comparison(dict_SN_LN, target_file):
+    """
+    First, it defines the major release to which the header belongs to. Then, checks if a flavor can be inferred.
+    Args:
+         dict_SN_LN (dict): dictionary with the contig (SN: key, LN: value) info from the target file
+         target_file (str): path of the target file
+
+    Returns:
+        Prints the file path being analyzed,the species and the Reference genome version inferred.
+        It raises an error if:
+            - The contigs in the target file are not in the database (a species or ref gen version not included in the tool)
+            - There are contigs belonging to more than one release/species. This will be printed if the match between
+            species is as long as the shortest chromosome from the version with the most matches. If the match is
+            shorter it assumes it's a random match e.g a decoy contig that randomly matches the length of
+            another species/version.
+    """
+
+    matches_info = [intersection_targetfile_referencerepo(dict_SN_LN, major_releases[ref]) for ref in major_releases]
+    matches_with_counts = [(len(matches), build, species) for matches, build, species in matches_info]
+    max_match = max(matches_with_counts, key=lambda ref_gen_w_macthes: ref_gen_w_macthes[0]) # Find the major release
+    # with the maximum matches
+    incosistency = False 
+
+    # check all the matches belong to the same release version
+    multiple_matches = []
+    for match in matches_with_counts:
+        if match[0] != 0:
+            multiple_matches.append(match)
+
+    if len(multiple_matches) > 1 :
+        if multiple_matches[0][1] != "hg17" and multiple_matches[1][1] != "hg18": # these versions share contig lengths
+            if multiple_matches[0][1] != "rhemac3" and multiple_matches[1][1] != "rhemac8":
+                incosistency = check_if_decoy(matches_info, target_file)
+
+    if incosistency == False:
+        if max_match[0] == 0:
+            for contig in dict_SN_LN.values(): 
+                if contig not in mit_contigs.values(): 
+                    console.print(f"[bold][red]Reference genome can't be inferred[/bold] - "
+                          "The contigs in the file are not found in refgenDetector database[red]")
+                    break
+                else: 
+                    ref_version = next(key for key, value in mit_contigs.items() if value == contig)
+                    console.print(f"[bold]Species detected:[/bold] Homo sapiens \n[bold]Reference genome version  :[/bold] {ref_version}")
+                    console.print(f"Note: Only the mitochondrial reference sequence is present. Nuclear genome build cannot be determined.")
+
+        elif max_match[1] == "GRCh37": #check for GRCh37 flavors
+
+            matches_flavors = [
+                intersection_targetfile_referencerepo(dict_SN_LN, flavors_GRCh37[ref])
+                for ref in flavors_GRCh37
+            ]
+            
+            match_flavors = max(matches_flavors, key=lambda x: x[0])
+            if match_flavors: #if some flavor was defined it prints it
+                console.print(f"[bold]Species detected:[/bold] {match_flavors[2]} "
+                f"[bold]\nReference genome version  :[/bold] {match_flavors[1]}")
+            else: #if there wasnt any flavor inferred, the major release it printed
+                console.print(f"[bold]Species detected:[/bold] Homo sapiens \n["
+                              f"bold]Reference genome version  :[/bold] GRCh37")
+
+        elif max_match[1] == "GRCh38": #checks for GRCh38 flavors
+
+            if any("HLA-" in key for key in dict_SN_LN.keys()):
+                #first checks if the contigs contain in their names HLA-
+                console.print(f"[bold]Species detected:[/bold] Homo sapiens \n[bold]"
+                              f"Reference genome version  :[/bold] hs38DH_extra")
+            elif set(dict_SN_LN.values()).intersection(verily_difGRCh38.values()):#checks if the Verily's unique
+                # lengths are present
+                console.print(f"[bold]Species detected:[/bold] Homo sapiens \n[bold]"
+                              f"Reference genome version  :[/bold] GRCh38_no_alt_plus_hs38d1")
+            else: # if no GRCh38 flavor is inferred, the major release is printed
+                console.print(f"[bold]Species detected:[/bold] Homo sapiens \n["
+                              f"bold]Reference genome version  :[/bold] GRCh38")        
+        else: # print the major releases with no considered flavors.
+            console.print(f"[bold]Species detected:[/bold] {match[2]} "
+                  f"\n[bold]Reference genome version:[/bold] {match[1]}")
+
+
+
+
+def get_info_bamcram(header_bam_cram, target_file, md5, assembly):
+    """
+    Second function of the BAM/CRAM module. Loop over the SQ (sequence dictionary) records in the header, creates a
+    dictionary with the contigs names and lengths, if present and requested by the user (adding -m and -a in the
+    argument) prints AS and M5
+
+    Args:
+        header_bam_cram(pysam.libcalignmentfile.AlignmentHeader): text object
+
+    Returns:
+        dict_SN_LN (dict): dictionary with the contig (SN: key, LN: value) info from the target file
+        target_file (str): path of the target file
+        dict_assembly[1] (str): if present and asked by the user, AS value from the target file header
+        dict_M5 (dict): if present and asked by the user, M5 values from the target file header
+    """
+
+    dict_SN_LN = {sq_record["SN"]: sq_record["LN"] for sq_record in header_bam_cram.get("SQ", [])}
+
+    if assembly: # if the user chose -a
+        dict_assembly = set(sq_record["AS"] for sq_record in header_bam_cram.get("SQ", []) if "AS" in sq_record)
+        if dict_assembly:
+            console.print(f"[bold]AS field:[/bold] {dict_assembly.pop()}")
+    if md5: # if the user chose -m
+        dict_M5 = set(sq_record["M5"] for sq_record in header_bam_cram.get("SQ", []) if "M5" in sq_record)
+        if dict_M5:
+            console.print(f"[bold]M5 fields:[/bold]{dict_M5}")
+    comparison(dict_SN_LN, target_file)
+
+
+def process_data_bamcram(target_file, md5, assembly):
+    """
+    First function of the BAM/CRAM module. It opens each BAM or CRAM provided by the user and extracts the header.
+
+    Args:
+        target_file (str): path to the file
+
+    Returns:
+        header_bam_cram (pysam.libcalignmentfile.AlignmentHeader): text object
+    """
+    try:
+        save = pysam.set_verbosity(0)  # https://github.com/pysam-developers/pysam/issues/939
+        bam_cram = pysam.AlignmentFile(target_file, "rb")
+        pysam.set_verbosity(save)
+    except Exception as e:
+        console.print(f"[bold]File:[/bold] {target_file} \n[bold][red]Error:[/bold][red] {e.__class__}, {e}")
+
+
+    header_bam_cram = bam_cram.header
+    get_info_bamcram(header_bam_cram, target_file, md5, assembly)
+
+def get_info_txt(header_txt, md5, assembly):
+    """
+    Second function of the txt module. Extracts the SQ (sequence dictionary) records in the header, creates a
+    dictionary with the contigs names and lengths, and, if present and requested by the user (adding -m and -a in the
+    argument) prints AS and M5.
+
+    Args:
+        header_txt (io.TextIOWrapper): text object
+
+    Returns:
+        dict_SN_LN (dict): dictionary with the contig (SN: key, LN: value) info from the target file
+        header_txt.name (str): path of the target file
+        dict_assembly[1] (str): if present and asked by the user, AS value from the target file header
+        dict_M5 (dict): if present and asked by the user, M5 values from the target file header
+    """
+    header_reader = csv.reader(header_txt, delimiter="\t")
+    try:
+        dict_SQ = [line for line in header_reader if "@SQ" in line]
+    except (UnicodeDecodeError, csv.Error) as e:
+        print(f"File cannot be read ({type(e).__name__}: {e}). It is likely compressed, corrupted or the incorrect -t.")
+    try:
+        dict_SN_LN = {line[1].replace("SN:", ""): int(line[2].replace("LN:", "")) for line in dict_SQ}  #the dictonary values must be int due to the structure of the collection of reference dictionaries
+
+    except ValueError:
+        print(f"Check the LN field of your header {header_txt.name} only contains numbers")
+    
+    comparison(dict_SN_LN, header_txt.name)
+
+    if assembly:  # # if the user chose -a
+        dict_assembly = [l for line in dict_SQ for l in line if "AS" in l][:1]
+        if dict_assembly:  # if AS is present in the header
+            console.print(f"[bold]AS field:[/bold] {dict_assembly[0].split(':')[1]}")
+    if md5:  # # if the user chose -m
+        for i in dict_SQ[0]:
+            if "M5" in i:
+                dict_M5 = {line[1].replace("SN:", ""): i.replace("M5:", "") for line in
+                      dict_SQ}
+                console.print(f"[bold]MD5 fields:[/bold] {dict_M5}")
+
+def process_data_txt(target_file, md5, assembly):
+    """
+    First function of the txt module. It opens each header in --path. gzip or uncompressed and encoded in utf-8 or
+    iso-8859-1.
+
+    Args:
+        target_file (str): path to the file
+
+    Returns:
+        header_txt (io.TextIOWrapper): text object
+    """
+    try:
+        if os.path.isfile(target_file):
+            with open(target_file, "r") as header_txt:
+                get_info_txt(header_txt, md5, assembly)
+        else:
+            raise NoFileException()
+    except UnicodeError:
+        with open(target_file, "r", encoding="iso-8859-1") as header_txt:
+            get_info_txt(header_txt, md5, assembly)
+    except OSError:
+        try:
+            with gzip.open(target_file, "rt") as header_txt:
+                get_info_txt(header_txt, md5, assembly)
+        except UnicodeError:
+            with gzip.open(target_file, "rt", encoding="iso-8859-1") as header_txt:
+                get_info_txt(header_txt, md5, assembly)
+    except NoFileException:
+        console.print(f"[bold]File:[/bold] {target_file} \n[bold][red]Error:[/bold][red] The path provided is not "
+                      f"found or you are using the incorrect --type option.")
+    except Exception as e:
+        print("Unexpected error:\n", e)

refgenDetector/chromosomes_dict.py

@@ -0,0 +1,34 @@
+
+"""
+Original dictionary:
+chromosomes = {
+        "chr1": ["1", "chr1", "CM000663.1", "NC_000001.10", "CM000663.2", "NC_000001.11", "CP068277.2", "NC_060925.1"],
+        "chr2": ["2", "chr2", "CM000664.1", "NC_000002.11", "CM000664.2", "NC_000002.12", "CP068276.2", "NC_060926.1"],
+        "chr3": ["3", "chr3", "CM000665.1", "NC_000003.11", "CM000665.2", "NC_000003.12", "CP068275.2", "NC_060927.1"],
+        "chr4": ["4", "chr4", "CM000666.1", "NC_000004.11", "CM000666.2", "NC_000004.12", "CP068274.2", "NC_060928.1"],
+        "chr5": ["5", "chr5", "CM000667.1", "NC_000005.9", "CM000667.2", "NC_000005.10", "CP068273.2", "NC_060929.1"],
+        "chr6": ["6", "chr6", "CM000668.1", "NC_000006.11", "CM000668.2", "NC_000006.12", "CP068272.2", "NC_060930.1"],
+        "chr7": ["7", "chr7", "CM000669.1", "NC_000007.13", "CM000669.2", "NC_000007.14", "CP068271.2", "NC_060931.1"],
+        "chr8": ["8", "chr8", "CM000670.1", "NC_000008.10", "CcM000670.2", "NC_000008.11", "CP068270.2", "NC_060932.1"],
+        "chr9": ["9", "chr9", "CM000671.1", "NC_000009.11", "CM000671.2", "NC_000009.12", "CP068269.2", "NC_060933.1"],
+        "chr10": ["10", "chr10", "CM000672.1", "NC_000010.10", "CM000672.2", "NC_000010.11", "CP068268.2", "NC_060934.1"],
+        "chr11": ["11", "chr11", "CM000673.1", "NC_000011.9", "CM000673.2", "NC_000011.10", "CP068267.2", "NC_060935.1"],
+        "chr12": ["12", "chr12", "CM000674.1", "NC_000012.11", "CM000674.2", "NC_000012.12", "CP068266.2", "NC_060936.1"],
+        "chr13": ["13", "chr13", "CM000675.1", "NC_000013.10", "CM000675.2", "NC_000013.11", "CP068265.2", "NC_060937.1"],
+        "chr14": ["14", "chr14", "CM000676.1", "NC_000014.8", "CM000676.2", "NC_000014.9", "CP068264.2", "NC_060938.1"],
+        "chr15": ["15", "chr15", "CM000677.1", "NC_000015.9", "CM000677.2", "NC_000015.10", "CP068263.2", "NC_060939.1"],
+        "chr16": ["16", "chr16", "CM000678.1", "NC_000016.9", "CM000678.2", "NC_000016.10", "CP068262.2", "NC_060940.1"],
+        "chr17": ["17", "chr17", "CM000679.1", "NC_000017.10", "CM000679.2", "NC_000017.11", "CP068261.2", "NC_060941.1"],
+        "chr18": ["18", "chr18", "CM000680.1", "NC_000018.9", "CM000680.2", "NC_000018.10", "CP068260.2", "NC_060942.1"],
+        "chr19": ["19", "chr19", "CM000681.1", "NC_000019.9", "CM000681.2", "NC_000019.10", "CP068259.2", "NC_060943.1"],
+        "chr20": ["20", "chr20", "CM000682.1", "NC_000020.10", "CM000682.2", "NC_000020.11", "CP068258.2", "NC_060944.1"],
+        "chr21": ["21", "chr21", "CM000683.1", "NC_000021.8", "CM000683.2", "NC_000021.9", "CP068257.2", "NC_060945.1"],
+        "chr22": ["22", "chr22", "CM000684.1", "NC_000022.10", "CM000684.2", "NC_000022.11", "CP068256.2", "NC_060946.1"],
+        "chrX": ["X", "chrX", "CM000685.1", "NC_000023.10", "CM000685.2", "NC_000023.11", "CP068255.2", "NC_060947.1"],
+        "chrY": ["Y", "chrY", "CM000686.1", "NC_000024.9", "CM000686.2", "NC_000024.10", "CP086569.2", "NC_060948.1"]
+    }
+
+chromosome_map = {v: k for k, lst in chromosomes.items() for v in lst}
+print(chromosome_map)"""
+
+chromosome_map = {'1': 'chr1', 'chr1': 'chr1', 'CM000663.1': 'chr1', 'NC_000001.10': 'chr1', 'CM000663.2': 'chr1', 'NC_000001.11': 'chr1', 'CP068277.2': 'chr1', 'NC_060925.1': 'chr1', '2': 'chr2', 'chr2': 'chr2', 'CM000664.1': 'chr2', 'NC_000002.11': 'chr2', 'CM000664.2': 'chr2', 'NC_000002.12': 'chr2', 'CP068276.2': 'chr2', 'NC_060926.1': 'chr2', '3': 'chr3', 'chr3': 'chr3', 'CM000665.1': 'chr3', 'NC_000003.11': 'chr3', 'CM000665.2': 'chr3', 'NC_000003.12': 'chr3', 'CP068275.2': 'chr3', 'NC_060927.1': 'chr3', '4': 'chr4', 'chr4': 'chr4', 'CM000666.1': 'chr4', 'NC_000004.11': 'chr4', 'CM000666.2': 'chr4', 'NC_000004.12': 'chr4', 'CP068274.2': 'chr4', 'NC_060928.1': 'chr4', '5': 'chr5', 'chr5': 'chr5', 'CM000667.1': 'chr5', 'NC_000005.9': 'chr5', 'CM000667.2': 'chr5', 'NC_000005.10': 'chr5', 'CP068273.2': 'chr5', 'NC_060929.1': 'chr5', '6': 'chr6', 'chr6': 'chr6', 'CM000668.1': 'chr6', 'NC_000006.11': 'chr6', 'CM000668.2': 'chr6', 'NC_000006.12': 'chr6', 'CP068272.2': 'chr6', 'NC_060930.1': 'chr6', '7': 'chr7', 'chr7': 'chr7', 'CM000669.1': 'chr7', 'NC_000007.13': 'chr7', 'CM000669.2': 'chr7', 'NC_000007.14': 'chr7', 'CP068271.2': 'chr7', 'NC_060931.1': 'chr7', '8': 'chr8', 'chr8': 'chr8', 'CM000670.1': 'chr8', 'NC_000008.10': 'chr8', 'CM000670.2': 'chr8', 'NC_000008.11': 'chr8', 'CP068270.2': 'chr8', 'NC_060932.1': 'chr8', '9': 'chr9', 'chr9': 'chr9', 'CM000671.1': 'chr9', 'NC_000009.11': 'chr9', 'CM000671.2': 'chr9', 'NC_000009.12': 'chr9', 'CP068269.2': 'chr9', 'NC_060933.1': 'chr9', '10': 'chr10', 'chr10': 'chr10', 'CM000672.1': 'chr10', 'NC_000010.10': 'chr10', 'CM000672.2': 'chr10', 'NC_000010.11': 'chr10', 'CP068268.2': 'chr10', 'NC_060934.1': 'chr10', '11': 'chr11', 'chr11': 'chr11', 'CM000673.1': 'chr11', 'NC_000011.9': 'chr11', 'CM000673.2': 'chr11', 'NC_000011.10': 'chr11', 'CP068267.2': 'chr11', 'NC_060935.1': 'chr11', '12': 'chr12', 'chr12': 'chr12', 'CM000674.1': 'chr12', 'NC_000012.11': 'chr12', 'CM000674.2': 'chr12', 'NC_000012.12': 'chr12', 'CP068266.2': 'chr12', 'NC_060936.1': 'chr12', '13': 'chr13', 'chr13': 'chr13', 'CM000675.1': 'chr13', 'NC_000013.10': 'chr13', 'CM000675.2': 'chr13', 'NC_000013.11': 'chr13', 'CP068265.2': 'chr13', 'NC_060937.1': 'chr13', '14': 'chr14', 'chr14': 'chr14', 'CM000676.1': 'chr14', 'NC_000014.8': 'chr14', 'CM000676.2': 'chr14', 'NC_000014.9': 'chr14', 'CP068264.2': 'chr14', 'NC_060938.1': 'chr14', '15': 'chr15', 'chr15': 'chr15', 'CM000677.1': 'chr15', 'NC_000015.9': 'chr15', 'CM000677.2': 'chr15', 'NC_000015.10': 'chr15', 'CP068263.2': 'chr15', 'NC_060939.1': 'chr15', '16': 'chr16', 'chr16': 'chr16', 'CM000678.1': 'chr16', 'NC_000016.9': 'chr16', 'CM000678.2': 'chr16', 'NC_000016.10': 'chr16', 'CP068262.2': 'chr16', 'NC_060940.1': 'chr16', '17': 'chr17', 'chr17': 'chr17', 'CM000679.1': 'chr17', 'NC_000017.10': 'chr17', 'CM000679.2': 'chr17', 'NC_000017.11': 'chr17', 'CP068261.2': 'chr17', 'NC_060941.1': 'chr17', '18': 'chr18', 'chr18': 'chr18', 'CM000680.1': 'chr18', 'NC_000018.9': 'chr18', 'CM000680.2': 'chr18', 'NC_000018.10': 'chr18', 'CP068260.2': 'chr18', 'NC_060942.1': 'chr18', '19': 'chr19', 'chr19': 'chr19', 'CM000681.1': 'chr19', 'NC_000019.9': 'chr19', 'CM000681.2': 'chr19', 'NC_000019.10': 'chr19', 'CP068259.2': 'chr19', 'NC_060943.1': 'chr19', '20': 'chr20', 'chr20': 'chr20', 'CM000682.1': 'chr20', 'NC_000020.10': 'chr20', 'CM000682.2': 'chr20', 'NC_000020.11': 'chr20', 'CP068258.2': 'chr20', 'NC_060944.1': 'chr20', '21': 'chr21', 'chr21': 'chr21', 'CM000683.1': 'chr21', 'NC_000021.8': 'chr21', 'CM000683.2': 'chr21', 'NC_000021.9': 'chr21', 'CP068257.2': 'chr21', 'NC_060945.1': 'chr21', '22': 'chr22', 'chr22': 'chr22', 'CM000684.1': 'chr22', 'NC_000022.10': 'chr22', 'CM000684.2': 'chr22', 'NC_000022.11': 'chr22', 'CP068256.2': 'chr22', 'NC_060946.1': 'chr22', 'X': 'chrX', 'chrX': 'chrX', 'CM000685.1': 'chrX', 'NC_000023.10': 'chrX', 'CM000685.2': 'chrX', 'NC_000023.11': 'chrX', 'CP068255.2': 'chrX', 'NC_060947.1': 'chrX', 'Y': 'chrY', 'chrY': 'chrY', 'CM000686.1': 'chrY', 'NC_000024.9': 'chrY', 'CM000686.2': 'chrY', 'NC_000024.10': 'chrY', 'CP086569.2': 'chrY', 'NC_060948.1': 'chrY'}

refgenDetector/ref_manager.py

@@ -0,0 +1,240 @@
+import sys
+import json
+from pathlib import Path
+from reference_genome_dictionaries import major_releases
+
+DEFAULT_MAJOR_RELEASES = dict(major_releases)
+
+CUSTOM_DB = Path("custom_references.json")
+
+if CUSTOM_DB.exists():
+    with open(CUSTOM_DB) as f:
+        custom_refs = json.load(f)
+
+    major_releases.update(custom_refs)
+
+
+def load_from_fai(file_path):
+    """
+    Loads the contig information from a .fai file into a dictionary.
+    Args:
+        file_path (str): path to the .fai file to load
+
+    Returns:
+        dict: A dictionary where keys are contig names and values are their lengths.
+    """
+
+    contigs = {}
+
+    with open(file_path) as f:
+        for line in f:
+            if line.strip() == "":
+                continue
+
+            parts = line.strip().split("\t")
+
+            if len(parts) < 2:
+                raise ValueError(f"Invalid .fai line: {line}")
+
+            contigs[parts[0]] = int(parts[1])
+
+    if not contigs:
+        raise ValueError("Empty .fai file")
+
+    return contigs
+
+
+def load_custom_db():
+    """
+    Loads the custom reference database from a JSON file. If the file does not exist, returns an empty dictionary.
+
+    Returns:
+        dict: A dictionary containing the custom references, where keys are reference names and values are their data.
+    """
+    if CUSTOM_DB.exists():
+        with open(CUSTOM_DB) as f:
+            return json.load(f)
+    return {}
+
+
+def save_custom_db(db):
+    """
+    Saves the custom reference database to a JSON file.
+    Args:
+        db (dict): A dictionary containing the custom references, where keys are reference names and values are their data.
+
+    """
+    with open(CUSTOM_DB, "w") as f:
+        json.dump(db, f, indent=4)
+
+
+def get_all_references():
+    """
+    Merge default + custom references
+    Returns:
+        dict: A dictionary containing all references, where keys are reference names and values are their data.
+    """
+    custom = load_custom_db()
+    merged = dict(major_releases)
+    merged.update(custom)
+    return merged
+
+
+def compare_contigs(c1, c2):
+    """
+    Return True if contig dictionaries match exactly
+    Args:
+        c1 (dict): Contig dictionary of the new reference, where keys are contig names and values are their lengths.
+        c2 (dict): Contig dictionary of an existing reference, where keys are contig names and values are their lengths.
+    """
+    return c1 == c2
+
+
+def find_matching_reference(new_contigs, all_refs):
+    """
+    Check if contigs match an existing reference. Avoid adding duplicates to the database. 
+    Args:
+        new_contigs (dict): Contig dictionary of the new reference, where keys are contig names and values are their lengths.
+        all_refs (dict): A dictionary containing all references, where keys are reference names and values are their data, including the contig dictionary under the key "
+    Returns:        
+        str | None: The name of the matching reference if a match is found, or None if not. 
+    """
+
+    for name, data in all_refs.items():
+        if compare_contigs(new_contigs, data["ref_gen"]):
+            return name
+
+    return None
+
+
+def add_reference(ref_name, species, fai_file):
+    """
+    Add a new reference to the custom database, after checking that it doesn't match an existing reference. The contig information is loaded from the provided .fai file.
+    Args:
+        ref_name (str): Name of the new reference to add.
+        species (str): Species of the new reference to add. 
+        fai_file (str): Path to the .fai file containing the contig information of the new reference. The .fai file must have the format: contig_name \t contig_length \t ... (other columns are ignored).
+    Returns:    
+        If a matching reference is found, it prints a message with the name of the matching reference and aborts the addition. 
+        If no match is found, it adds the new reference to the custom database and prints a success message.
+    """
+
+    fai_file = Path(fai_file)
+
+    if not fai_file.exists():
+        raise FileNotFoundError(f"File not found: {fai_file}")
+
+    if fai_file.suffix != ".fai":
+        raise ValueError("Input must be a .fai file")
+
+    print(f"Loading contigs from: {fai_file}")
+    contigs = load_from_fai(fai_file)
+
+    all_refs = get_all_references()
+
+    # Duplicate detection
+    match = find_matching_reference(contigs, all_refs)
+    if match:
+        print(f"This reference matches existing reference: {match}")
+        print("Aborting to avoid duplication.")
+        return
+
+    db = load_custom_db()
+
+    if ref_name in db:
+        print(f"Warning: '{ref_name}' already exists and will be overwritten")
+
+    db[ref_name] = {
+        "ref_gen": contigs,
+        "build": ref_name,
+        "species": species
+    }
+
+    save_custom_db(db)
+
+    print(f"Reference '{ref_name}' added successfully.")
+
+
+def list_references():
+    """
+    List all available references, including both default and custom ones. 
+    It indicates the origin of each reference (default or custom) and prints the total number of references.
+    Args:     None
+    Returns:
+    """
+    default = DEFAULT_MAJOR_RELEASES
+    custom = load_custom_db()
+    all_refs = get_all_references()
+
+    print("\nAvailable references:\n")
+
+    for name, data in all_refs.items():
+        origin = "custom" if name in custom else "default"
+        print(f"- {name} ({data['species']}) [{origin}]")
+
+    print(f"\nTotal: {len(all_refs)} references")
+
+
+def remove_reference(ref_name):
+    """
+    Remove a reference from the custom database by its name. 
+    It checks if the reference exists in the custom database before attempting to remove it, and prints a message indicating whether the removal was successful or if the reference was not found.
+    Args:      
+        ref_name (str): Name of the reference to remove. It must be a reference that was added to the custom database, as default references cannot be removed.
+    Returns:     
+        If the reference is found and removed successfully, it prints a success message.
+    """
+    db = load_custom_db()
+
+    if ref_name not in db:
+        print(f"'{ref_name}' not found in custom references.")
+        return
+
+    del db[ref_name]
+    save_custom_db(db)
+
+    print(f"Removed reference '{ref_name}'")
+
+
+def main():
+    """
+    Command-line interface for managing the reference database. It supports three commands:
+        - add <name> <species> <fai>: Adds a new reference to the custom database with the specified name, species, and contig information loaded from the provided .fai file.
+        - list: Lists all available references, including both default and custom ones, indicating their origin and the total number of references.
+        - remove <name>: Removes a reference from the custom database by its name. Only references that were added to the custom database can be removed, default references cannot be removed.
+    """
+
+    if len(sys.argv) < 2:
+        print(
+            "Usage:\n"
+            "  add <name> <species> <fai>\n"
+            "  list\n"
+            "  remove <name>"
+        )
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "add":
+        if len(sys.argv) != 5:
+            print("Usage: add <name> <species> <genome.fai>")
+            sys.exit(1)
+
+        add_reference(sys.argv[2], sys.argv[3], sys.argv[4])
+
+    elif command == "list":
+        list_references()
+
+    elif command == "remove":
+        if len(sys.argv) != 3:
+            print("Usage: remove <name>")
+            sys.exit(1)
+
+        remove_reference(sys.argv[2])
+
+    else:
+        print(f"Unknown command: {command}")
+
+
+if __name__ == "__main__":
+    main()