scdecon.io¶

io ¶

Input/output layer: readers and writers for scdecon data formats.

read_bulk ¶

read_bulk(path: str | Path, sep: str | None = None) -> pd.DataFrame

Load a bulk expression matrix as a genes-by-samples DataFrame.

The first column becomes the gene index; the remaining columns are samples. Gene rows are returned in exactly the order they appear in the source file: the reader never sorts, filters, or reorders them.

Supported formats (chosen from the file suffix, never sniffed from content):

.tsv -- tab-separated (separator "\t")
.csv -- comma-separated (separator ",")

Any other suffix is intentionally unsupported and raises ValueError unless an explicit sep is provided.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a bulk expression matrix (`.tsv` or `.csv`).	required
`sep`	`str \| None`	Column separator. If `None`, it is inferred from the file suffix as described above; pass a value to read a file with an unsupported suffix.	`None`

Returns:

Type	Description
`DataFrame`	Genes (index) by samples (columns), with values unchanged from disk.

Raises:

Type	Description
`FileNotFoundError`	If `path` does not point to an existing file.
`ValueError`	If the separator cannot be inferred, the table is empty, gene identifiers are duplicated, or any sample column is non-numeric.

read_h5ad ¶

read_h5ad(path: str | Path) -> anndata.AnnData

Load an annotated single-cell dataset from an .h5ad file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a `.h5ad` file written by AnnData/Scanpy.	required

Returns:

Type	Description
`AnnData`	The dataset exactly as stored, including a sparse `.X` if present.

Raises:

Type	Description
`FileNotFoundError`	If `path` does not point to an existing file.

read_metadata ¶

read_metadata(path: str | Path, index_col: int | str = 0) -> pd.DataFrame

Load a sample- or cell-annotation table.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a metadata table (`.tsv` or `.csv`).	required
`index_col`	`int \| str`	Column to use as the row index (identifiers). Defaults to the first column.	`0`

Returns:

Type	Description
`DataFrame`	The metadata table with values unchanged from disk.

Raises:

Type	Description
`FileNotFoundError`	If `path` does not point to an existing file.
`ValueError`	If the separator cannot be inferred, the table is empty, or the index contains duplicate identifiers.

write_h5ad ¶

write_h5ad(adata: AnnData, path: str | Path) -> Path

Write an AnnData object to an .h5ad file.

The object is written exactly as given, including a sparse .X if present.

Parameters:

Name	Type	Description	Default
`adata`	`AnnData`	The AnnData object to persist.	required
`path`	`str \| Path`	Destination path. Missing parent directories are created.	required

Returns:

Type	Description
`Path`	The path that was written.

write_table ¶

write_table(frame: DataFrame, path: str | Path, sep: str | None = None) -> Path

Write a DataFrame to a delimited text file, preserving row order.

Supported formats mirror :func:scdecon.io.read_bulk:

.tsv -- tab-separated (separator "\t")
.csv -- comma-separated (separator ",")

The index is written as the first column so the file round-trips through the matching reader. Rows and columns are written in their current order; the writer never sorts or reorders them.

Parameters:

Name	Type	Description	Default
`frame`	`DataFrame`	The table to write. Its index becomes the first column on disk.	required
`path`	`str \| Path`	Destination path. Missing parent directories are created.	required
`sep`	`str \| None`	Column separator. If `None`, it is inferred from the file suffix; pass a value to write a file with an unsupported suffix.	`None`

Returns:

Type	Description
`Path`	The path that was written.

Raises:

Type	Description
`ValueError`	If the separator cannot be inferred from the suffix and `sep` is not given.