gtfparse 2.7.2__tar.gz → 2.8.0__tar.gz

{gtfparse-2.7.2 → gtfparse-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gtfparse
-Version: 2.7.2
+Version: 2.8.0
 Summary: Parsing library for extracting data frames of genomic features from GTF files
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 Project-URL: Homepage, https://github.com/openvax/gtfparse

{gtfparse-2.7.2 → gtfparse-2.8.0}/gtfparse/__init__.py

@@ -22,8 +22,9 @@ from .read_gtf import (
     parse_gtf_pandas,
     read_gtf,
 )
+from .write_gtf import write_gtf
 
-__version__ = "2.7.2"
+__version__ = "2.8.0"
 
 __all__ = [
     "GENCODE_BIOTYPE_ALIASES",
@@ -37,4 +38,5 @@ __all__ = [
     "parse_gtf_and_expand_attributes",
     "parse_gtf_pandas",
     "read_gtf",
+    "write_gtf",
 ]

gtfparse-2.8.0/gtfparse/write_gtf.py

@@ -0,0 +1,168 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import gzip
+import logging
+from collections.abc import Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional, Union
+
+import polars
+
+if TYPE_CHECKING:
+    import pandas
+
+logger = logging.getLogger(__name__)
+
+# The eight tab-separated columns that precede the attribute field of a GTF
+# line, in the order they must be written. Any other column in a DataFrame is
+# treated as an expanded attribute (see read_gtf's expand_attribute_column).
+GTF_FIXED_COLUMNS = [
+    "seqname",
+    "source",
+    "feature",
+    "start",
+    "end",
+    "score",
+    "strand",
+    "frame",
+]
+
+# GTF uses a single dot to denote a missing value in the fixed columns.
+MISSING_VALUE = "."
+
+# Name of the raw, unexpanded attribute column produced by
+# read_gtf(expand_attribute_column=False).
+RAW_ATTRIBUTE_COLUMN = "attribute"
+
+
+def _attribute_expr(attribute_columns: list[str]) -> polars.Expr:
+    """
+    Build a polars expression that renders the GTF attribute field for each row
+    from a set of expanded attribute columns.
+
+    Each column ``key`` becomes ``key "value";`` and the per-row pairs are
+    joined with a single space, matching the format emitted by Ensembl/GENCODE
+    and parsed by read_gtf.
+
+    A pair is omitted for any row where the value is "absent". read_gtf marks an
+    absent key with null (numeric columns, e.g. the ``*_version`` fields) or the
+    empty string (string columns) and cannot distinguish absent from
+    present-but-empty, so we treat both null and "" as absent. Values that are
+    merely falsy but non-empty -- notably the string "0" -- are written and
+    survive a round trip (this is the regression that the naive ``if value:``
+    check in earlier drafts got wrong).
+    """
+    if not attribute_columns:
+        return polars.lit("")
+    pairs = []
+    for name in attribute_columns:
+        value = polars.col(name).cast(polars.String)
+        pairs.append(
+            polars.when(value.is_null() | (value == ""))
+            .then(None)
+            .otherwise(polars.format('{} "{}";', polars.lit(name), value))
+        )
+    # ignore_nulls drops absent keys; fill_null covers the all-absent row so the
+    # surrounding line expression never collapses to null.
+    return polars.concat_str(pairs, separator=" ", ignore_nulls=True).fill_null("")
+
+
+def _line_series(df: polars.DataFrame) -> polars.Series:
+    """
+    Turn a DataFrame into a Series of fully-formatted GTF lines (without
+    trailing newlines), building the whole thing with vectorized polars
+    expressions rather than per-row Python.
+    """
+    columns = df.columns
+    missing = [name for name in GTF_FIXED_COLUMNS if name not in columns]
+    if missing:
+        raise ValueError("DataFrame is missing required GTF column(s): %s" % ", ".join(missing))
+
+    # Fixed columns are always written in canonical order; nulls become '.'.
+    # Cast before fill_null so numeric columns accept the string sentinel.
+    fixed = [
+        polars.col(name).cast(polars.String).fill_null(MISSING_VALUE) for name in GTF_FIXED_COLUMNS
+    ]
+
+    if RAW_ATTRIBUTE_COLUMN in columns:
+        # Unexpanded read: the attribute column is already a formatted string.
+        attribute = polars.col(RAW_ATTRIBUTE_COLUMN).cast(polars.String).fill_null("")
+    else:
+        attribute_columns = [name for name in columns if name not in GTF_FIXED_COLUMNS]
+        attribute = _attribute_expr(attribute_columns)
+
+    # Always keep the 9th (attribute) field, even when empty, so every line has
+    # the nine tab-separated columns read_gtf expects.
+    line = polars.concat_str([*fixed, attribute], separator="\t")
+    return df.select(line.alias("_gtf_line")).get_column("_gtf_line")
+
+
+def write_gtf(
+    df: Union[polars.DataFrame, "pandas.DataFrame"],
+    path: Union[str, Path],
+    header_lines: Optional[Iterable[str]] = None,
+) -> None:
+    """
+    Write a DataFrame of genomic features back out to a GTF file.
+
+    This is the inverse of :func:`read_gtf`. A DataFrame produced by
+    ``read_gtf`` (whether the attribute column was expanded into one column per
+    key or left as a raw ``attribute`` string) can be written back out and
+    re-read to recover an equivalent DataFrame.
+
+    Parameters
+    ----------
+    df : polars.DataFrame or pandas.DataFrame
+        Feature rows to write. Must contain the fixed GTF columns
+        (seqname, source, feature, start, end, score, strand, frame).
+        Any additional column is written as an attribute, except a column
+        literally named ``attribute``, which is treated as a pre-formatted
+        attribute string and emitted verbatim.
+
+    path : str or pathlib.Path
+        Destination file path. Any existing file is overwritten. If the path
+        ends in ``.gz`` the output is gzip-compressed (mirroring read_gtf,
+        which transparently reads gzip-compressed GTFs).
+
+    header_lines : iterable of str, optional
+        Lines to write at the top of the file before any feature rows, e.g.
+        ``["##description: example", "##provider: GENCODE"]``. Each is written
+        verbatim on its own line, so include a leading ``#`` if you want it to
+        be parsed back as a comment.
+
+    Notes
+    -----
+    GTF has no escaping mechanism for the structural characters ``"`` and
+    ``;`` inside attribute values (nor for the tab and newline that delimit
+    columns and rows), and read_gtf strips quotes and splits on ``;`` when
+    parsing. Values returned by read_gtf therefore never contain those
+    characters, so any DataFrame obtained from read_gtf round-trips exactly. A
+    DataFrame built by hand whose attribute values contain ``"``, ``;``, a tab,
+    or a newline cannot be represented losslessly and will not round-trip.
+    """
+    # Accept a pandas DataFrame too, since read_gtf(result_type="pandas")
+    # returns one; convert to polars so the formatting below is uniform.
+    if not isinstance(df, polars.DataFrame):
+        df = polars.from_pandas(df)
+
+    lines = _line_series(df)
+
+    open_file = gzip.open if str(path).lower().endswith(".gz") else open
+    with open_file(path, "wt", encoding="utf-8", newline="\n") as output_file:
+        if header_lines is not None:
+            for header_line in header_lines:
+                output_file.write("%s\n" % header_line)
+        for line in lines:
+            output_file.write("%s\n" % line)
+
+    logger.info("Wrote %d GTF rows to %s", lines.len(), path)

{gtfparse-2.7.2 → gtfparse-2.8.0}/gtfparse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gtfparse
-Version: 2.7.2
+Version: 2.8.0
 Summary: Parsing library for extracting data frames of genomic features from GTF files
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 Project-URL: Homepage, https://github.com/openvax/gtfparse

{gtfparse-2.7.2 → gtfparse-2.8.0}/gtfparse.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ gtfparse/attribute_parsing.py
 gtfparse/create_missing_features.py
 gtfparse/parsing_error.py
 gtfparse/read_gtf.py
+gtfparse/write_gtf.py
 gtfparse.egg-info/PKG-INFO
 gtfparse.egg-info/SOURCES.txt
 gtfparse.egg-info/dependency_links.txt
@@ -21,4 +22,5 @@ tests/test_gencode_gtf.py
 tests/test_multiple_values_for_tag_attribute.py
 tests/test_parse_gtf_lines.py
 tests/test_read_stringtie_gtf.py
-tests/test_refseq_gtf.py
+tests/test_refseq_gtf.py
+tests/test_write_gtf.py

gtfparse-2.8.0/tests/test_write_gtf.py

@@ -0,0 +1,222 @@
+import gzip
+
+import polars
+import pytest
+from polars.testing import assert_frame_equal
+
+from gtfparse import read_gtf, write_gtf
+
+from .data import data_path
+
+# A spread of real GTF flavors: RefSeq (minimal attrs), Ensembl (many attrs +
+# null scores + *_version columns), GENCODE (mixed feature types so different
+# rows carry different attribute sets), and StringTie.
+FIXTURES = [
+    "refseq.ucsc.small.gtf",
+    "ensembl_grch37.head.gtf",
+    "gencode.head.gtf",
+    "gencode.real.head.gtf",
+    "B16.stringtie.head.gtf",
+]
+
+
+def _minimal_df(**extra_columns):
+    """Build a one-row DataFrame with the fixed GTF columns plus extras.
+
+    Each extra column is passed as a single-element list, e.g.
+    ``_minimal_df(gene_id=["G1"])``.
+    """
+    row = {
+        "seqname": ["chr1"],
+        "source": ["test"],
+        "feature": ["gene"],
+        "start": [1],
+        "end": [100],
+        "score": [None],
+        "strand": ["+"],
+        "frame": [None],
+    }
+    row.update(extra_columns)
+    return polars.DataFrame(row)
+
+
+# ---------------------------------------------------------------------------
+# write(read(...)): start from a GTF file, read it, write it back.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("fixture", FIXTURES)
+@pytest.mark.parametrize("expand", [True, False])
+def test_write_read_recovers_parsed_frame(fixture, expand, tmp_path):
+    """read -> write -> read reproduces the parsed DataFrame exactly (column
+    order included), for both expanded and unexpanded attribute modes."""
+    original = read_gtf(data_path(fixture), expand_attribute_column=expand)
+    out_path = tmp_path / "out.gtf"
+    write_gtf(original, out_path)
+    recovered = read_gtf(str(out_path), expand_attribute_column=expand)
+    assert_frame_equal(original, recovered, categorical_as_str=True)
+
+
+@pytest.mark.parametrize("fixture", FIXTURES)
+def test_written_output_is_idempotent(fixture, tmp_path):
+    """write(read(...)) is a fixed point: writing what we read, reading it, and
+    writing it again yields byte-identical output."""
+    df = read_gtf(data_path(fixture))
+    first = tmp_path / "first.gtf"
+    second = tmp_path / "second.gtf"
+    write_gtf(df, first)
+    write_gtf(read_gtf(str(first)), second)
+    assert first.read_bytes() == second.read_bytes()
+
+
+# ---------------------------------------------------------------------------
+# read(write(...)): start from an in-memory DataFrame, write it, read it back.
+# ---------------------------------------------------------------------------
+
+
+def test_read_write_recovers_dataframe(tmp_path):
+    """A DataFrame written out and read back preserves its attribute values."""
+    df = _minimal_df(gene_id=["ENSG1"], gene_name=["DDX11L1"], gene_version=["5"])
+    out_path = tmp_path / "df.gtf"
+    write_gtf(df, out_path)
+    recovered = read_gtf(str(out_path))
+    assert recovered["gene_id"].to_list() == ["ENSG1"]
+    assert recovered["gene_name"].to_list() == ["DDX11L1"]
+    # writing the recovered frame is itself a fixed point
+    again = tmp_path / "df2.gtf"
+    write_gtf(recovered, again)
+    assert_frame_equal(recovered, read_gtf(str(again)), categorical_as_str=True)
+
+
+def test_round_trip_from_pandas(tmp_path):
+    """write_gtf accepts a pandas DataFrame (read_gtf(result_type='pandas'))."""
+    polars_df = read_gtf(data_path("ensembl_grch37.head.gtf"))
+    pandas_df = read_gtf(data_path("ensembl_grch37.head.gtf"), result_type="pandas")
+    out_path = tmp_path / "from_pandas.gtf"
+    write_gtf(pandas_df, out_path)
+    assert_frame_equal(polars_df, read_gtf(str(out_path)), categorical_as_str=True)
+
+
+def test_gzip_output_round_trips(tmp_path):
+    """A '.gz' path is gzip-compressed on disk and read back transparently."""
+    df = read_gtf(data_path("ensembl_grch37.head.gtf"))
+    out_path = tmp_path / "out.gtf.gz"
+    write_gtf(df, out_path)
+    # actually gzip-compressed on disk
+    assert out_path.read_bytes()[:2] == b"\x1f\x8b"
+    with gzip.open(out_path, "rt") as handle:
+        assert "\t" in handle.readline()
+    assert_frame_equal(df, read_gtf(str(out_path)), categorical_as_str=True)
+
+
+def test_gzip_detection_is_case_insensitive(tmp_path):
+    """An uppercase '.GZ' suffix is still gzip-compressed."""
+    df = read_gtf(data_path("refseq.ucsc.small.gtf"))
+    out_path = tmp_path / "out.GZ"
+    write_gtf(df, out_path)
+    assert out_path.read_bytes()[:2] == b"\x1f\x8b"
+
+
+def test_empty_dataframe_writes_no_rows(tmp_path):
+    """A zero-row DataFrame produces a file with only its header lines."""
+    empty = read_gtf(data_path("refseq.ucsc.small.gtf")).clear()
+    out_path = tmp_path / "empty.gtf"
+    write_gtf(empty, out_path, header_lines=["##empty"])
+    assert out_path.read_text() == "##empty\n"
+
+
+def test_fixed_columns_only(tmp_path):
+    """A DataFrame with only the fixed columns writes a valid 9-field line
+    (empty attribute field) and reads back."""
+    fixed_only = polars.DataFrame(
+        {
+            "seqname": ["chr1"],
+            "source": ["test"],
+            "feature": ["gene"],
+            "start": [1],
+            "end": [100],
+            "score": [None],
+            "strand": ["+"],
+            "frame": [None],
+        }
+    )
+    out_path = tmp_path / "fixed.gtf"
+    write_gtf(fixed_only, out_path)
+    # nine tab-separated fields, the last (attribute) empty
+    assert out_path.read_text().strip("\n").split("\t") == [
+        "chr1",
+        "test",
+        "gene",
+        "1",
+        "100",
+        ".",
+        "+",
+        ".",
+        "",
+    ]
+    # read_gtf accepts it (no attribute columns to expand)
+    recovered = read_gtf(str(out_path), expand_attribute_column=False)
+    assert recovered["seqname"].to_list() == ["chr1"]
+
+
+# ---------------------------------------------------------------------------
+# Attribute / missing-value semantics.
+# ---------------------------------------------------------------------------
+
+
+def test_nonempty_value_written_empty_and_null_omitted(tmp_path):
+    """A non-empty value such as '0' is written; empty string and null are
+    treated as absent and omitted (matching read_gtf's missing-value model)."""
+    df = _minimal_df(
+        gene_id=["G1"],
+        zero_attr=["0"],
+        empty_attr=[""],
+        missing_attr=[None],
+    )
+    out_path = tmp_path / "attrs.gtf"
+    write_gtf(df, out_path)
+    line = out_path.read_text().strip()
+    assert 'gene_id "G1";' in line
+    assert 'zero_attr "0";' in line  # non-empty falsy value survives
+    assert "empty_attr" not in line  # empty string omitted as absent
+    assert "missing_attr" not in line  # null omitted as absent
+
+
+def test_missing_value_fixed_columns_use_dot(tmp_path):
+    """None in the fixed columns is serialized as '.'."""
+    df = _minimal_df(gene_id=["G1"])  # score and frame are None
+    out_path = tmp_path / "dots.gtf"
+    write_gtf(df, out_path)
+    fields = out_path.read_text().strip().split("\t")
+    assert fields[5] == "."  # score
+    assert fields[7] == "."  # frame
+
+
+def test_structural_characters_are_not_round_trippable(tmp_path):
+    """GTF has no escaping for '"' or ';'; read_gtf strips quotes and splits on
+    ';'. Pin that such values cannot round-trip so a future change is noticed."""
+    df = _minimal_df(gene_id=["A;B"], note=['say "hi"'])
+    out_path = tmp_path / "special.gtf"
+    write_gtf(df, out_path)
+    recovered = read_gtf(str(out_path))
+    # the semicolon split the value apart
+    assert recovered["gene_id"].to_list() != ["A;B"]
+    # the double quotes were stripped from the value
+    assert '"' not in recovered["note"][0]
+
+
+def test_header_lines_are_written(tmp_path):
+    df = read_gtf(data_path("refseq.ucsc.small.gtf"))
+    out_path = tmp_path / "with_header.gtf"
+    write_gtf(df, out_path, header_lines=["##description: test", "##provider: gtfparse"])
+    lines = out_path.read_text().splitlines()
+    assert lines[0] == "##description: test"
+    assert lines[1] == "##provider: gtfparse"
+    # comment lines are ignored by read_gtf, so the data still round-trips
+    assert_frame_equal(df, read_gtf(str(out_path)), categorical_as_str=True)
+
+
+def test_missing_required_column_raises(tmp_path):
+    df = polars.DataFrame({"seqname": ["chr1"], "gene_id": ["G1"]})
+    with pytest.raises(ValueError, match="missing required GTF column"):
+        write_gtf(df, tmp_path / "bad.gtf")