Skip to content

Target Index

gentropy.dataset.target_index.TargetIndex dataclass

Bases: Dataset

Target index dataset.

Gene-based annotation.

Source code in src/gentropy/dataset/target_index.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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@dataclass
class TargetIndex(Dataset):
    """Target index dataset.

    Gene-based annotation.
    """

    @classmethod
    def get_schema(cls: type[TargetIndex]) -> StructType:
        """Provides the schema for the TargetIndex dataset.

        Returns:
            StructType: Schema for the TargetIndex dataset
        """
        return parse_spark_schema("target_index.json")

    def filter_by_biotypes(self: TargetIndex, biotypes: list[str]) -> TargetIndex:
        """Filter by approved biotypes.

        Args:
            biotypes (list[str]): List of Ensembl biotypes to keep.

        Returns:
            TargetIndex: Target index dataset filtered by biotypes.
        """
        self.df = self._df.filter(f.col("biotype").isin(biotypes))
        return self

    def locations_lut(self: TargetIndex) -> DataFrame:
        """Gene location information.

        Returns:
            DataFrame: Gene LUT including genomic location information.
        """
        return self.df.select(
            f.col("id").alias("geneId"),
            f.col("genomicLocation.chromosome").alias("chromosome"),
            f.col("genomicLocation.start").alias("start"),
            f.col("genomicLocation.end").alias("end"),
            f.col("genomicLocation.strand").alias("strand"),
            "tss",
        )

    def symbols_lut(self: TargetIndex) -> DataFrame:
        """Gene symbol lookup table.

        Pre-processess gene/target dataset to create lookup table of gene symbols, including
        obsoleted gene symbols.

        Returns:
            DataFrame: Gene LUT for symbol mapping containing `geneId` and `geneSymbol` columns.
        """
        return self.df.select(
            f.explode(
                f.array_union(f.array("approvedSymbol"), f.col("obsoleteSymbols.label"))
            ).alias("geneSymbol"),
            f.col("id").alias("geneId"),
            f.col("genomicLocation.chromosome").alias("chromosome"),
            "tss",
        )

    def protein_id_lut(
        self: TargetIndex,
        include_par_chr: str = "X",
    ) -> DataFrame:
        """Mapping between gene id and protein id.

        Args:
            include_par_chr (str): Chromosome to include PAR (pseudo-autosomal region)
                genes from. Must be ``"X"`` or ``"Y"``. Defaults to ``"X"``.

        Returns:
            DataFrame: Gene LUT for UniProt mapping containing `geneId`, `proteinId` columns.

        Raises:
            ValueError: If ``include_par_chr`` is not ``"X"`` or ``"Y"``.

        !!! note "PAR gene mapping"
            For the PAR (pseudo autosomal region) genes we want to keep only one mapping by default for chromosome X
            to avoid the confusion of having the same geneSymbol mapped to two ensembl ids.

        """
        if include_par_chr not in ("X", "Y"):
            raise ValueError("include_par_chr must be either 'X' or 'Y'")

        # Condition checks if there are multiple chromosomes for the same proteinId, example: ASMTL gene
        # [ENSG00000169093, ENSG00000292339] mapped to X and Y due to PAR region.
        is_par = f.concat_ws(
            ",",
            f.sort_array(
                f.collect_set("chromosome").over(Window.partitionBy("proteinId"))
            ),
        ) == f.lit("X,Y")

        _df = (
            self.df.select(
                f.col("id").alias("geneId"),
                f.inline("proteinIds"),
                f.col("canonicalTranscript.chromosome").alias("chromosome"),
            )
            .withColumnRenamed("id", "proteinId")
            .select(
                f.col("geneId"),
                f.col("proteinId"),
                is_par.alias("isPAR"),
                f.col("chromosome"),
            )
        )
        if include_par_chr:
            _df = _df.filter(
                ~((f.col("isPAR")) & (~f.col("chromosome").isin([include_par_chr])))
            ).drop("isPAR", "chromosome")

        return _df

    def tss_lut(self: TargetIndex) -> DataFrame:
        """Gene TSS lookup table.

        The TSS is determined using the following priority:
        1. preferred TSS from target index
        2. canonical transcript start|end based on strand
        3. genomic location start|end based on strand

        Returns:
            DataFrame: Gene LUT for TSS mapping containing `geneId` and `tss` columns.
        """
        ct_tss = f.when(
            f.col("canonicalTranscript.strand") == "+",
            f.col("canonicalTranscript.start"),
        ).when(
            f.col("canonicalTranscript.strand") == "-",
            f.col("canonicalTranscript.end"),
        )
        gl_tss = f.when(
            f.col("genomicLocation.strand") == 1, f.col("genomicLocation.start")
        ).when(f.col("genomicLocation.strand") == -1, f.col("genomicLocation.end"))

        tss = f.coalesce(f.col("tss"), ct_tss, gl_tss).cast(t.LongType()).alias("tss")
        return self.df.select(f.col("id").alias("geneId"), tss)

filter_by_biotypes(biotypes: list[str]) -> TargetIndex

Filter by approved biotypes.

Parameters:

Name Type Description Default
biotypes list[str]

List of Ensembl biotypes to keep.

 required

Returns:

Name Type Description
TargetIndex TargetIndex

Target index dataset filtered by biotypes.
Source code in src/gentropy/dataset/target_index.py 
36
37
38
39
40
41
42
43
44
45
46
def filter_by_biotypes(self: TargetIndex, biotypes: list[str]) -> TargetIndex:
    """Filter by approved biotypes.

    Args:
        biotypes (list[str]): List of Ensembl biotypes to keep.

    Returns:
        TargetIndex: Target index dataset filtered by biotypes.
    """
    self.df = self._df.filter(f.col("biotype").isin(biotypes))
    return self

get_schema() -> StructType classmethod

Provides the schema for the TargetIndex dataset.

Returns:

Name Type Description
StructType StructType

Schema for the TargetIndex dataset
Source code in src/gentropy/dataset/target_index.py 
27
28
29
30
31
32
33
34
@classmethod
def get_schema(cls: type[TargetIndex]) -> StructType:
    """Provides the schema for the TargetIndex dataset.

    Returns:
        StructType: Schema for the TargetIndex dataset
    """
    return parse_spark_schema("target_index.json")

locations_lut() -> DataFrame

Gene location information.

Returns:

Name Type Description
DataFrame DataFrame

Gene LUT including genomic location information.
Source code in src/gentropy/dataset/target_index.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def locations_lut(self: TargetIndex) -> DataFrame:
    """Gene location information.

    Returns:
        DataFrame: Gene LUT including genomic location information.
    """
    return self.df.select(
        f.col("id").alias("geneId"),
        f.col("genomicLocation.chromosome").alias("chromosome"),
        f.col("genomicLocation.start").alias("start"),
        f.col("genomicLocation.end").alias("end"),
        f.col("genomicLocation.strand").alias("strand"),
        "tss",
    )

protein_id_lut(include_par_chr: str = 'X') -> DataFrame

Mapping between gene id and protein id.

Parameters:

Name Type Description Default
include_par_chr str

Chromosome to include PAR (pseudo-autosomal region) genes from. Must be "X" or "Y". Defaults to "X".

 'X'

Returns:

Name Type Description
DataFrame DataFrame

Gene LUT for UniProt mapping containing geneId, proteinId columns.

Raises:

Type Description
ValueError

If include_par_chr is not "X" or "Y".

PAR gene mapping

For the PAR (pseudo autosomal region) genes we want to keep only one mapping by default for chromosome X to avoid the confusion of having the same geneSymbol mapped to two ensembl ids.

Source code in src/gentropy/dataset/target_index.py 
 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
128
129
130
131
132
133
def protein_id_lut(
    self: TargetIndex,
    include_par_chr: str = "X",
) -> DataFrame:
    """Mapping between gene id and protein id.

    Args:
        include_par_chr (str): Chromosome to include PAR (pseudo-autosomal region)
            genes from. Must be ``"X"`` or ``"Y"``. Defaults to ``"X"``.

    Returns:
        DataFrame: Gene LUT for UniProt mapping containing `geneId`, `proteinId` columns.

    Raises:
        ValueError: If ``include_par_chr`` is not ``"X"`` or ``"Y"``.

    !!! note "PAR gene mapping"
        For the PAR (pseudo autosomal region) genes we want to keep only one mapping by default for chromosome X
        to avoid the confusion of having the same geneSymbol mapped to two ensembl ids.

    """
    if include_par_chr not in ("X", "Y"):
        raise ValueError("include_par_chr must be either 'X' or 'Y'")

    # Condition checks if there are multiple chromosomes for the same proteinId, example: ASMTL gene
    # [ENSG00000169093, ENSG00000292339] mapped to X and Y due to PAR region.
    is_par = f.concat_ws(
        ",",
        f.sort_array(
            f.collect_set("chromosome").over(Window.partitionBy("proteinId"))
        ),
    ) == f.lit("X,Y")

    _df = (
        self.df.select(
            f.col("id").alias("geneId"),
            f.inline("proteinIds"),
            f.col("canonicalTranscript.chromosome").alias("chromosome"),
        )
        .withColumnRenamed("id", "proteinId")
        .select(
            f.col("geneId"),
            f.col("proteinId"),
            is_par.alias("isPAR"),
            f.col("chromosome"),
        )
    )
    if include_par_chr:
        _df = _df.filter(
            ~((f.col("isPAR")) & (~f.col("chromosome").isin([include_par_chr])))
        ).drop("isPAR", "chromosome")

    return _df

