pmotools.pmo_builder.pmo_updater module

class pmotools.pmo_builder.pmo_updater.PMOUpdater[source]

Bases: object

static merge_dicts_by_key(main_list: list[dict], update_list: list[dict], key_field: str, replace: bool = False, ignore_fields: list[str] | None = None) → list[dict][source]

Merge two lists of dicts by a shared key field.

The first list is treated as the main/base data source. The second list provides updates that are applied on top. Both input lists are left untouched (deep copies are used internally).

Parameters:

  • main_list – The primary list of dicts (source of truth).

  • update_list – The list of dicts whose values will be merged in.

  • key_field – The dict key used to match records across lists.

  • replace – If True, existing values in main are overwritten by update values. If False, a conflict raises a ValueError.

  • ignore_fields – Optional list of field names to skip entirely during the merge (they are never read from update_list).

Returns:

A new list of dicts with updates applied.

Raises:

  • ValueError – If either list contains duplicate values for key_field.

  • KeyError – If any dict in either list is missing key_field.

  • KeyError – If update_list contains a key_field value that does not exist in main_list.

  • ValueError – If replace=False and an update would overwrite an existing field.

static update_representative_microhaplotypes_with_protein_variants(pmo, protein_variants_info: DataFrame, target_name_col: str = 'target_name', seq_col: str = 'seq', transcript_col: str = 'transcript', protein_start_col: str = 'protein_start', protein_end_col: str = 'protein_end', protein_genome_id_col: str | None = None, protein_ref_seq_col: str | None = None, protein_alt_seq_col: str | None = None, gene_name_col: str | None = None, alternative_gene_name_col: str | None = None, codon_chrom_col: str | None = None, codon_start_col: str | None = None, codon_end_col: str | None = None, codon_genome_id_col: str | None = None, codon_strand_col: str | None = None, codon_ref_seq_col: str | None = None, codon_alt_seq_col: str | None = None, replace_current_protein_variants: bool = False)[source]

Update a PMO’s representative microhaplotypes with associated protein variants, from a table with one row per variant

Parameters:

  • pmo – the PMO to update, will directly modify this PMO

  • protein_variants_info – the protein variants table

  • target_name_col – the column containing the target name of the microhaplotype

  • seq_col – the column containing the sequence of the microhaplotype

  • transcript_col – the column containing the transcript name, used as the chrom of the protein location

  • protein_start_col – the column containing the start of the variant within the protein, 0-based

  • protein_end_col – the column containing the end of the variant within the protein, 0-based

  • protein_genome_id_col – (Optional) the column containing the index into targeted_genomes for the protein location. Default: 0

  • protein_ref_seq_col – (Optional) the column containing the reference amino acid(s)

  • protein_alt_seq_col – (Optional) the column containing the alternative amino acid(s)

  • gene_name_col – (Optional) the column containing the gene name

  • alternative_gene_name_col – (Optional) the column containing an alternative gene name

  • codon_chrom_col – (Optional) the column containing the chromosome of the codon. Must be set with codon_start_col and codon_end_col

  • codon_start_col – (Optional) the column containing the genomic start of the codon, 0-based

  • codon_end_col – (Optional) the column containing the genomic end of the codon, 0-based

  • codon_genome_id_col – (Optional) the column containing the index into targeted_genomes for the codon location. Default: 0

  • codon_strand_col – (Optional) the column containing the strand of the codon

  • codon_ref_seq_col – (Optional) the column containing the reference sequence of the codon

  • codon_alt_seq_col – (Optional) the column containing the alternative sequence of the codon

  • replace_current_protein_variants – whether to replace current protein variants for the microhaplotypes in the table

Returns:

a reference to the updated PMO

static update_representative_microhaplotypes_with_seq_variants(pmo, seq_variants_info: DataFrame, target_name_col: str = 'target_name', seq_col: str = 'seq', chrom_col: str = 'chrom', start_col: str = 'start', end_col: str = 'end', genome_id_col: str | None = None, strand_col: str | None = None, ref_seq_col: str | None = None, alt_seq_col: str | None = None, replace_current_seq_variants: bool = False)[source]

