Qs re: simpleaf flex-quant

[HelenaLC]

More of a couple Qs than issues...

• I'm wanting to run cellbender post simpleaf, which would require an .h5(ad) (I think). I see mention of an --anndata-out flag for simpleaf quant but it appears to not exist (yet?) for simpleaf flex-quant, is that right?

• I tried both without --index (defaults) and with it (running simpleaf index with a --probe-csv from previous CellRanger runs on the same data). Both don't work (...see below...), but not sure how to get symbols going?

  • One doesn't give me gene symbols, and I end up with DEPRACATED_ENSG000... in the output.
  • Two complains with Error: When providing --index, a t2g map is also needed. Place probe_t2g.tsv in the index directory, or provide --probe-set. (there is only a t2g_3col.tsv).

Any suggestions greatly appreciated and big thanks in advance :))

Just in case, this is how I tried to run this (first ever attempt, so sorry if I'm missing the obvious...):

PRJ="path/to/project"
DIR=$PRJ/data
IDX=$DIR/af_idx
SUB=$DIR/SCGRES_102
PAT="TS_A7" # split pools?
NTH=4

# this didn't help, though this contains gene symbols...
#simpleaf index --use-piscem --output $IDX --threads 40 --probe-csv probes.csv

export ALEVIN_FRY_HOME="$DIR/af_home"
simpleaf set-paths
ulimit -n 2048

r1="$(find -L $SUB -name "${PAT}*_R1_*" -type f | sort | paste -sd, -)"
r2="$(find -L $SUB -name "${PAT}*_R2_*" -type f | sort | paste -sd, -)"

simpleaf flex-quant \
  --chemistry 10x-flexv1-gex-3p \
  --output $SUB/$PAT \
  --organism human \
  --reads1 $r1 \
  --reads2 $r2 \
  -t $NTH
  #--index $IDX

simpleaf --version
# simpleaf 0.21.1

# ...and then sth annoying like...
# (pseudo-code)

# R
se = fishpond::loadFry("af_quant")
ad = anndataR::as_AnnData(se)
ad$write_h5ad("raw.h5ad")

# shell
cellbender remove-background \
      --input raw.h5ad \
      --output fil.h5 \
      --checkpoint ckpt.tar.gz \
      --expected-cells 40000 \
      --checkpoint-mins 30
      --cpu-threads 40

[rob-p]

Hi @HelenaLC,

Thanks for testing this out and for the feedback! Some answers for your questions. But first, I just want to note that you should ideally use simpleaf 0.22, which already makes some improvements over 0.21.1 and fixes some issues with cross-sample crosstalk. Also, in 0.22.0 we renamed flex-quant to multiplex-quant since one can run more than just Flex data with the tool.

Anyway, here are some answers to your questions.

1. AnnData support: Yes, this is currently missing from the multiplex quant flow. This is on the very near term roadmap, but we just haven't done it yet. One of the big questions blocking this is, what information should the multiplex AnnData object contain? I say this because in mtx mode, the entire af_quant directory becomes the primary output object. It is many files, but contains a lot of information. However the AnnData objects are intended to be self-contained. I think we can do what we do for the standard count matrix, but we are just thinking through the scenarios here.

2. When you run with the defaults (i.e. without a pre-built index), we currently map the gene_id rather than the gene_symbol as the primary feature name. If you look at the 10x probe file, each gene_id maps to a gene_symbol where the id is the first column and the symbol the last. Ideally, I'd like for both to be available easily in the oputput, and this is something that AnnData support will make easier. For the time being, the easiest way to get the symbol in place of the ID would be simply to map from the 10x probe CSV. The quantification should be over all probes whose inclusion status is TRUE in that file.

3. The t2g file should work. Actually, the 10x file has a spliced/unspliced column label, but their output doesn't really reflect that, and probes seem all to be collapsed down to the gene level. This is actually something worth thinking about (i.e. how should USA mode be handled in probe-based assays). I'd be interested about any thoughts you have regarding this, and would also be happy to help getting a custom index working easily on your end if that's something you're interested in doing.

Best,
Rob

[HelenaLC]

Wowww, so fast, thank you!

Ran 0.22.0 and the DEPRACATED_ENSGs have magically gone.

1. Got it! Something like what I got should do and is all we need for now.
2. Okay, I can do this manually then in a couple lines of code.
3. I'd love to get this running (so fast and easy!), but admittedly my understanding is limited... The probes CSV I provided looks as follows, but didn't work. I'm confused by ...or provide probe set when simpleaf index was run with a probe set. Should I provide an other file/command instead, or provide the CSV both to index and multiplex-quant? Surely I'm missing something.

Fwiw, I get around 18k features (similar to CellRanger, but not identical) and 50k cells (double CellRanger) from 500k observations pre-cellbender. But that's surely off if information on include is currently lacking.

Forgive the first-time user stupidity, but I'm a happy guinea pig if there is anything I can try/give feedback on. Just worried to mess it up (this being "real" data...).

# this runs cleanly
simpleaf index --use-piscem --output $IDX --threads 40 --probe-csv probes.csv

# index/
piscem_idx_cfish.json  piscem_idx.ectab    piscem_idx.sigs.json  piscem_idx.ssi.mphf  simpleaf_index.json
piscem_idx.ctab        piscem_idx.refinfo  piscem_idx.ssi        piscem_idx_ver.json  t2g_3col.tsv

simpleaf multiplex-quant \
  --chemistry 10x-flexv1-gex-3p \
  --output $SUB/$PAT \
  --organism human \
  --reads1 $r1 \
  --reads2 $r2 \
  -t $NTH \
  --index $IDX
# error (see above)

# probes.csv head
gene_id,probe_seq,probe_id,included,region
ENSG00000000003,GGTGACACCACAACAATGCAACGTATTTTGGATCTTGTCTACTGCATGGC,ENSG00000000003|TSPAN6|8eab823,TRUE,spliced
ENSG00000000003,TCTGCATCTCTCTGTGGAGTACAATCTTCAAGTTTACAGCAACTCTTAGG,ENSG00000000003|TSPAN6|9d7fe51,TRUE,unspliced
ENSG00000000003,AAAGCTGTTCTTAATCTCATGTCTGAAAACAAATCCTACGATGGCAGCGA,ENSG00000000003|TSPAN6|d2b5833,TRUE,spliced
ENSG00000000005,CGTGACGGGTCTTCTCTACTTTCACTTGAGGGACCACCCACTGTTCATTT,ENSG00000000005|TNMD|7790621,TRUE,unspliced

[rob-p]

Hi @HelenaLC,

Thanks for the fast feedback! So version 0.23 is now available with AnnData output for multiplex mode ;P. You have to remove any pre built index in your alevin-fry home directory though. The new version will propagate gene symbols in var["gene_symbols"].

The different number of cells is almost certainly due to the fact that cellranger is doing filtering internally, but we are providing the raw matrix (so users can use their own favorite filtering downstream). We report any cell with > 10 reads.

With 0.23, you also get a separate sample ID metadata row so demuxing the matrix for QC should be straightforward. Let me know what you find!

Best,
Rob

[HelenaLC]

Hm... same code as before (default, no custom index) but adding --anndata-out with v0.23.0 I get the quantification to pass, but then:

2026-03-23T16:14:17.501964Z  INFO simpleaf::utils::prog_utils: command returned successfully (exit status: 0)
2026-03-23T16:14:17.517010Z  INFO af_anndata: USA mode : false
2026-03-23T16:14:37.471387Z  INFO af_anndata: Reading MM into AnnData took 19.954358372s
Error: could not parse `0.06666667` as dtype `i64` at column 'MappingRate' (column number 6)

The current offset in the file is 24865 bytes.

You might want to try:
- increasing `infer_schema_length` (e.g. `infer_schema_length=10000`),
- specifying correct dtype with the `schema_overrides` argument
- setting `ignore_errors` to `True`,
- adding `0.06666667` to the `null_values` list.

Original error: ```remaining bytes non-empty```

af_quant/alevin/ does, however, show this:

quants.h5ad  quants_mat_cols.txt  quants_mat.mtx  quants_mat_rows.txt

[rob-p]

Hi @HelenaLC,

Might you be able to share the full probe and sample barcode file? This was tested internally on the 4-plex 10x flex v1 sample data and ran successfully to completion, but I imagine that if any of the assumptions on input are too strong, this could cause an issue. I'd like to fix this on your actual data ASAP to ensure this functionality works end to end for you!

Best,
Rob

[rob-p]

What the error message is suggesting is that the conversion tool is attempting to parse a featureDump column as the wrong format, which obviously gets in the way of proper conversion. One way this might happen is if the number of columns is misaligned (multiplex quantification has one more column than single sample), but that should be handled automatically!

--Rob

[HelenaLC]

Would be happy to, but can't figure it out from our wet lab production... in previous CellRanger runs (not by me) I see only

• reference GRCh38-2024-A but Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv (I just asked them out on that); that should be from here.
• for the sample barcodes, I only see BC001-4, but no .csv specification anywhere...
• there are 4 samples foa shoa, I see a patient identifier for each BC
• simpleaf v0.22.0 seems to get that, there were 100k "cells" per BC1-4, and a couple odd ones in BC5+

In any case, my simpleaf home lists probe_indices/downloads/Chromium_Human_Transcriptome_Probe_Set_v1.1.0_GRCh38-2024-A.csv. Could incompatible ref vs. probe vs. barcode data cause this?

[rob-p]

It shouldn't — because the probe and sample barcode list will both be automatically fetched if using the default index.

One thing that might help is if you could share the json files present in your map and quant dirs. Something like this should work:

cd /path/to/simpleaf_output && find map quant -type f -name '*.json' -print0 | tar --null -czf simpleaf-jsons.tar.gz --files-from -

that along with the output of simpleaf inspect should give a full view of the program environment.

Sorry for all of the quirks in getting this new workflow working smoothly. Thanks for helping out with it, and I'm dedicated to getting it working smoothly for you!

[HelenaLC]

Thank you, that's very kind... I'm discussing with wet lab on the side and just to note that these data specifically are a couple years old, hence the 2020 (so they say), but now people run the 2024 probe list (so they say).

• .json files: simpleaf-jsons.tar.gz
• output of simpleaf inspect: inspect.txt

[rob-p]

Thanks; these outputs all look OK. One more thought. Could you share the first few lines of your featureDump.txt file? I think that's the one that's failing to convert properly.

[HelenaLC]

head -n 15 featureDump.txt ... 'n tail:

CB      sample_name     CorrectedReads  MappedReads     DeduplicatedReads       MappingRate     DedupRate       MeanByMax       NumGenesExpressed      NumGenesOverMean
TACAATGAGTAAGTGC        BC001   235638  235638  63706   1       0.27035537      0.0019917118    9675    2282
ATTCGTCCACATTCGT        BC001   42269   42269   11153   1       0.26385766      0.008894131     4431    1136
TGGTTACGTCCATCCT        BC001   42601   42601   10626   1       0.24943076      0.010409758     4381    1145
CAAATTGAGAAGGTTC        BC001   41836   41836   12211   1       0.2918778       0.0063241054    4449    1068
GAACGAAAGATGCCTC        BC001   43092   43092   10757   1       0.24962871      0.027268464     4641    1283
CCATTGTCAATGGGAG        BC001   42016   42016   10837   1       0.25792554      0.0042325584    4630    1193
GCCCTCAAGTATGGGT        BC001   42513   42513   10599   1       0.24931197      0.0007490434    2636    130
GTTTGGGAGTTTGCTG        BC001   42123   42123   12009   1       0.28509367      0.02030911      4969    1324
...
AGTCGCGCAGGGATGA        BC004   62      62      14      1       0.22580644      1       14      0
CATAATCTCACTCGCG        BC004   71      71      19      1       0.26760563      0.5277778       18      1
CAATTGCGTTAATCCA        BC004   91      91      31      1       0.34065935      0.3974359       26      4
ATCTTAGGTGCGGCTT        BC004   85      85      24      1       0.28235295      0.5714286       21      3
CGTAATCGTCACAGAA        BC004   72      72      23      1       0.31944445      0.21296297      9       1
AAGCAACTCCCACATA        BC004   57      57      12      1       0.21052632      1       12      0

[rob-p]

Ahh --- I see! So I think the issue is the automatic inference of the column type from the first few rows. Here, the MappingRate column is 1 for the first several rows. So, polars likely infers it as an integer. Later, we hit a row where it is fractional, and the parser errors out. The solution is to encode the types explicitly. Let me fix this and push an update. It doesn't happen in the test data we have, because we have fractional rates near the start.

[rob-p]

Ok, 0.23.2 has now been tagged and released on GitHub. It will take a little bit to propagate through bioconda. You can try and test the GitHub executables if they will run on your cluster, otherwise, I'll ping back here when everything has been updated via bioconda.

[rob-p]

Hi @HelenaLC,

The new version is merged upstream, so should be available as soon as it propagates to the conda servers (bioconda/bioconda-recipes#63791). Let me know if this produces a clean run for you.

--Rob

[HelenaLC]

On it! Still not getting it from conda search -c bioconda simpleaf, but I can do a quick simpleaf multiplex-quant (and hopefully check the .h5ad) if it comes up before I sleep (then run cellbender over night) :)) Keep you posted! *I tried alternative installation, cargo etc., but our server is in denial.