_somascan_IO

SomaScan-specific import and cleanup helpers for working with .adat files and related observation metadata.

This module provides:

  • read_adat_2_AnnData

  • soma_fill_sampletype_obs_values

  • soma_make_adata_index_unique_by_merge

  • make_df_obs_adataX_soma

These functions are parser- and dataset-specific. Unlike the _tools module docs, this page is based on the current code rather than dedicated regression tests in tests/.

read_adat_2_AnnData

read_adat_2_AnnData(...) parses a SomaLogic .adat file into an AnnData object.

Full signature

def read_adat_2_AnnData(path_or_buf: Union[str, TextIO]) -> AnnData:

import adata_science_tools as adtl

adata = adtl.read_adat_2_AnnData("input/example.adat")

Accepted inputs

  • a filesystem path as str

  • an already-open text buffer

Returned structure

The parser constructs:

  • adata.X from the RFU matrix

  • adata.obs from row metadata

  • adata.var from column metadata

  • adata.uns from header metadata

Important behavior:

  • all values in adata.uns are coerced to strings before return;

  • this is done to avoid issues when writing the object back to .h5ad.

Naming caveat

The function does not automatically set adata.obs_names and adata.var_names to SomaScan identifiers such as SampleId or SeqId.

The example comments in the source show the intended next steps:

  • choose identifier columns,

  • assign them to obs_names and var_names,

  • make them unique if necessary.

soma_fill_sampletype_obs_values

soma_fill_sampletype_obs_values(...) copies values from one donor obs column into one or more target obs columns for specific sample types.

Full signature

def soma_fill_sampletype_obs_values(
    adata: AnnData,
    donor_obs_column: str = 'SampleType',
    donor_obs_col_values_to_paste: list[str] | None = None,
    obs_columns_toFix: list[str] | None = None,
    make_copy: bool = False
):

adata = adtl.soma_fill_sampletype_obs_values(
    adata,
    donor_obs_column="SampleType",
    donor_obs_col_values_to_paste=["QC", "Buffer", "Calibrator"],
    obs_columns_toFix=["AliquotingNotes", "AssayNotes", "TimePoint"],
    make_copy=True,
)

Default behavior

  • donor_obs_column defaults to SampleType

  • donor_obs_col_values_to_paste defaults to ["QC", "Buffer", "Calibrator"]

  • make_copy=False modifies the original AnnData

Important behavior

  • if make_copy=True, the function returns a modified copy;

  • if the donor column is missing, it raises KeyError;

  • if no target columns are provided, it prints a note and returns without changes;

  • if requested target columns are missing from adata.obs, it filters them down and prints a note;

  • if no rows match the donor values, it prints a note and returns without changes;

  • matched donor values are broadcast across all requested target columns.

The function uses print(...) for its status notes rather than structured logging.

soma_make_adata_index_unique_by_merge

soma_make_adata_index_unique_by_merge(...) makes adata.obs_names more unique by appending another obs column value to selected rows.

Full signature

def soma_make_adata_index_unique_by_merge(
    adata: AnnData,
    donor_obs_column: str = 'Barcode2d',
    mask: pd.Series | None = None,
    duplicates_index_only: bool = True,
    ensure_global_unique: bool = False,
    make_copy: bool = False,
) -> AnnData:

adata = adtl.soma_make_adata_index_unique_by_merge(
    adata,
    donor_obs_column="Barcode2d",
    duplicates_index_only=True,
    ensure_global_unique=True,
    make_copy=True,
)

How it works

  • start from the current obs_names

  • pick rows using mask, or all rows if mask is None

  • optionally restrict to duplicate index values when duplicates_index_only=True

  • replace each selected name with <old_name>_<donor_value>

  • optionally call obs_names_make_unique() when ensure_global_unique=True

Important behavior

  • duplicates_index_only=True is the default, so the helper only rewrites duplicated names unless you disable that behavior;

  • make_copy=False modifies the original object in place;

  • mask is intersected with the duplicate-name mask when duplicates_index_only=True.

make_df_obs_adataX_soma

make_df_obs_adataX_soma(...) is a SomaScan-specific variant of the generic DataFrame helper from _IO.md.

Full signature

def make_df_obs_adataX_soma(adata,layer=None,index=None,varcolumns=None,include_obs=True):

df = adtl.make_df_obs_adataX_soma(
    adata,
    layer=None,
    include_obs=True,
)

It supports:

  • choosing adata.X or a named layer,

  • using adata.obs_names or an obs column as the row index,

  • selecting one or more adata.var columns as feature labels,

  • concatenating adata.obs in front of the expression matrix.

Differences from make_df_obs_adataX

  • no use_raw option

  • no sparse-to-dense guard before building the DataFrame

  • otherwise similar varcolumns handling, including MultiIndex output when multiple var columns are supplied

Practical guidance

  • Use read_adat_2_AnnData(...) as the initial import step for .adat files.

  • Set and clean obs_names and var_names explicitly after import.

  • Use soma_fill_sampletype_obs_values(...) to patch metadata columns for special sample types such as QC or buffer rows.

  • Use soma_make_adata_index_unique_by_merge(...) when imported sample identifiers are duplicated.

  • Prefer the generic helper in _IO.md unless you specifically need the SomaScan-flavored DataFrame export path.

Current caveats

This module has no direct regression tests in tests/, so the page documents current code behavior and known practical caveats:

  • read_adat_2_AnnData(...) depends on the external somadata package;

  • read_adat_2_AnnData(...) leaves naming decisions to the caller after import;

  • make_df_obs_adataX_soma(...) does not perform the sparse-to-dense conversion guard used in the generic _IO helper.