Skip to content

deCODE Aptamer Metadata

gentropy.datasource.decode.aptamer_metadata.AptamerMetadata dataclass

Bases: Dataset

Mapping from SomaScan aptamer identifiers to protein target metadata.

Each row describes a single SomaScan aptamer and its one or more protein targets. Multi-target aptamers (i.e. those measuring a protein complex) are flagged with isProteinComplex = True and their targetMetadata array will contain more than one element.

The dataset is created from the aptamer study table supplied by deCODE and is used in deCODEStudyIndex.from_manifest to join aptamer-level annotations onto the per-study manifest.

Source code in src/gentropy/datasource/decode/aptamer_metadata.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class AptamerMetadata(Dataset):
    """Mapping from SomaScan aptamer identifiers to protein target metadata.

    Each row describes a single SomaScan aptamer and its one or more protein targets.
    Multi-target aptamers (i.e. those measuring a protein complex) are flagged with
    ``isProteinComplex = True`` and their ``targetMetadata`` array will contain more
    than one element.

    The dataset is created from the aptamer study table supplied by deCODE and is used
    in `deCODEStudyIndex.from_manifest`
    to join aptamer-level annotations onto the per-study manifest.
    """

    @classmethod
    def get_schema(cls) -> t.StructType:
        """Return the enforced Spark schema for `AptamerMetadata`.

        Returns:
            t.StructType: Expected schema containing ``aptamerId``, ``targetName``,
                ``targetFullName``, ``isProteinComplex``, and ``targetMetadata``.
        """
        return t.StructType(
            [
                t.StructField("aptamerId", t.StringType(), nullable=False),
                t.StructField("targetName", t.StringType(), nullable=False),
                t.StructField("targetFullName", t.StringType(), nullable=True),
                t.StructField("isProteinComplex", t.BooleanType(), nullable=False),
                t.StructField(
                    "targetMetadata",
                    t.ArrayType(
                        t.StructType(
                            [
                                t.StructField(
                                    "geneSymbol", t.StringType(), nullable=True
                                ),
                                t.StructField(
                                    "proteinId", t.StringType(), nullable=True
                                ),
                            ]
                        )
                    ),
                ),
            ]
        )

    @classmethod
    def from_source(cls, session: Session, path: str) -> AptamerMetadata:
        """Load and parse the deCODE aptamer metadata file.

        The file at ``path`` is expected to be a TSV with the SomaScan study table
        layout (columns: ``seqid``, ``target_name``, ``target_full_name``, ``gene_name``,
        ``uniprot``). Each ``seqid`` value is normalised by stripping the ``SeqId.`` prefix
        and converting the underscore-separated aptamer identifier to a hyphen-separated one.

        Args:
            session (Session): Gentropy session object used to load the source data.
            path (str): Path (local or remote) to the aptamer metadata TSV file.

        Returns:
            AptamerMetadata: Validated `AptamerMetadata` dataset.
        """
        data = session.load_data(path, fmt="tsv")
        return cls._transform_source(data)

    @classmethod
    def _transform_source(cls, df: DataFrame) -> AptamerMetadata:
        """Transform a raw aptamer study table into a validated `AptamerMetadata` dataset.

        The input DataFrame is expected to contain at minimum the columns
        ``seqid``, ``target_name``, ``target_full_name``, ``gene_name``, and ``uniprot``.
        Multi-valued ``gene_name`` and ``uniprot`` fields (comma-separated) are split
        into arrays and zipped to form the ``targetMetadata`` struct array.

        Args:
            df (DataFrame): Raw study table as loaded from the aptamer metadata file.

        Returns:
            AptamerMetadata: Validated deCODE aptamer metadata dataset.
        """
        return cls(
            _df=df.select(
                "seqid",
                "target_name",
                "target_full_name",
                "gene_name",
                "uniprot",
            )
            .select(
                f.regexp_replace(f.trim("seqid"), "SeqId.", "").alias("aptamerId"),
                f.trim("target_name").alias("targetName"),
                f.trim("target_full_name").alias("targetFullName"),
                safe_split(f.trim("gene_name"), ",").alias("geneSymbol"),
                safe_split(f.trim("uniprot"), ",").alias("proteinId"),
            )
            .withColumn(
                "targetMetadata",
                f.arrays_zip("geneSymbol", "proteinId").alias("targetMetadata"),
            )
            .withColumn("isProteinComplex", f.size(f.col("targetMetadata")) > 1)
            .select(
                "aptamerId",
                "targetName",
                "targetFullName",
                "isProteinComplex",
                "targetMetadata",
            )
            .distinct()
        )

from_source(session: Session, path: str) -> AptamerMetadata classmethod

Load and parse the deCODE aptamer metadata file.

The file at path is expected to be a TSV with the SomaScan study table layout (columns: seqid, target_name, target_full_name, gene_name, uniprot). Each seqid value is normalised by stripping the SeqId. prefix and converting the underscore-separated aptamer identifier to a hyphen-separated one.

Parameters:

Name Type Description Default
session Session

Gentropy session object used to load the source data.

 required
path str

Path (local or remote) to the aptamer metadata TSV file.

 required

Returns:

Name Type Description
AptamerMetadata AptamerMetadata

Validated AptamerMetadata dataset.
Source code in src/gentropy/datasource/decode/aptamer_metadata.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
@classmethod
def from_source(cls, session: Session, path: str) -> AptamerMetadata:
    """Load and parse the deCODE aptamer metadata file.

    The file at ``path`` is expected to be a TSV with the SomaScan study table
    layout (columns: ``seqid``, ``target_name``, ``target_full_name``, ``gene_name``,
    ``uniprot``). Each ``seqid`` value is normalised by stripping the ``SeqId.`` prefix
    and converting the underscore-separated aptamer identifier to a hyphen-separated one.

    Args:
        session (Session): Gentropy session object used to load the source data.
        path (str): Path (local or remote) to the aptamer metadata TSV file.

    Returns:
        AptamerMetadata: Validated `AptamerMetadata` dataset.
    """
    data = session.load_data(path, fmt="tsv")
    return cls._transform_source(data)

get_schema() -> t.StructType classmethod

Return the enforced Spark schema for AptamerMetadata.

Returns:

Type Description
StructType

t.StructType: Expected schema containing aptamerId, targetName, targetFullName, isProteinComplex, and targetMetadata.
Source code in src/gentropy/datasource/decode/aptamer_metadata.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@classmethod
def get_schema(cls) -> t.StructType:
    """Return the enforced Spark schema for `AptamerMetadata`.

    Returns:
        t.StructType: Expected schema containing ``aptamerId``, ``targetName``,
            ``targetFullName``, ``isProteinComplex``, and ``targetMetadata``.
    """
    return t.StructType(
        [
            t.StructField("aptamerId", t.StringType(), nullable=False),
            t.StructField("targetName", t.StringType(), nullable=False),
            t.StructField("targetFullName", t.StringType(), nullable=True),
            t.StructField("isProteinComplex", t.BooleanType(), nullable=False),
            t.StructField(
                "targetMetadata",
                t.ArrayType(
                    t.StructType(
                        [
                            t.StructField(
                                "geneSymbol", t.StringType(), nullable=True
                            ),
                            t.StructField(
                                "proteinId", t.StringType(), nullable=True
                            ),
                        ]
                    )
                ),
            ),
        ]
    )
  • 2026-02-10
  • 2026-02-10
  • Contributors
    • project-defiant