| Title: | MD Analysis of Residue Properties Using Structural Alphabets |
|---|---|
| Description: | Analyze molecular dynamics (MD) simulation data using structural alphabets. Protein local conformations from molecular simulations are encoded in a compressed string representation. Residue-level UniProt annotations can be directly retrieved. Comparative analysis tools are available to investigate conformational variability, coordinated motions, and differences between systems (e.g. wild-type vs mutant; bound vs unbound). Methodological details for the structural alphabet analysis can be found in Pandini et al. (2013) <doi:10.1093/bioinformatics/btt326>. |
| Authors: | Nancy D'Arminio [aut] (ORCID: <https://orcid.org/0000-0002-8065-2142>), Anna Marabotti [aut] (ORCID: <https://orcid.org/0000-0002-9510-5205>), Alessandro Pandini [aut, cph, cre] (ORCID: <https://orcid.org/0000-0002-4158-233X>) |
| Maintainer: | Alessandro Pandini <[email protected]> |
| License: | GPL-3 |
| Version: | 0.0.2 |
| Built: | 2026-09-25 08:59:01 UTC |
| Source: | https://github.com/cran/MDaRes |
Fetches active site annotations (ft_act_site) from UniProt
for a given protein accession code and structures them into a dataframe.
add_active_site(accession_code)add_active_site(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for active site annotations using the GetProteinAnnontate
function from the UniprotR package. It extracts the positions of active sites
and their functional notes, then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The residue position of the active site.
ActiveSite: Character. A description of the active site function.
if (interactive()) { active_sites_df <- add_active_site("P12345") head(active_sites_df) }if (interactive()) { active_sites_df <- add_active_site("P12345") head(active_sites_df) }
Fetches ligand binding site annotations (ft_binding) from UniProt
for a given protein accession code and structures them into a dataframe.
add_binding_site(accession_code)add_binding_site(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for ligand binding site annotations using the GetProteinAnnontate
function from the UniprotR package. It extracts ligand names and their corresponding residue
positions, then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The position(s) of the ligand binding site annotation.
LigandBindingSite: Character. The name of the ligand binding site.
if (interactive()) { binding_sites_df <- add_binding_site("P12345") head(binding_sites_df) }if (interactive()) { binding_sites_df <- add_binding_site("P12345") head(binding_sites_df) }
Fetches disulfide bond annotations (ft_disulfid) from UniProt
for a given protein accession code and structures them into a dataframe.
add_disulfide_bond(accession_code)add_disulfide_bond(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., "P12345"). |
This function queries UniProt for disulfide bond annotations using the
GetProteinAnnontate function from the UniprotR package. It parses
entries labeled with "DISULFID", extracts residue positions provided either
as single positions (e.g., "150") or ranges (e.g., "99..231"), and
expands ranges into per-residue rows.
Character strings equal to "NA" are converted to proper NA values.
If no annotations are found (i.e., the retrieved field is NULL, NA,
or empty), the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The residue position(s) involved in the disulfide bond.
DisulfideBond: Character. A label for the detected bond (set to "Bridge").
if (interactive()) { disulfide_df <- add_disulfide_bond("P12345") head(disulfide_df) }if (interactive()) { disulfide_df <- add_disulfide_bond("P12345") head(disulfide_df) }
Fetches domain annotations (ft_domain) from UniProt for a given protein accession code
and structures them into a dataframe.
add_domain(accession_code)add_domain(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for domain annotations using the GetProteinAnnontate function
from the UniprotR package. It extracts domain names and their corresponding residue positions,
then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The position(s) of the domain annotation.
Domain: Character. The name of the protein domain.
if (interactive()) { domain_df <- add_domain("P12345") head(domain_df) }if (interactive()) { domain_df <- add_domain("P12345") head(domain_df) }
Fetches glycosylation site annotations (ft_carbohyd) from UniProt
for a given protein accession code and structures them into a dataframe.
add_glycosilation(accession_code)add_glycosilation(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for glycosylation site annotations using the GetProteinAnnontate
function from the UniprotR package. It extracts the positions of glycosylation sites
and their functional notes, then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The residue position of the glycosylation site.
Glycosylation: Character. A description of the glycosylation modification.
if (interactive()) { glycosylation_df <- add_glycosilation("P12345") head(glycosylation_df) }if (interactive()) { glycosylation_df <- add_glycosilation("P12345") head(glycosylation_df) }
Fetches lipidation site annotations (ft_lipid) from UniProt
for a given protein accession code and structures them into a dataframe.
add_lipidation(accession_code)add_lipidation(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for lipidation site annotations using the GetProteinAnnontate
function from the UniprotR package. It extracts the positions of lipidation sites
and their functional notes, then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The residue position of the lipidation site.
Lipidation: Character. A description of the lipidation modification.
if (interactive()) { lipidation_df <- add_lipidation("P12345") head(lipidation_df) }if (interactive()) { lipidation_df <- add_lipidation("P12345") head(lipidation_df) }
Fetches subcellular location annotations (ft_intramem, ft_transmem, ft_topo_dom)
from UniProt for a given protein accession code and structures them into a dataframe.
add_location(accession_code)add_location(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for subcellular location annotations using the
GetProteinAnnontate function from the UniprotR package. It extracts
the location type (e.g., "INTRAMEM", "TRANSMEM", "TOPO_DOM") and the corresponding residue positions,
then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The position(s) of the location annotation.
Location: Character. The type of location with an associated note (e.g., "TRANSMEM: Helical").
if (interactive()) { location_df <- add_location("P12345") head(location_df) }if (interactive()) { location_df <- add_location("P12345") head(location_df) }
Fetches modified residue annotations (ft_mod_res) from UniProt
for a given protein accession code and structures them into a dataframe.
add_modified_residue(accession_code)add_modified_residue(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for modified residue site annotations using the GetProteinAnnontate
function from the UniprotR package. It extracts the positions of modified residues
and their functional notes, then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The residue position of the modification.
ModifiedResidue: Character. A description of the residue modification.
if (interactive()) { modified_residue_df <- add_modified_residue("P12345") head(modified_residue_df) }if (interactive()) { modified_residue_df <- add_modified_residue("P12345") head(modified_residue_df) }
Fetches molecule processing annotations (ft_chain) from UniProt
for a given protein accession code and structures them into a dataframe.
add_molecule_processing(accession_code)add_molecule_processing(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for molecule processing annotations using the
GetProteinAnnontate function from the UniprotR package. It extracts
the molecule processing type and the corresponding residue positions, then structures
them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The position(s) of the molecule processing event.
MoleculeProcessing: Character. The type of molecule processing (e.g., "CHAIN").
if (interactive()) { molecule_processing_df <- add_molecule_processing("P12345") head(molecule_processing_df) }if (interactive()) { molecule_processing_df <- add_molecule_processing("P12345") head(molecule_processing_df) }
Fetches motif annotations (ft_motif) from UniProt for a given protein accession code
and structures them into a dataframe.
add_motive(accession_code)add_motive(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for motif annotations using the GetProteinAnnontate function
from the UniprotR package. It extracts the motif type and the corresponding residue positions,
then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The position(s) of the motif annotation.
Motive: Character. The type of motif.
if (interactive()) { motif_df <- add_motive("P12345") head(motif_df) }if (interactive()) { motif_df <- add_motive("P12345") head(motif_df) }
Fetches secondary structure annotations (ft_turn, ft_helix, and ft_strand)
from UniProt for a given protein accession code and structures them into a dataframe.
add_secondary_structure(accession_code)add_secondary_structure(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for secondary structure annotations (turns, helices, and strands) using the
GetProteinAnnontate function from the UniprotR package. It extracts the structure type and
corresponding residue positions, then structures them into a dataframe.
If no annotations are found, the function returns an empty dataframe.
A dataframe with the following columns:
Position: Numeric. The residue position of the secondary structure element.
SecondaryStructure: Character. The type of secondary structure (TURN, HELIX, STRAND).
if (interactive()) { secondary_structure_df <- add_secondary_structure("P12345") head(secondary_structure_df) }if (interactive()) { secondary_structure_df <- add_secondary_structure("P12345") head(secondary_structure_df) }
Fetches various annotations from UniProt (e.g., variants, domains, secondary structure) and merges them into a single dataframe for a given protein accession code.
add_uniprot_annotation(accession_code, total_ranking = NULL)add_uniprot_annotation(accession_code, total_ranking = NULL)
accession_code |
Character. The UniProt accession code of the protein (e.g., "P12345"). |
total_ranking |
Optional dataframe. If provided, the function will return annotation information aggregated over the fragments defined by the start-end positions in the ranking. |
This function calls multiple UniProt annotation functions (add_variants, add_domain, add_location, etc.)
and merges their results into a unified dataframe, ensuring missing values are replaced with meaningful defaults.
If a UniProt API request fails or an annotation is unavailable, the respective column is filled with default values.
If total_ranking is provided, it must contain the columns start, end, entropy, median_MI, and collectivity.
The function will expand each fragment into its constituent residue positions, merge them with UniProt annotations,
and return a dataframe where annotations are concatenated for each fragment.
A dataframe.
If total_ranking is not provided, each row represents a residue position with the following columns:
Position: Numeric. Residue position.
anPosition: Character. Combined annotation position (e.g., "P12345_1").
Residue: Character. Residue identity (e.g., "A", "G", "L").
Variant: Character. Mutation information or "no_variant" if absent.
Location: Character. Membrane location or "EXTRAMEM" if absent.
Motive: Character. Motif annotation or "no_motive" if absent.
Domain: Character. Structural domain or "no_domain" if absent.
LigandBindingSite: Character. Ligand binding site or "no_ligand" if absent.
ActiveSite: Character. Active site information or "no_active_site" if absent.
Glycosylation: Character. Glycosylation details or "no_glycans" if absent.
Lipidation: Character. Lipidation details or "no_lipid" if absent.
ModifiedResidue: Character. Post-translational modification details or "no_modifications" if absent.
DisulfideBond: Character. Disulfide bond information or "no_bridge" if absent.
SecondaryStructure: Character. Secondary structure type or "unknown" if absent.
If total_ranking is provided, each row corresponds to a fragment and includes:
start, end, entropy, median_MI, collectivity
plus concatenated annotation columns for all positions in the fragment (e.g., Residues, Variants, etc.)
if (interactive()) { ranking_file <- system.file( "extdata", "example_total_ranking.RDS", package = "MDaRes" ) ranking <- readRDS(ranking_file) annotated_fragments <- add_uniprot_annotation( accession_code = "P69905", total_ranking = ranking ) head(annotated_fragments) }if (interactive()) { ranking_file <- system.file( "extdata", "example_total_ranking.RDS", package = "MDaRes" ) ranking <- readRDS(ranking_file) annotated_fragments <- add_uniprot_annotation( accession_code = "P69905", total_ranking = ranking ) head(annotated_fragments) }
Fetches protein variant annotations from UniProt for a given accession code and structures them into a dataframe.
add_variants(accession_code)add_variants(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt for variant annotations (ft_variant) using the
GetProteinAnnontate function from the UniprotR package. It extracts the
variant position, mutation information, and UniProt variant ID, then structures them
into a dataframe.
The function ensures proper handling of missing values and returns an empty dataframe if no variants are found.
A dataframe with the following columns:
Position: Numeric. The position of the variant in the protein sequence.
Variant: Character. The UniProt variant ID and the mutation change (e.g., "VAR_123456 : A -> T").
if (interactive()) { variant_df <- add_variants("P12345") head(variant_df) }if (interactive()) { variant_df <- add_variants("P12345") head(variant_df) }
This function removes a specific prefix from a string and returns the modified string. It is typically used to clean column names by removing unnecessary prefixes.
colnames_substring(string)colnames_substring(string)
string |
A character vector representing column names or strings containing the prefix "Frag: ". |
A character vector with the prefix "Frag: " removed from each element.
Retrieves the amino acid sequence from UniProt for a given protein accession code and formats it into a structured dataframe.
create_annotation_df(accession_code)create_annotation_df(accession_code)
accession_code |
Character. The UniProt accession code of the protein (e.g., |
This function queries UniProt to fetch the full protein sequence using the GetSequences
function from the UniprotR package. The sequence is then split into individual residues
and structured into a dataframe where each row represents a residue with its sequential position.
A dataframe with the following columns:
Position: Numeric. The residue position in the sequence.
anPosition: Character. The annotated position formatted as "ACCESSION_POSITION".
Residue: Character. The single-letter amino acid code at the given position.
Wrapper around freq_diff_plot that saves the plot as a PNG file.
do_freq_diff_plot( first_freq, second_freq, output_name, width = 1800, height = 800, res = 120, ... )do_freq_diff_plot( first_freq, second_freq, output_name, width = 1800, height = 800, res = 120, ... )
first_freq |
A |
second_freq |
A |
output_name |
Character. Output file path without extension (".png" is appended). |
width, height
|
Integer. PNG size in pixels. |
res |
Integer. PNG resolution (ppi). |
... |
Additional arguments passed to |
Invisibly returns the frequency-difference matrix.
Generates a structural sequence profile plot and saves it as a PNG file.
do_freq_plot(shannon_output, output_name)do_freq_plot(shannon_output, output_name)
shannon_output |
A list of class |
output_name |
Character. The filename (without extension) for the output image. |
The function calls freq_plot() to generate the plot and saves it as a PNG file.
The function does not return anything but creates a PNG file.
shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) output_base <- tempfile("frequency-plot-") output_file <- paste0(output_base, ".png") do_freq_plot(shannon_output, output_base) file.exists(output_file) unlink(output_file)shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) output_base <- tempfile("frequency-plot-") output_file <- paste0(output_base, ".png") do_freq_plot(shannon_output, output_base) file.exists(output_file) unlink(output_file)
Generates a heatmap of the mutual information matrix and saves it as a PNG file.
do_MI_plot(MI_matrix, output_name)do_MI_plot(MI_matrix, output_name)
MI_matrix |
A list of class |
output_name |
Character. The filename (without extension) for the output image. |
The function calls MI_plot() to generate the plot and saves it as a PNG file.
The function does not return anything but creates a PNG file.
mi_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(mi_file) output_base <- tempfile("MI-plot-") output_file <- paste0(output_base, ".png") do_MI_plot(MI_output, output_base) file.exists(output_file) unlink(output_file)mi_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(mi_file) output_base <- tempfile("MI-plot-") output_file <- paste0(output_base, ".png") do_MI_plot(MI_output, output_base) file.exists(output_file) unlink(output_file)
Wrapper around shannon_entropy_diff_plot that opens a PNG device, draws the plot,
and closes the device. This is useful for batch workflows where plots must be written to disk
without manual interaction.
do_shannon_entropy_diff_plot( first_shannon, second_shannon, output_name, overlay = TRUE, width = 2600, height = 1200, res = 220 )do_shannon_entropy_diff_plot( first_shannon, second_shannon, output_name, overlay = TRUE, width = 2600, height = 1200, res = 220 )
first_shannon |
A |
second_shannon |
A |
output_name |
Character. Output path without file extension. The function will write
|
overlay |
Logical. If |
width |
Integer. PNG width in pixels. Defaults to |
height |
Integer. PNG height in pixels. Defaults to |
res |
Integer. PNG resolution in dots per inch. Defaults to |
The function uses png to create the file device and ensures that
dev.off is called even if an error occurs during plotting (via
on.exit).
Invisibly returns the entropy difference vector (the same value returned invisibly by
shannon_entropy_diff_plot).
first_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) second_file <- system.file( "extdata", "example_shannon_entropy_2.RDS", package = "MDaRes" ) sh1 <- readRDS(first_file) sh2 <- readRDS(second_file) output_base <- tempfile("shannon-difference-") output_file <- paste0(output_base, ".png") do_shannon_entropy_diff_plot(sh1, sh2, output_base) file.exists(output_file) unlink(output_file)first_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) second_file <- system.file( "extdata", "example_shannon_entropy_2.RDS", package = "MDaRes" ) sh1 <- readRDS(first_file) sh2 <- readRDS(second_file) output_base <- tempfile("shannon-difference-") output_file <- paste0(output_base, ".png") do_shannon_entropy_diff_plot(sh1, sh2, output_base) file.exists(output_file) unlink(output_file)
Generates a Shannon entropy plot and saves it as a PNG file.
do_shannon_entropy_plot(shannon_output, output_name)do_shannon_entropy_plot(shannon_output, output_name)
shannon_output |
A list of class |
output_name |
Character. The filename (without extension) for the output image. |
The function calls shannon_entropy_plot() to generate the plot and saves it as a PNG file.
The function does not return anything but creates a PNG file.
shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) output_base <- tempfile("shannon-plot-") output_file <- paste0(output_base, ".png") do_shannon_entropy_plot(shannon_output, output_base) file.exists(output_file) unlink(output_file)shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) output_base <- tempfile("shannon-plot-") output_file <- paste0(output_base, ".png") do_shannon_entropy_plot(shannon_output, output_base) file.exists(output_file) unlink(output_file)
Maps fragment-based Shannon entropy values onto a protein structure by storing residue-wise entropy values in the B-factor column of a PDB file. A companion PyMOL script is generated to visualize the modified structure using cartoon putty representation and B-factor based coloring.
entropy_visualization(pdb_filename, chain = NULL, shannon_output)entropy_visualization(pdb_filename, chain = NULL, shannon_output)
pdb_filename |
Character string. Path to the input PDB or CIF file. |
chain |
Character string or NULL. Chain identifier to retain, for example "A". If NULL, all chains are retained. |
shannon_output |
A list produced by |
Shannon entropy values are computed for structural fragments, whereas PyMOL visualizes atom-based or residue-based properties. Therefore, this function first converts fragment entropy values into residue entropy values. For each residue in the structure, the assigned entropy is calculated as the mean entropy of all fragments spanning that residue.
The resulting residue-wise entropy values are written into the B-factor column of the output PDB file. All atoms belonging to the same residue receive the same entropy value.
Two output files are generated in the same directory as the input structure:
<input>-bfactor.pdb: PDB file with entropy values stored in
the B-factor column.
<input>-bfactor.pml: PyMOL script for cartoon putty
visualization and B-factor based coloring.
Invisibly returns a list with the following elements:
output_pdb: Path to the generated PDB file.
output_pml: Path to the generated PyMOL script.
entropy_per_residue: Named numeric vector containing the
entropy value assigned to each residue.
source_pdb <- system.file( "extdata", "example_calpha_ref.pdb", package = "MDaRes" ) shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) working_pdb <- tempfile(fileext = ".pdb") file.copy(source_pdb, working_pdb) shannon_output <- readRDS(shannon_file) result <- entropy_visualization( pdb_filename = working_pdb, chain = "A", shannon_output = shannon_output ) file.exists(result$output_pdb) file.exists(result$output_pml) unlink(c( working_pdb, result$output_pdb, result$output_pml ))source_pdb <- system.file( "extdata", "example_calpha_ref.pdb", package = "MDaRes" ) shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) working_pdb <- tempfile(fileext = ".pdb") file.copy(source_pdb, working_pdb) shannon_output <- readRDS(shannon_file) result <- entropy_visualization( pdb_filename = working_pdb, chain = "A", shannon_output = shannon_output ) file.exists(result$output_pdb) file.exists(result$output_pml) unlink(c( working_pdb, result$output_pdb, result$output_pml ))
Generates a heatmap of per-fragment Structural Alphabet frequency
differences between two shannon_list objects. The plotted quantity is
.
freq_diff_plot( first_freq, second_freq, zlim = c(-1, 1), n_ticks = 12, main = "Structural sequence profile (Deltafreq)", ylab = "SA Letter", letters = LETTERS[1:25], palette_fun = grDevices::colorRampPalette(c("blue", "white", "red"), space = "rgb"), n_col = 101, show_colorbar = TRUE, colorbar_width = 0.04, colorbar_gap = 0.05, mar = c(6, 4, 4, 6) )freq_diff_plot( first_freq, second_freq, zlim = c(-1, 1), n_ticks = 12, main = "Structural sequence profile (Deltafreq)", ylab = "SA Letter", letters = LETTERS[1:25], palette_fun = grDevices::colorRampPalette(c("blue", "white", "red"), space = "rgb"), n_col = 101, show_colorbar = TRUE, colorbar_width = 0.04, colorbar_gap = 0.05, mar = c(6, 4, 4, 6) )
first_freq |
A |
second_freq |
A |
zlim |
Numeric vector of length 2. Limits of the color scale for
|
n_ticks |
Integer. Approximate number of x-axis residue ticks to show.
Default is |
main |
Character. Plot title. |
ylab |
Character. Y-axis label. |
letters |
Character vector of SA letters. Length must match the number of rows in the frequency matrix. |
palette_fun |
Function that generates the color palette. |
n_col |
Integer. Number of colors used for the heatmap. |
show_colorbar |
Logical. If |
colorbar_width |
Numeric. Relative width of the colorbar region. |
colorbar_gap |
Numeric. Gap between heatmap and colorbar. |
mar |
Numeric vector of length 4. Plot margins. |
Positive values indicate higher frequency in first_freq; negative values
indicate higher frequency in second_freq. The colorbar is drawn inside an
expanded x-axis region to avoid clipping when saving to image files.
Invisibly returns the frequency-difference matrix.
first_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) second_file <- system.file( "extdata", "example_shannon_entropy_2.RDS", package = "MDaRes" ) sh1 <- readRDS(first_file) sh2 <- readRDS(second_file) freq_diff_plot(sh1, sh2)first_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) second_file <- system.file( "extdata", "example_shannon_entropy_2.RDS", package = "MDaRes" ) sh1 <- readRDS(first_file) sh2 <- readRDS(second_file) freq_diff_plot(sh1, sh2)
Generates a heatmap representing the structural sequence frequency profile obtained from Structural Alphabet encoding.
freq_plot(shannon_output)freq_plot(shannon_output)
shannon_output |
A list of class |
The frequency matrix is plotted as a heatmap where rows correspond to Structural Alphabet letters and columns correspond to encoded fragments. Residue labels on the x-axis are shown at reduced density to avoid overcrowding.
A heatmap displaying the frequency of Structural Alphabet letters along the encoded sequence.
shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) freq_plot(shannon_output)shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) freq_plot(shannon_output)
This function extracts residue numbering from the column names of an encoded trajectory. It is useful for labeling plots with meaningful residue numbers instead of generic column names.
get_res_numbering(encoded_trajectory)get_res_numbering(encoded_trajectory)
encoded_trajectory |
A data frame or object of class |
A character vector containing cleaned residue numbering extracted from the column names.
Imports a structural alphabet from a set of PDB files.
import_SA( n_elements = 25, folder_path = normalizePath(system.file("SA", package = "MDaRes")), file_extension = ".pdb" )import_SA( n_elements = 25, folder_path = normalizePath(system.file("SA", package = "MDaRes")), file_extension = ".pdb" )
n_elements |
Integer. The number of structural alphabet elements to import. |
folder_path |
Character. Path to the folder containing the PDB files. |
file_extension |
Character. File extension of the structural alphabet files (e.g., ".pdb"). |
This function loads n_elements structures from the given folder and stores them in a named list
using capital letters (A-Z) as names. The bio3d package is used to read PDB files.
A named list of PDB objects, where each element corresponds to a structural alphabet letter.
SA <- import_SA()SA <- import_SA()
Generates a heatmap representing the mutual information between structural fragments.
MI_plot(MI_output)MI_plot(MI_output)
MI_output |
A list of class |
The function plots the normalized mutual information matrix and labels both axes using residue numbering when available. Tick density is reduced to avoid overcrowding in large systems.
A heatmap of mutual information values between structural fragments.
MI_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(MI_file) MI_plot(MI_output)MI_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(MI_file) MI_plot(MI_output)
Generates rankings of residue pairs based on mutual information values.
MI_ranking_couple(MI_output)MI_ranking_couple(MI_output)
MI_output |
A list of class |
A data frame ranking residue pairs by mutual information value.
MI_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(MI_file) MI_ranking_couple(MI_output)MI_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(MI_file) MI_ranking_couple(MI_output)
This function computes the median mutual information (MI) and the degree of collectivity for each fragment in a mutual information matrix. It is used to identify the most central and informative fragments based on information theory and spectral decomposition.
MI_ranking_median(MI_output)MI_ranking_median(MI_output)
MI_output |
An object of class |
The degree of collectivity is calculated as the contribution of the top 3 eigenmodes of the mutual information matrix. This metric highlights fragments that are involved in widespread, collective information exchanges.
A data frame containing the following columns:
start: Starting residue index for the fragment.
end: Ending residue index for the fragment.
median_MI: The median mutual information value for the fragment.
collectivity: A spectral-based measure of collectivity derived from the top eigenvectors of the MI matrix.
The data frame is sorted in descending order by median_MI.
MI_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(MI_file) ranked_fragments <- MI_ranking_median(MI_output)MI_file <- system.file( "extdata", "example_MI.RDS", package = "MDaRes" ) MI_output <- readRDS(MI_file) ranked_fragments <- MI_ranking_median(MI_output)
Computes a mutual information matrix from an encoded trajectory.
MImat(encoded_trajectory)MImat(encoded_trajectory)
encoded_trajectory |
A data frame of class |
A list of class MI_list containing the mutual information matrix and residue numbering.
encoding_file <- system.file( "extdata", "example_encoding.RDS", package = "MDaRes" ) encoded_trj <- readRDS(encoding_file) encoded_trj <- encoded_trj[ , seq_len(min(10L, ncol(encoded_trj))), drop = FALSE ] MI_output <- MImat(encoded_trj)encoding_file <- system.file( "extdata", "example_encoding.RDS", package = "MDaRes" ) encoded_trj <- readRDS(encoding_file) encoded_trj <- encoded_trj[ , seq_len(min(10L, ncol(encoded_trj))), drop = FALSE ] MI_output <- MImat(encoded_trj)
Computes the normalized mutual information matrix from a structural alphabet trajectory.
nMImat(SA_output)nMImat(SA_output)
SA_output |
A data frame of class |
A matrix representing normalized mutual information values.
Encodes a molecular dynamics (MD) trajectory using a 4-residue structural alphabet (SA). For each frame and for each 4-residue fragment, the closest SA letter is assigned based on Kabsch-aligned RMSD computed in C++.
SA_encoding( SA, trj_name, top_name, pdb_name, sel_chain, parallel = c("none", "future"), workers = NULL, future_plan = NULL, verbose = TRUE )SA_encoding( SA, trj_name, top_name, pdb_name, sel_chain, parallel = c("none", "future"), workers = NULL, future_plan = NULL, verbose = TRUE )
SA |
List. Structural alphabet, indexed by |
trj_name |
Character. Path to the trajectory file (e.g. XTC, DCD). |
top_name |
Character. Path to the topology file (as required by
|
pdb_name |
Character. Path to the reference structure file (PDB or CIF). |
sel_chain |
Character. Chain identifier to be encoded (e.g. |
parallel |
Character. Either |
workers |
Integer or |
future_plan |
A |
verbose |
Logical. If |
A data frame of class "enc_trj" with one row per frame and one
column per fragment (e.g. "Frag: 1_4", "Frag: 2_5", ...), containing
SA letters (A..Y).
This function calculates the Shannon entropy and the frequency of structural alphabet letters in an encoded trajectory.
shannon_entropy(encoded_trajectory)shannon_entropy(encoded_trajectory)
encoded_trajectory |
A data frame of class |
Shannon entropy is calculated for each fragment in the trajectory using the frequency of different structural alphabet letters.
The frequency matrix (freq) contains the normalized frequency of each letter (A-Z).
A list of class shannon_list with the following components:
freq: A 25xN matrix of frequency values, where N is the number of fragments.
entropy: A numeric vector containing Shannon entropy values for each fragment.
residue_numbering: A character vector representing residue numbers.
encoding_file <- system.file( "extdata", "example_encoding.RDS", package = "MDaRes" ) encoded_trj <- readRDS(encoding_file) shannon_output <- shannon_entropy(encoded_trj) print(shannon_output$entropy)encoding_file <- system.file( "extdata", "example_encoding.RDS", package = "MDaRes" ) encoded_trj <- readRDS(encoding_file) shannon_output <- shannon_entropy(encoded_trj) print(shannon_output$entropy)
Plots the pointwise difference between two Shannon entropy profiles,
, with a zero baseline. Optionally
overlays the two original entropy curves on a right-hand axis.
shannon_entropy_diff_plot(first_out, second_out, overlay = FALSE)shannon_entropy_diff_plot(first_out, second_out, overlay = FALSE)
first_out |
A |
second_out |
A |
overlay |
Logical. If |
Both inputs must be of class shannon_list and their entropy vectors must
have the same length. The left y-axis is centered at 0 and scaled
symmetrically to the range of . When overlay = TRUE, the
original entropy curves are drawn using a right-hand axis.
Invisibly returns the numeric vector used for plotting.
first_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) second_file <- system.file( "extdata", "example_shannon_entropy_2.RDS", package = "MDaRes" ) sh1 <- readRDS(first_file) sh2 <- readRDS(second_file) shannon_entropy_diff_plot(sh1, sh2) shannon_entropy_diff_plot(sh1, sh2, overlay = TRUE)first_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) second_file <- system.file( "extdata", "example_shannon_entropy_2.RDS", package = "MDaRes" ) sh1 <- readRDS(first_file) sh2 <- readRDS(second_file) shannon_entropy_diff_plot(sh1, sh2) shannon_entropy_diff_plot(sh1, sh2, overlay = TRUE)
This function generates a Shannon entropy profile from a shannon_list
object produced by shannon_entropy().
shannon_entropy_plot(shannon_output)shannon_entropy_plot(shannon_output)
shannon_output |
A list of class |
The function plots entropy values along the sequence and adds horizontal and vertical grid lines for readability. Residue labels on the x-axis are shown at reduced density to avoid overcrowding in large systems.
A plot displaying Shannon entropy across the encoded sequence.
shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) shannon_entropy_plot(shannon_output)shannon_file <- system.file( "extdata", "example_shannon_entropy.RDS", package = "MDaRes" ) shannon_output <- readRDS(shannon_file) shannon_entropy_plot(shannon_output)
Creates a ranking table of fragments/residue ranges ordered by Shannon entropy (descending).
The function expects a shannon_list object containing entropy and residue_numbering.
shannon_ranking(shannon_output)shannon_ranking(shannon_output)
shannon_output |
An object of class
|
A data.frame with columns entropy, start, end, sorted by decreasing entropy.
encoding_file <- system.file( "extdata", "example_encoding.RDS", package = "MDaRes" ) encoded_trj <- readRDS(encoding_file) shannon_output <- shannon_entropy(encoded_trj) shannon_ranking(shannon_output)encoding_file <- system.file( "extdata", "example_encoding.RDS", package = "MDaRes" ) encoded_trj <- readRDS(encoding_file) shannon_output <- shannon_entropy(encoded_trj) shannon_ranking(shannon_output)
Merges Shannon entropy and mutual information rankings into a single data frame.
total_ranking(shannon_ranking_df, MI_median_ranking_df)total_ranking(shannon_ranking_df, MI_median_ranking_df)
shannon_ranking_df |
Data frame containing Shannon entropy rankings. |
MI_median_ranking_df |
Data frame containing mutual information median rankings. |
A merged ranking data frame.
shannon_file <- system.file( "extdata", "example_shannon_ranking.RDS", package = "MDaRes" ) mi_file <- system.file( "extdata", "example_MI_ranking_median.RDS", package = "MDaRes" ) shannon_ranking_df <- readRDS(shannon_file) MI_median_ranking_df <- readRDS(mi_file) total_ranking(shannon_ranking_df, MI_median_ranking_df)shannon_file <- system.file( "extdata", "example_shannon_ranking.RDS", package = "MDaRes" ) mi_file <- system.file( "extdata", "example_MI_ranking_median.RDS", package = "MDaRes" ) shannon_ranking_df <- readRDS(shannon_file) MI_median_ranking_df <- readRDS(mi_file) total_ranking(shannon_ranking_df, MI_median_ranking_df)