models

DataRepository

Bases: BaseModel

Information about the data repository where the source data is published

Source code in hdxms_datasets/models.py

class DataRepository(BaseModel):
    """Information about the data repository where the source data is published"""

    name: Annotated[str, Field(..., description="Repository name")]  # ie Pride, Zenodo,
    url: Annotated[Optional[HttpUrl], Field(None, description="Repository URL")]
    identifier: Annotated[Optional[str], Field(None, description="Repository entry identifier")]
    doi: Annotated[Optional[str], Field(None, description="Repository DOI")]
    description: Annotated[Optional[str], Field(None, description="Repository description")]

DeuterationType

Bases: str, Enum

Type of the peptide

Source code in hdxms_datasets/models.py

class DeuterationType(str, Enum):
    """Type of the peptide"""

    partially_deuterated = "partially_deuterated"
    fully_deuterated = "fully_deuterated"
    non_deuterated = "non_deuterated"

HDXDataSet

Bases: BaseModel

HDX-MS dataset containing multiple states

Source code in hdxms_datasets/models.py

class HDXDataSet(BaseModel):
    """HDX-MS dataset containing multiple states"""

    # Basic information
    description: Annotated[Optional[str], Field(None, description="Dataset description")]

    states: list[State] = Field(description="List of HDX states in the dataset")
    structure: Annotated[Structure, Field(description="Structural model file path")]
    protein_identifiers: Annotated[
        ProteinIdentifiers, Field(description="Protein identifiers (UniProt, etc.)")
    ]
    metadata: Annotated[DatasetMetadata, Field(description="Dataset metadata")]
    file_hash: Annotated[
        Optional[str], Field(None, init=False, description="Hash of the files in the dataset")
    ]

    @model_validator(mode="after")
    def compute_file_hash(self):
        """Compute a hash of the dataset based on its data files"""
        if any(not p.exists() for p in self.data_files):
            self.file_hash = None
            return self

        self.file_hash = self.hash_files()[:16]  # Shorten to 16 characters

        return self

    def hash_files(self) -> str:
        return hash_files(self.data_files)  # Ensure files are sorted and hashed consistently

    def validate_file_integrity(self) -> bool:
        """match hash of files with the stored hash"""
        if self.file_hash is None:
            return False
        current_hash = self.hash_files()
        return current_hash.startswith(self.file_hash)

    def get_state(self, state: str | int) -> State:
        """Get a specific state by name or index"""
        if isinstance(state, int):
            return self.states[state]
        elif isinstance(state, str):
            for s in self.states:
                if s.name == state:
                    return s
        raise ValueError(f"State '{state}' not found in dataset.")

    @property
    def data_files(self) -> list[Path]:
        """List of all data files in the dataset"""
        return sorted(set(extract_values_by_types(self, Path)))

    @classmethod
    def from_json(
        cls,
        json_str: str,
        dataset_root: Optional[Path] = None,
    ) -> HDXDataSet:
        """Load dataset from JSON string"""
        if dataset_root is None:
            context = {}
        else:
            context = {"dataset_root": dataset_root}
        return cls.model_validate_json(json_str, context=context)

data_files: list[Path] property

List of all data files in the dataset

compute_file_hash()

Compute a hash of the dataset based on its data files

Source code in hdxms_datasets/models.py

@model_validator(mode="after")
def compute_file_hash(self):
    """Compute a hash of the dataset based on its data files"""
    if any(not p.exists() for p in self.data_files):
        self.file_hash = None
        return self

    self.file_hash = self.hash_files()[:16]  # Shorten to 16 characters

    return self

from_json(json_str, dataset_root=None) classmethod

Load dataset from JSON string

Source code in hdxms_datasets/models.py

@classmethod
def from_json(
    cls,
    json_str: str,
    dataset_root: Optional[Path] = None,
) -> HDXDataSet:
    """Load dataset from JSON string"""
    if dataset_root is None:
        context = {}
    else:
        context = {"dataset_root": dataset_root}
    return cls.model_validate_json(json_str, context=context)

get_state(state)

Get a specific state by name or index

Source code in hdxms_datasets/models.py

def get_state(self, state: str | int) -> State:
    """Get a specific state by name or index"""
    if isinstance(state, int):
        return self.states[state]
    elif isinstance(state, str):
        for s in self.states:
            if s.name == state:
                return s
    raise ValueError(f"State '{state}' not found in dataset.")

validate_file_integrity()

match hash of files with the stored hash

Source code in hdxms_datasets/models.py

def validate_file_integrity(self) -> bool:
    """match hash of files with the stored hash"""
    if self.file_hash is None:
        return False
    current_hash = self.hash_files()
    return current_hash.startswith(self.file_hash)

