snapatac2.ex.export_fragments#

snapatac2.ex.export_fragments(adata, groupby, selections=None, ids=None, min_frag_length=None, max_frag_length=None, out_dir='./', prefix='', suffix='.bed.zst', compression=None, compression_level=None)[source]#

Export grouped fragments to BED-like files.

Use this function after importing fragments to write one fragment file per cell group. Provide group labels directly or pass the name of an .obs column. The output filenames are constructed as {prefix}{group_name}{suffix} inside out_dir.

Anti-Patterns#

  • Do NOT pass an AnnData object without fragment metadata created by import_fragments.

  • Do NOT pass groupby or ids lists with lengths different from adata.n_obs.

param adata:

Annotated data object with n_obs cells and fragment metadata.

type adata:

AnnData | AnnDataSet

param groupby:

Group assignment for each cell. If a string, values are read from adata.obs[groupby]. If a list, it must contain one group label per cell in observation order.

type groupby:

str | list[str]

param selections:

Group names to export. If None, export every group found in groupby.

type selections:

list[str] | None

param ids:

Cell IDs to write into BED records. If a string, values are read from adata.obs[ids]. If a list, it must contain one ID per cell. If None, adata.obs_names are used.

type ids:

str | list[str] | None

param min_frag_length:

Minimum fragment length to export. If None, do not apply a minimum.

type min_frag_length:

int | None

param max_frag_length:

Maximum fragment length to export. If None, do not apply a maximum.

type max_frag_length:

int | None

param out_dir:

Directory where output files are written.

type out_dir:

Path

param prefix:

Text prepended to each output filename.

type prefix:

str

param suffix:

Text appended to each output filename. Used to infer compression when compression=None.

type suffix:

str

param compression:

Compression codec. If None, infer it from suffix.

type compression:

Optional[Literal['gzip', 'zstandard']]

param compression_level:

Compression level. Use 1-9 for gzip or 1-22 for zstandard. If None, use the backend default: 6 for gzip or 3 for zstandard.

type compression_level:

int | None

returns:

Mapping from group name to output filename.

rtype:

dict[str, str]

See also

export_coverage

Examples

>>> import snapatac2 as snap
>>> data = snap.pp.import_fragments(
...     snap.datasets.pbmc500(downsample=True),
...     chrom_sizes=snap.genome.hg38,
...     sorted_by_barcode=False,
... )
>>> snap.ex.export_fragments(
...     data,
...     groupby=["pbmc500"] * data.n_obs,
...     out_dir="fragments_by_group",
... )
{'pbmc500': 'fragments_by_group/pbmc500.bed.zst'}
On this page