symbols_lut() -> DataFrame

Gene symbol lookup table.

Pre-processess gene/target dataset to create lookup table of gene symbols, including obsoleted gene symbols.

Returns:

Name Type Description
DataFrame DataFrame

Gene LUT for symbol mapping containing geneId and geneSymbol columns.
Source code in src/gentropy/dataset/target_index.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def symbols_lut(self: TargetIndex) -> DataFrame:
    """Gene symbol lookup table.

    Pre-processess gene/target dataset to create lookup table of gene symbols, including
    obsoleted gene symbols.

    Returns:
        DataFrame: Gene LUT for symbol mapping containing `geneId` and `geneSymbol` columns.
    """
    return self.df.select(
        f.explode(
            f.array_union(f.array("approvedSymbol"), f.col("obsoleteSymbols.label"))
        ).alias("geneSymbol"),
        f.col("id").alias("geneId"),
        f.col("genomicLocation.chromosome").alias("chromosome"),
        "tss",
    )

tss_lut() -> DataFrame

Gene TSS lookup table.

The TSS is determined using the following priority: 1. preferred TSS from target index 2. canonical transcript start|end based on strand 3. genomic location start|end based on strand

Returns:

Name Type Description
DataFrame DataFrame

Gene LUT for TSS mapping containing geneId and tss columns.
Source code in src/gentropy/dataset/target_index.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def tss_lut(self: TargetIndex) -> DataFrame:
    """Gene TSS lookup table.

    The TSS is determined using the following priority:
    1. preferred TSS from target index
    2. canonical transcript start|end based on strand
    3. genomic location start|end based on strand

    Returns:
        DataFrame: Gene LUT for TSS mapping containing `geneId` and `tss` columns.
    """
    ct_tss = f.when(
        f.col("canonicalTranscript.strand") == "+",
        f.col("canonicalTranscript.start"),
    ).when(
        f.col("canonicalTranscript.strand") == "-",
        f.col("canonicalTranscript.end"),
    )
    gl_tss = f.when(
        f.col("genomicLocation.strand") == 1, f.col("genomicLocation.start")
    ).when(f.col("genomicLocation.strand") == -1, f.col("genomicLocation.end"))

    tss = f.coalesce(f.col("tss"), ct_tss, gl_tss).cast(t.LongType()).alias("tss")
    return self.df.select(f.col("id").alias("geneId"), tss)

Schema