Update a PMO’s representative microhaplotypes with associated sequence variants, from a table with one row per variant

Parameters:

  • pmo – the PMO to update, will directly modify this PMO

  • seq_variants_info – the sequence variants table

  • target_name_col – the column containing the target name of the microhaplotype

  • seq_col – the column containing the sequence of the microhaplotype

  • chrom_col – the column containing the chromosome of the variant

  • start_col – the column containing the start of the variant, 0-based

  • end_col – the column containing the end of the variant, 0-based

  • genome_id_col – (Optional) the column containing the index into targeted_genomes. Default: 0 for every variant

  • strand_col – (Optional) the column containing the strand of the variant

  • ref_seq_col – (Optional) the column containing the reference sequence of the variant

  • alt_seq_col – (Optional) the column containing the alternative sequence of the variant

  • replace_current_seq_variants – whether to replace current sequence variants for the microhaplotypes in the table

Returns:

a reference to the updated PMO

static update_specimen_meta_with_traveler_info(pmo, traveler_info: DataFrame, specimen_name_col: str = 'specimen_name', travel_country_col: str = 'travel_country', travel_start_col: str = 'travel_start_date', travel_end_col: str = 'travel_end_date', bed_net_usage_col: str = None, geo_admin1_col: str = None, geo_admin2_col: str = None, geo_admin3_col: str = None, lat_lon_col: str = None, replace_current_traveler_info: bool = False)[source]

Update a PMO’s specimen’s metadata with travel info

Parameters:

  • pmo – the PMO to update, will directly modify this PMO

  • traveler_info – the traveler info

  • specimen_name_col – the specimen name column within the traveler input table

  • travel_country_col – the column name containing the traveled to country

  • travel_start_col – the column name containing the traveled start date, format YYYY-MM-DD or YYYY-MM

  • travel_end_col – the column name containing the traveled end date, format YYYY-MM-DD or YYYY-MM

  • bed_net_usage_col – (Optional) a number between 0 - 1 for rough frequency of bednet usage while traveling

  • geo_admin1_col – (Optional) the column name containing the traveled to country admin level 1 info

  • geo_admin2_col – (Optional) the column name containing the traveled to country admin level 2 info

  • geo_admin3_col – (Optional) the column name containing the traveled to country admin level 3 info

  • lat_lon_col – (Optional) the latitude and longitude column name containing the region traveled to latitude and longitude

  • replace_current_traveler_info – whether to replace current travel info

Returns:

a reference to the updated PMO

static update_target_info_with_markers_of_interest(pmo, markers_info: DataFrame, target_name_col: str = 'target_name', chrom_col: str = 'chrom', start_col: str = 'start', end_col: str = 'end', genome_id_col: str | None = None, strand_col: str | None = None, ref_seq_col: str | None = None, alt_seq_col: str | None = None, associations_col: str | None = None, associations_delim: str = ',', replace_current_markers: bool = False)[source]

Update a PMO’s target_info with markers of interest, from a table with one row per marker

Parameters:

  • pmo – the PMO to update, will directly modify this PMO

  • markers_info – the markers of interest table

  • target_name_col – the column containing the name of the target the marker is covered by

  • chrom_col – the column containing the chromosome of the marker

  • start_col – the column containing the start of the marker, 0-based

  • end_col – the column containing the end of the marker, 0-based

  • genome_id_col – (Optional) the column containing the index into targeted_genomes. Default: 0 for every marker

  • strand_col – (Optional) the column containing the strand of the marker

  • ref_seq_col – (Optional) the column containing the reference sequence of the marker

  • alt_seq_col – (Optional) the column containing an alternative sequence of the marker

  • associations_col – (Optional) the column containing associations with the marker, e.g. SP resistance

  • associations_delim – the delimiter between associations. Default: ‘,’

  • replace_current_markers – whether to replace current markers of interest for the targets in the table

Returns:

a reference to the updated PMO