Skip to content

Add fasta support#7851

Open
georgia-hf wants to merge 9 commits into
huggingface:mainfrom
georgia-hf:add-fasta-support
Open

Add fasta support#7851
georgia-hf wants to merge 9 commits into
huggingface:mainfrom
georgia-hf:add-fasta-support

Conversation

@georgia-hf
Copy link
Copy Markdown

This PR adds support for FASTA files conversion to Parquet.

@HuggingFaceDocBuilderDev
Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

Copy link
Copy Markdown
Member

@lhoestq lhoestq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks all good ! I just left minor comments

".ffn": ("fasta", {}),
".frn": ("fasta", {}),
}
_EXTENSION_TO_MODULE.update({ext: ("imagefolder", {}) for ext in imagefolder.ImageFolder.EXTENSIONS})
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can also add the upper versions of the extensions here

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Huh, but why do none of the other extensions have uppers?

import datasets
from datasets.features import Value
from datasets.table import table_cast
from datasets.utils.file_utils import xopen
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need for xopen, you can use regular open (it's replaced by xopen anyway when needed due to an old logic)

@apcamargo
Copy link
Copy Markdown

A few comments:

  • Have you tried using this with longer sequences? @UriNeri developed something similar internally and used it with viral genomes. He got some Parquet errors due to genomes not fitting in a utf8 column. This was fixed by using large_utf8.
  • If you're only using it to read FASTA files, I think that having BioPython as a dependency is overkill. The library is very large and the FASTA parser isn't particularly fast. I have an example of a fast parser with no external references here (this is actually based on readfq.py, with a couple of extra functions that might not be useful in the context of this PR)

@UriNeri
Copy link
Copy Markdown

UriNeri commented Nov 15, 2025

  • If you're only using it to read FASTA files, I think that having BioPython as a dependency is overkill. The library is very large and the FASTA parser isn't particularly fast. I have an example of a fast parser with no external references here (this is actually based on readfq.py, with a couple of extra functions that might not be useful in the context of this PR)

What @apcamargo said, plus FWIW in our approach (so might not be relevant here) we use polars (with custom fasta io parser) or polars-bio (that has a scan_fasta function) and we foudn out that the page size sometimes need to be adjusted:

envs/default/lib/python3.9/site-packages/polars/lazyframe/frame.py:2422, in LazyFrame.collect(self, type_coercion, predicate_pushdown, projection_pushdown, simplify_expression, slice_pushdown, comm_subplan_elim, comm_subexpr_elim, cluster_with_columns, collapse_joins, no_optimization, engine, background, optimizations, **_kwargs)
   2420 # Only for testing purposes
   2421 callback = _kwargs.get("post_opt_callback", callback)
-> 2422 return wrap_df(ldf.collect(engine, callback))
ComputeError: parquet: File out of specification: A page can only contain i32::MAX uncompressed bytes. This one contains 4544943557

Which in polars can be solved with:

df.write_parquet(
    "test1.patquet",
   compression="zstd",
    row_group_size=10_000,  #  smaller row groups
     data_page_size=1024*1024  # 1MB page size
)

behroozazarkhalili added a commit to behroozazarkhalili/datasets that referenced this pull request Dec 31, 2025
Add native support for loading FASTA biological sequence files with zero
external dependencies. This addresses feedback from PR huggingface#7851.

Key features:
- Pure Python parser based on Heng Li's readfq.py (no BioPython dependency)
- Uses pa.large_string() for sequences to handle UTF-8 overflow with long genomes
- Adaptive byte-based batching (max_batch_bytes=256MB) prevents Parquet page
  size errors with very large sequences like complete viral genomes
- Supports gzip, bzip2, and xz compression via magic byte detection
- Column filtering: select subset of [id, description, sequence]

Supported extensions: .fa, .fasta, .fna, .ffn, .faa, .frn
Copy link
Copy Markdown
Member

@lhoestq lhoestq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

coming back to scientific formats datasets :)

just a little comment before and checking the CI is green before we merge

from typing import List as ListT

import pyarrow as pa
from Bio import SeqIO
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you move this import in _iter_fasta_records ? since it's an optional dependency

Comment thread docs/source/loading.mdx

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("fasta", data_files="data.fasta")
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are there fasta datasets on the Hub that would be cool

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants