Models

Data models extending sssom-schema for secondary-to-primary mappings.

Mapping Sets

class BaseMappingSet(*args, _if_missing: Callable[[JsonObj, str], Tuple[bool, Any]] = None, **kwargs)

Bases: MappingSet

A MappingSet with helpers for cardinality computation and export.

_primary_ids

Private store for the full primary ID set.

Type:

set[str]

_primary_labels

Private store for the full primary label set.

Type:

dict[str, set[str]]

_ambiguity_mode

Which field pair _find_ambiguous() checks for conflicts: "id" (subject_id/object_id) or "label" (subject_label/object_label). Label-based subclasses override this to "label".

Type:

ClassVar[str]

Initialise the mapping set and the private primary-IDs store.

to_sssom(output_path: Path | str | None = None) → sssom_document.MappingSetDocument

Return an SSSOM MappingSetDocument, optionally writing to TSV.

Parameters:

output_path – If given, the document is also serialised to an SSSOM TSV file at this path

Returns:

sssom.sssom_document.MappingSetDocument for the mapping set.

to_rdf(output_path: Path | str | None = None, serialisation: str = 'turtle') → rdflib.Graph

Return an RDFLib graph, optionally writing it to a file.

When output_path is given (or auto-generated via the save dispatcher), the graph is also serialised to disk. Either way the rdflib.Graph is returned so callers can query or manipulate it directly.

Parameters:

• output_path – Destination path. Pass a path (or None to auto-generate one) to persist the graph. If you only want the in-memory graph without touching the file-system, call to_rdf() with no arguments and ignore the path attribute.

• serialisation – RDFLib serialisation format (default: "turtle").

Returns:

rdflib.Graph containing all mappings as RDF triples.

to_json(output_path: Path | str | None = None) → dict[str, Any]

Return the mapping set as a JSON-compatible dict, optionally writing to file.

Parameters:

output_path – If given, the JSON is also written to this path.

Returns:

dict representation of the mapping set in SSSOM JSON format.

to_owl(output_path: Path | str | None = None, serialisation: str = 'turtle') → rdflib.Graph

Return an OWL rdflib.Graph, optionally writing to file.

Parameters:

• output_path – If given, the graph is also serialised to this path.

• serialisation – RDFLib serialisation format (default: "turtle").

Returns:

rdflib.Graph containing OWL axioms for the mapping set.

save(fmt: str, output_path: Path | str | None = None, **kwargs: object) → Path

Write to any supported format by name.

Shared formats: "sssom", "rdf", "json", "owl". Subclasses override this to add type-specific formats.

Parameters:

• fmt – Format key (see above).

• output_path – Destination path. Auto-generated if None.

• **kwargs – Forwarded to the format-specific writer.

Returns:

Path to the written file.

Raises:

ValueError – For unknown format keys.

find_ambiguous() → AmbiguousMappingSet

Find mappings whose subject is also a current primary entry.

Delegates to _find_ambiguous(). See that function for full semantics.

Returns:

AmbiguousMappingSet with all conflicting mappings annotated. Empty when no ambiguities are detected.

class IdMappingSet(*args, _if_missing: Callable[[JsonObj, str], Tuple[bool, Any]] = None, **kwargs)

Bases: BaseMappingSet

Mapping set for ID-based (secondary to primary identifier) mappings.

Initialise the mapping set and the private primary-IDs store.

compute_cardinalities() → None

Compute cardinalities using subject_id and object_id fields.

to_pri_ids(output_path: Path | str | None = None) → list[str]

Return a sorted list of unique primary IDs, optionally writing to TXT.

When _primary_ids is populated (e.g. from the HGNC complete set) that set is used. Otherwise primary IDs are derived from the unique object_id values in the mappings.

Parameters:

output_path – If given, the IDs are also written one-per-line to a text file.

Returns:

Sorted list of unique primary ID strings.

save(fmt: str, output_path: Path | str | None = None, **kwargs: object) → Path

Write to any supported format by name.

Formats: "sssom", "rdf", "json", "owl", "sec2pri", "pri_ids".

Parameters:

• fmt – Format key (see above).

• output_path – Destination path. Auto-generated if None.

• **kwargs – Forwarded to the format-specific writer.

Returns:

Path to the written file.

Raises:

ValueError – For unknown format keys.

class LabelMappingSet(*args, _if_missing: Callable[[JsonObj, str], Tuple[bool, Any]] = None, **kwargs)

Bases: BaseMappingSet

Mapping set for label-based (previous/alias label to current label) mappings.

Initialise the mapping set and the private primary-IDs store.

compute_cardinalities() → None

Compute cardinalities using subject_label and object_label.

to_label_sec2pri(output_path: Path | str | None = None) → pd.DataFrame

Return a DataFrame of previous/alias label to current label mappings.

Columns: secondary_id (subject_id), secondary_label (subject_label: alias or previous label), primary_id (object_id), primary_label (object_label: current approved label), predicate_id, mapping_cardinality.

Parameters:

output_path – If given, the DataFrame is also written as a TSV file.

Returns:

pandas.DataFrame with one row per label mapping.

to_pri_labels(output_path: Path | str | None = None) → list[tuple[str, str]]

Return a sorted list of unique (primary_id, label) pairs.

When _primary_labels is populated (e.g. from the HGNC complete set) that dict is used. Otherwise pairs are derived from the unique (object_id, object_label) values in the mappings.