root
 |-- id: string (nullable = false)
 |-- approvedSymbol: string (nullable = true)
 |-- biotype: string (nullable = true)
 |-- transcriptIds: array (nullable = true)
 |    |-- element: string (containsNull = true)
 |-- canonicalTranscript: struct (nullable = true)
 |    |-- id: string (nullable = true)
 |    |-- chromosome: string (nullable = true)
 |    |-- start: long (nullable = true)
 |    |-- end: long (nullable = true)
 |    |-- strand: string (nullable = true)
 |-- canonicalExons: array (nullable = true)
 |    |-- element: string (containsNull = true)
 |-- genomicLocation: struct (nullable = true)
 |    |-- chromosome: string (nullable = true)
 |    |-- start: long (nullable = true)
 |    |-- end: long (nullable = true)
 |    |-- strand: integer (nullable = true)
 |-- alternativeGenes: array (nullable = true)
 |    |-- element: string (containsNull = true)
 |-- approvedName: string (nullable = true)
 |-- go: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- id: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |    |    |-- evidence: string (nullable = true)
 |    |    |-- aspect: string (nullable = true)
 |    |    |-- geneProduct: string (nullable = true)
 |    |    |-- ecoId: string (nullable = true)
 |-- hallmarks: struct (nullable = true)
 |    |-- attributes: array (nullable = true)
 |    |    |-- element: struct (containsNull = true)
 |    |    |    |-- pmid: long (nullable = true)
 |    |    |    |-- description: string (nullable = true)
 |    |    |    |-- attribute_name: string (nullable = true)
 |    |-- cancerHallmarks: array (nullable = true)
 |    |    |-- element: struct (containsNull = true)
 |    |    |    |-- pmid: long (nullable = true)
 |    |    |    |-- description: string (nullable = true)
 |    |    |    |-- impact: string (nullable = true)
 |    |    |    |-- label: string (nullable = true)
 |-- synonyms: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- label: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- symbolSynonyms: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- label: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- nameSynonyms: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- label: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- functionDescriptions: array (nullable = true)
 |    |-- element: string (containsNull = true)
 |-- subcellularLocations: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- location: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |    |    |-- termSL: string (nullable = true)
 |    |    |-- labelSL: string (nullable = true)
 |-- targetClass: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- id: long (nullable = true)
 |    |    |-- label: string (nullable = true)
 |    |    |-- level: string (nullable = true)
 |-- obsoleteSymbols: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- label: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- obsoleteNames: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- label: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- constraint: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- constraintType: string (nullable = true)
 |    |    |-- score: float (nullable = true)
 |    |    |-- exp: float (nullable = true)
 |    |    |-- obs: integer (nullable = true)
 |    |    |-- oe: float (nullable = true)
 |    |    |-- oeLower: float (nullable = true)
 |    |    |-- oeUpper: float (nullable = true)
 |    |    |-- upperRank: integer (nullable = true)
 |    |    |-- upperBin: integer (nullable = true)
 |    |    |-- upperBin6: integer (nullable = true)
 |-- tep: struct (nullable = true)
 |    |-- targetFromSourceId: string (nullable = true)
 |    |-- description: string (nullable = true)
 |    |-- therapeuticArea: string (nullable = true)
 |    |-- url: string (nullable = true)
 |-- proteinIds: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- id: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- dbXrefs: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- id: string (nullable = true)
 |    |    |-- source: string (nullable = true)
 |-- chemicalProbes: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- control: string (nullable = true)
 |    |    |-- drugId: string (nullable = true)
 |    |    |-- id: string (nullable = true)
 |    |    |-- isHighQuality: boolean (nullable = true)
 |    |    |-- mechanismOfAction: array (nullable = true)
 |    |    |    |-- element: string (containsNull = true)
 |    |    |-- origin: array (nullable = true)
 |    |    |    |-- element: string (containsNull = true)
 |    |    |-- probeMinerScore: double (nullable = true)
 |    |    |-- probesDrugsScore: double (nullable = true)
 |    |    |-- scoreInCells: double (nullable = true)
 |    |    |-- scoreInOrganisms: double (nullable = true)
 |    |    |-- targetFromSourceId: string (nullable = true)
 |    |    |-- urls: array (nullable = true)
 |    |    |    |-- element: struct (containsNull = true)
 |    |    |    |    |-- niceName: string (nullable = true)
 |    |    |    |    |-- url: string (nullable = true)
 |-- homologues: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- speciesId: string (nullable = true)
 |    |    |-- speciesName: string (nullable = true)
 |    |    |-- homologyType: string (nullable = true)
 |    |    |-- targetGeneId: string (nullable = true)
 |    |    |-- isHighConfidence: string (nullable = true)
 |    |    |-- targetGeneSymbol: string (nullable = true)
 |    |    |-- queryPercentageIdentity: double (nullable = true)
 |    |    |-- targetPercentageIdentity: double (nullable = true)
 |    |    |-- priority: integer (nullable = true)
 |-- tractability: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- modality: string (nullable = true)
 |    |    |-- id: string (nullable = true)
 |    |    |-- value: boolean (nullable = true)
 |-- safetyLiabilities: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- event: string (nullable = true)
 |    |    |-- eventId: string (nullable = true)
 |    |    |-- effects: array (nullable = true)
 |    |    |    |-- element: struct (containsNull = true)
 |    |    |    |    |-- direction: string (nullable = true)
 |    |    |    |    |-- dosing: string (nullable = true)
 |    |    |-- biosamples: array (nullable = true)
 |    |    |    |-- element: struct (containsNull = true)
 |    |    |    |    |-- cellFormat: string (nullable = true)
 |    |    |    |    |-- cellLabel: string (nullable = true)
 |    |    |    |    |-- tissueId: string (nullable = true)
 |    |    |    |    |-- tissueLabel: string (nullable = true)
 |    |    |-- datasource: string (nullable = true)
 |    |    |-- literature: string (nullable = true)
 |    |    |-- url: string (nullable = true)
 |    |    |-- studies: array (nullable = true)
 |    |    |    |-- element: struct (containsNull = true)
 |    |    |    |    |-- description: string (nullable = true)
 |    |    |    |    |-- name: string (nullable = true)
 |    |    |    |    |-- type: string (nullable = true)
 |-- pathways: array (nullable = true)
 |    |-- element: struct (containsNull = true)
 |    |    |-- pathwayId: string (nullable = true)
 |    |    |-- pathway: string (nullable = true)
 |    |    |-- topLevelTerm: string (nullable = true)
 |-- tss: long (nullable = true)
  • 2025-01-22
  • 2025-01-22
  • Contributors
    • vivienho
    • web-flow