prepare_data(attr_to_split=..., attr_to_balance=...) requires the cell_state_dict state_key to be present in attr_to_balance, and appears to require it to be patient-level

#596
by Mashuaiii - opened

Hi Geneformer team,

I ran into two related behaviors when using Classifier.prepare_data() with attr_to_split and attr_to_balance, and I’d like to confirm whether they are intended or whether I’m misusing the API.

Setup

My tokenized dataset has:

patient_ID: patient-level identifier (one value per patient)

cell_state: cell-level label (one patient can have multiple cells with different cell_state values)

I want to split the dataset by patient(attr_to_split="patient_ID") while balancing Gender (attr_to_balance=["Gender"]).

Observation 1: attr_to_balance must include the cell_state_dict state_key

If I initialize the classifier with:

python
cell_state_dict={"state_key": "cell_state", "states": "all"}

and call:

python
cc.prepare_data(
    input_data_file="...",
    output_directory=...,
    output_prefix=...,
    attr_to_split="patient_ID",
    attr_to_balance=["Gender"],
)

it raises an error saying cell_state cannot be found, even though cell_state does exist in the dataset. If I instead add cell_state to attr_to_balance:

python
attr_to_balance=["Gender", "cell_state"]
the error changes, but it still does not work correctly when cell_state is cell-level (see Observation 2).

Observation 2: cell_state_dict seems to require a patient-level state_key

When I create a patient-level state column, e.g. patient_state (one value per patient, such as disease or healthy), and set:

python
cell_state_dict={"state_key": "patient_state", "states": "all"}

then:

python
attr_to_split="patient_ID",
attr_to_balance=["Gender"],

also raises the “cannot find patient_state” error. But adding patient_state to attr_to_balance:

python
attr_to_balance=["Gender", "patient_state"]

makes it work without error.

So it appears that:

  1. attr_to_balance must explicitly include the state_key from cell_state_dict, otherwise balance_attr_splits cannot populate that column.

  2. cell_state_dict seems to only work smoothly when state_key is a patient-level column. When state_key is a cell-level label (a patient can have multiple states), the balancing logic cannot aggregate it per patient, and the call fails.

My questions

  1. Is it intended that attr_to_balance must explicitly include the cell_state_dict state_key? If so, could this be documented in prepare_data or the tutorial? The current error message (“cannot find cell_state”) is misleading, because the column does exist.

  2. Is cell_state_dict expected to work with a cell-level state_key when attr_to_split is patient-level? Conceptually, the classifier is distinguishing cell-level states, so a cell-level state_key seems natural. But the balancing logic appears to require a patient-level value per patient. Is there a recommended way to split by patient while using a cell-level state_key?

  3. If a cell-level state_key cannot be used with attr_to_split + attr_to_balance, is the intended workflow to fall back to split_sizes (cell-level random split), or to use split_id_dict with explicit patient IDs? I currently use:

python
cc = Classifier(
    classifier="cell",
    cell_state_dict={"state_key": "cell_state", "states": "all"},
    filter_data={},
    training_args=training_args,
    max_ncells=None,
    freeze_layers=2,
    num_crossval_splits=1,
    forward_batch_size=20,
    nproc=8,
    model_version="V2",
    split_sizes={"train": 0.7, "valid": 0.15, "test": 0.15},
)

which avoids the balancing logic entirely, but it splits by cell rather than by patient, so the same patient’s cells can appear in both train and test. Is there a recommended patient-level alternative when state_key is cell-level?

Thanks for your help — I’d be happy to provide the full traceback or a minimal reproducible example if that would help.

Sign up or log in to comment