Parameters:

output_path – If given, the pairs are also written as a two-column TSV file (id\\tlabel).

Returns:

Sorted list of (primary_id, label) tuples.

to_name2synonym(output_path: Path | str | None = None) → pd.DataFrame

Return a name to synonym DataFrame, optionally writing to TSV.

Columns: primary_id, name (primary / canonical name), synonym (secondary / alternative name).

Only oboInOwl:hasExactSynonym rows are included. Rows with IAO:0100001 ("term replaced by") are deprecation mappings and belong in the label_sec2pri output, not here.

The direction follows the sec:pri structure, where the secondary (synonym/alternative) term is the subject and the primary (canonical) term is the object.

Parameters:

output_path – If given, the DataFrame is also written as a TSV file.

Returns:

pandas.DataFrame with synonym-only label mapping rows.

save(fmt: str, output_path: Path | str | None = None, **kwargs: object) → Path

Write to any supported format by name.

Formats: "sssom", "rdf", "json", "owl", "label_sec2pri" ("label2prev" is a deprecated alias), "pri_labels", "name2synonym".

Parameters:

• fmt – Format key (see above).

• output_path – Destination path. Auto-generated if None.

• **kwargs – Forwarded to the format-specific writer.

Returns:

Path to the written file.

Raises:

ValueError – For unknown format keys.

Configuration

class DatasourceConfig(*, name: str, prefix: str, curie_base_url: str, config_id: str = '', datasource_id: str = '', parser_class: str = '', entity_types: list[str] = <factory>, parse_options: dict[str, ~typing.Any] = <factory>, mapping_sets: dict[str, ~typing.Any] = <factory>, available_outputs: list[str] = <factory>, default_output_filename: str = '', download_urls: dict[str, ~typing.Any] = <factory>, primary_file_key: str = '', id_pattern: str = '', archive_url: str | None = '', input_file_types: list[str] = <factory>, source: str = '', homepage: str = '', data_license: str = '', sparql_endpoint: str = '', queries: dict[str, str] = <factory>, version_query: str = '', new_format_version: int | None = None, distribution_eras: list[~mapkgsutils.parsers.config.DistributionEra] = <factory>, xref_sources: list[~mapkgsutils.parsers.config.XrefSource] = <factory>, products: list[str] = <factory>, species: dict[str, ~typing.Any] = <factory>, subset: dict[str, ~typing.Any] = <factory>, mappingset: dict[str, ~typing.Any] = <factory>, mapping: dict[str, ~typing.Any] = <factory>, **extra_data: ~typing.Any)

Configuration for a biological database datasource loaded from YAML.

Required fields (name, prefix, curie_base_url) have no default; every other key is optional. Unrecognized top-level keys are tolerated (a warning is emitted by validate_config_dict()).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

version_query: str

SPARQL SELECT run against sparql_endpoint to get version

products: list[str]

Products split a release into disjoint datasets, e.g. ["species"]. Each names an attribute of the parser; their values become the product slug

species_token(taxon_id: str | int) → str

Resolve a canonical NCBI taxon ID to this datasource’s species token.

Reads the species.available block (see ensembl.yaml), which maps each supported taxon ID to the datasource-specific token used to build download paths/filters (e.g. Ensembl’s homo_sapiens).

Parameters:

taxon_id – Canonical NCBI taxon ID, e.g. 9606 or "9606".

Returns:

The datasource-specific species token.

Raises:

ValueError – If no species block is configured, or taxon_id is not one of its declared entries.

default_species() → str | int

Return the configured default species taxon ID (9606 if unset).

default_subset() → str | None

Return the configured default subset, or None if this datasource has none.

xref_source(source_id: str) → XrefSource | None

Return the configured XrefSource with id source_id, if any.

formats_for(kind: str) → Any

Return the list of supported output formats for a mapping-set kind.

Parameters:

kind – Mapping-set key, e.g. "ids" or "labels".

Returns:

List of format strings, or an empty list when the kind is absent.

era_for(version: str | None) → DistributionEra | None

Return the first configured era whose bounds contain version.

Parameters:

version – Version string to match, or None.

Returns:

The matching DistributionEra, or None if no eras are configured or none match (callers should fall back to the top-level download_urls/new_format_version behavior).

Constants

Pre-loaded datasource configurations.

Constants for supported datasources.

Datasource configs are built on access.

CONSOLIDATE_DATASOURCES: tuple[str, ...] = ('chebi', 'ensembl', 'hgnc', 'ncbi', 'uniprot', 'vgnc')

Datasource config ids that support consolidate (first-seen-date).

Base Parser

class BaseParser(version: str | None = None, show_progress: bool = True, config_name: str | None = None)

Abstract base class for all pysec2pri datasource parsers.

Initialize the parser.

Parameters:

• version – Version/release identifier for the datasource.

• show_progress – Whether to show progress bars during parsing.

• config_name – Name of config file to load (defaults to class name).

config_package: ClassVar[str] = 'pysec2pri.config'

Importable package holding this datasource family’s *.yaml config files. Set by the concrete framework subclass.

mapping_set_classes: ClassVar[dict[str, type[BaseMappingSet]]] = {'id': <class 'pysec2pri.parsers.base.IdMappingSet'>, 'label': <class 'pysec2pri.parsers.base.LabelMappingSet'>}

Which BaseMappingSet subclass create_mapping_set() instantiates for each mapping_type.