PeptideFormat

Bases: str, Enum

Format of the peptide data

Source code in hdxms_datasets/models.py

class PeptideFormat(str, Enum):
    """Format of the peptide data"""

    DynamX_v3_state = "DynamX_v3_state"
    DynamX_v3_cluster = "DynamX_v3_cluster"
    DynamX_vx_state = "DynamX_vx_state"
    HDExaminer_v3 = "HDExaminer_v3"
    OpenHDX = "OpenHDX"

    @classmethod
    def identify(cls, df: nw.DataFrame) -> PeptideFormat | None:
        """Identify format from DataFrame"""
        from hdxms_datasets.formats import identify_format

        fmt = identify_format(df)
        if fmt:
            return cls(fmt.name)
        return None

identify(df) classmethod

Identify format from DataFrame

Source code in hdxms_datasets/models.py

@classmethod
def identify(cls, df: nw.DataFrame) -> PeptideFormat | None:
    """Identify format from DataFrame"""
    from hdxms_datasets.formats import identify_format

    fmt = identify_format(df)
    if fmt:
        return cls(fmt.name)
    return None

Peptides

Bases: BaseModel

Information about HDX-MS peptides

Source code in hdxms_datasets/models.py

class Peptides(BaseModel):
    """Information about HDX-MS peptides"""

    data_file: DataFilePath
    data_format: Annotated[PeptideFormat, Field(description="Data format (e.g., OpenHDX)")]
    deuteration_type: Annotated[
        DeuterationType, Field(description="Type of the peptide (e.g., fully_deuterated)")
    ]
    chain: Annotated[Optional[list[str]], Field(description="Chain identifiers")] = None
    filters: Annotated[
        dict[str, ValueType | list[ValueType]],
        Field(default_factory=dict, description="Filters applied to the data"),
    ]
    pH: Annotated[
        Optional[float], Field(description="pH (read, uncorrected) of the experiment")
    ] = None
    temperature: Annotated[Optional[float], Field(description="Temperature in Kelvin")] = None
    d_percentage: Annotated[Optional[float], Field(description="Deuteration percentage")] = None
    ionic_strength: Annotated[Optional[float], Field(description="Ionic strength in Molar")] = None

    def load(
        self,
        convert: bool = True,
        aggregate: bool | None = None,
        sort_rows: bool = True,
        sort_columns: bool = True,
        drop_null: bool = True,
    ) -> nw.DataFrame:
        if self.data_file.exists():
            from hdxms_datasets.loader import load_peptides

            return load_peptides(
                self,
                convert=convert,
                aggregate=aggregate,
                sort_rows=sort_rows,
                sort_columns=sort_columns,
                drop_null=drop_null,
            )
        else:
            raise FileNotFoundError(f"Data file {self.data_file} does not exist.")

ProteinIdentifiers

Bases: BaseModel

general protein information

Source code in hdxms_datasets/models.py

class ProteinIdentifiers(BaseModel):
    """general protein information"""

    uniprot_accession_number: Annotated[Optional[str], Field(None, description="UniProt ID")] = None
    uniprot_entry_name: Annotated[Optional[str], Field(None, description="UniProt entry name")] = (
        None
    )
    protein_name: Annotated[Optional[str], Field(None, description="Recommended protein name")] = (
        None
    )

ProteinState

Bases: BaseModel

Protein information for a specific state

Source code in hdxms_datasets/models.py

class ProteinState(BaseModel):
    """Protein information for a specific state"""

    sequence: Annotated[str | list[str], Field(description="Amino acid sequence")]
    n_term: Annotated[int, Field(description="N-terminal residue number")]
    c_term: Annotated[int, Field(description="C-terminal residue number")]
    mutations: Annotated[Optional[list[str]], Field(description="List of mutations")] = None
    oligomeric_state: Annotated[Optional[int], Field(description="Oligomeric state")] = None
    ligand: Annotated[Optional[str], Field(description="Bound ligand information")] = None

    @model_validator(mode="after")
    def check_sequence(self):
        if len(self.sequence) != self.c_term - self.n_term + 1:
            raise ValueError("Sequence length does not match N-term and C-term residue numbers.")
        return self

Publication

Bases: BaseModel

Publication information

Source code in hdxms_datasets/models.py

class Publication(BaseModel):
    """Publication information"""

    title: Optional[str] = None
    authors: Optional[List[str]] = None
    journal: Optional[str] = None
    year: Optional[int] = None
    doi: Optional[str] = None
    pmid: Optional[str] = None
    url: Optional[str] = None

State

Bases: BaseModel

Information about HDX-MS state

Source code in hdxms_datasets/models.py

