RNApysoforms.process_ensembl_gtf

RNApysoforms.process_ensembl_gtf(gtf_df: DataFrame) → DataFrame[source]

Processes an already-loaded GTF DataFrame to extract and format genomic features.

This function takes a Polars DataFrame containing GTF data and processes it by: - Filtering for ‘exon’ and ‘CDS’ feature types - Extracting key attributes (gene_id, gene_name, transcript_id, etc.) from the attributes column - Filling missing gene_name and transcript_name with gene_id and transcript_id - Validating that required attributes are present (consistent with 2024 ENSEMBL GTF format) - Casting exon_number to Int64

This function is useful when you have already loaded your GTF data into a Polars DataFrame and want to process it without reading from a file. If you need to read from a file, use read_ensembl_gtf() instead.

Expected DataFrame Format: The input DataFrame should have the following columns (standard GTF format):

seqnames (chromosome or sequence name)

source (annotation source)

type (feature type, e.g., ‘exon’, ‘CDS’)

start (start position of the feature)

end (end position of the feature)

score (score value, often ‘.’)

strand (strand information, ‘+’ or ‘-‘)

phase (reading frame phase)

attributes (semicolon-separated key-value pairs)

Required Attributes in the attributes column: The function expects ENSEMBL-formatted attributes with the following keys:

gene_id (required)

transcript_id (required)

gene_name (optional, will be filled with gene_id if missing)

transcript_name (optional, will be filled with transcript_id if missing)

transcript_biotype (required)

exon_number (optional for exon/CDS features)

Parameters:: gtf_df (pl.DataFrame) – A Polars DataFrame containing GTF data in standard format with the expected columns.
Returns:: A processed Polars DataFrame containing extracted gene and transcript features. The DataFrame includes the following columns: - gene_id: Identifier for the gene. - gene_name: Name of the gene. If missing, filled with gene_id. - transcript_id: Identifier for the transcript. - transcript_name: Name of the transcript. If missing, filled with transcript_id. - transcript_biotype: Biotype classification of the transcript. - seqnames: Chromosome or sequence name. - strand: Strand information (‘+’ or ‘-‘). - type: Feature type (‘exon’ or ‘CDS’). - start: Start position of the feature. - end: End position of the feature. - exon_number: Exon number within the transcript, cast to Int64.
Return type:: pl.DataFrame
Raises:: ValueError – If the GTF DataFrame is not consistent with the 2024 ENSEMBL GTF format (missing required attributes).

Examples

Process an already-loaded GTF DataFrame:

>>> import polars as pl
>>> from RNApysoforms import process_ensembl_gtf
>>>
>>> # Assume gtf_df is already loaded with standard GTF columns
>>> # gtf_df = pl.read_csv("file.gtf", separator="  ", has_header=False, ...)
>>>
>>> processed_df = process_ensembl_gtf(gtf_df)
>>> print(processed_df.head())

Notes

The function filters out feature types other than ‘exon’ and ‘CDS’.
Regular expressions are used to extract specific attributes from the ‘attributes’ column.
Missing gene_name and transcript_name values are filled with gene_id and transcript_id, respectively.
The ‘exon_number’ field is cast to Int64, handling possible nulls without strict type enforcement.
If required attributes (gene_id, transcript_id, transcript_biotype) are missing, a ValueError is raised.