class State(BaseModel):
    """Information about HDX-MS state"""

    name: Annotated[str, Field(description="State name")]
    peptides: list[Peptides] = Field(..., description="List of peptides in this state")
    description: Annotated[str, Field(description="State description")] = ""  # TODO max length?
    protein_state: ProteinState = Field(..., description="Protein information for this state")

Structure

Bases: BaseModel

Structural model file information

Source code in hdxms_datasets/models.py

class Structure(BaseModel):
    """Structural model file information"""

    data_file: DataFilePath
    format: Annotated[str, Field(description="Format of the structure file (e.g., PDB, mmCIF)")]
    description: Annotated[Optional[str], Field(description="Description of the structure")] = None

    # source database identifiers
    pdb_id: Annotated[Optional[str], Field(None, description="RCSB PDB ID")] = None
    alphafold_id: Annotated[Optional[str], Field(None, description="AlphaFold ID")] = None

    auth_residue_numbers: Annotated[
        bool, Field(default=False, description="Use author residue numbers")
    ] = False
    residue_offset: Annotated[
        int,
        Field(
            default=0,
            description="Offset for residue numbering; structure numbers = hdx numbers + offset",
        ),
    ] = 0
    auth_chain_labels: Annotated[
        bool, Field(default=False, description="Use author chain labels")
    ] = False

    def pdbemolstar_custom_data(self) -> dict[str, Any]:
        """
        Returns a dictionary with custom data for PDBeMolstar visualization.
        """

        if self.format in ["bcif"]:
            binary = True
        else:
            binary = False

        if self.data_file.is_file():
            data = self.data_file.read_bytes()
        else:
            raise ValueError(f"Path {self.data_file} is not a file.")

        return {
            "data": data,
            "format": self.format,
            "binary": binary,
        }

pdbemolstar_custom_data()

Returns a dictionary with custom data for PDBeMolstar visualization.

Source code in hdxms_datasets/models.py

def pdbemolstar_custom_data(self) -> dict[str, Any]:
    """
    Returns a dictionary with custom data for PDBeMolstar visualization.
    """

    if self.format in ["bcif"]:
        binary = True
    else:
        binary = False

    if self.data_file.is_file():
        data = self.data_file.read_bytes()
    else:
        raise ValueError(f"Path {self.data_file} is not a file.")

    return {
        "data": data,
        "format": self.format,
        "binary": binary,
    }

extract_values_by_types(obj, target_types)

Recursively extract all values of specified type(s) from a nested structure. This function can handle Pydantic models, lists, tuples, sets, and dictionaries.

Parameters:

Name	Type	Description	Default
obj	Any	Pydantic model instance or any nested structure	required
target_types	Type | tuple[Type, ...]	Single type or tuple of types to search for	required

Returns:

Type	Description
list[Any]	List of all values matching any of the target types

Source code in hdxms_datasets/models.py

def extract_values_by_types(obj: Any, target_types: Type | tuple[Type, ...]) -> list[Any]:
    """
    Recursively extract all values of specified type(s) from a nested structure.
    This function can handle Pydantic models, lists, tuples, sets, and dictionaries.

    Args:
        obj: Pydantic model instance or any nested structure
        target_types: Single type or tuple of types to search for

    Returns:
        List of all values matching any of the target types
    """
    values = []

    # Normalize target_types to tuple
    if not isinstance(target_types, tuple):
        target_types = (target_types,)

    # Check if current object is of any target type
    if isinstance(obj, target_types):
        values.append(obj)

    elif isinstance(obj, BaseModel):
        # Iterate through all field values in the Pydantic model
        for field_name, field_value in obj.__dict__.items():
            values.extend(extract_values_by_types(field_value, target_types))

    elif isinstance(obj, (list, tuple, set)):
        # Handle sequences
        for item in obj:
            values.extend(extract_values_by_types(item, target_types))

    elif isinstance(obj, dict):
        # Handle dictionaries (both keys and values)
        for key, value in obj.items():
            values.extend(extract_values_by_types(key, target_types))
            values.extend(extract_values_by_types(value, target_types))

    return values

hash_files(data_files)

Compute a hash of all data files in the dataset

Source code in hdxms_datasets/models.py

def hash_files(data_files: Iterable[Path]) -> str:
    """Compute a hash of all data files in the dataset"""
    hash_obj = hashlib.sha256()
    files = sorted(data_files, key=lambda p: p.as_posix())  # Sort to ensure consistent order
    for f in files:
        if f.suffix in TEXT_FILE_FORMATS:
            content = f.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
            hash_obj.update(content.encode("utf-8"))
        else:
            hash_obj.update(f.read_bytes())

    return hash_obj.hexdigest()