[r] SOMASparseNDArray: sparseMatrix zero-based shim to facilitate soma_joinid lookup

[mlin]

Extended discussion: #1232

To load a one-based Matrix::sparseMatrix with the contents of a zero-based SOMASparseNDArray, we add one to the offsets on each dimension. However, these dimensions are usually populated with soma_joinid intended to match the soma_joinid column in the obs & var data frames, and shifting them by one makes this join operation very error-prone.

Here we introduce a minimal shim for sparseMatrix that provides matrix access with zero-based indexes. To make this explicit for the user, we rename SOMASparseNDArray$read_sparse_matrix() to SOMASparseNDArray$read_sparse_matrix_zero_based(). The shim supports only minimal access operations, which is intentional to prevent "mixing" it with conventional one-based objects. If needed, the fully-featured sparseMatrix is recovered by calling as.one.based() on the shim. Thus, the default behavior is to match soma_joinid but an advanced user can explicitly change to one-based indexing for further use in R.

This is a refinement of the first attempt #1306 which was far more complex and error-prone, attempting a subclass with selected methods overridden instead of the distinct wrapper shim shown here.

[codecov-commenter]

Codecov Report

Patch coverage has no change and project coverage change: -12.04 ⚠️

Comparison is base (af81393) 65.52% compared to head (e342e0e) 53.48%.

❗ Current head e342e0e differs from pull request most recent head 1a1b04c. Consider uploading reports for the commit 1a1b04c to get more accurate results

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #1313       +/-   ##
===========================================
- Coverage   65.52%   53.48%   -12.04%     
===========================================
  Files          97       61       -36     
  Lines        7768     5175     -2593     
===========================================
- Hits         5090     2768     -2322     
+ Misses       2678     2407      -271     

Flag	Coverage Δ
python	?
r	53.48% <ø> (-0.53%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 42 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[mlin]

@eddelbuettel Updated NAMESPACE and added the Rd's for the new methods. Perhaps we leave updating the existing Rd's to a followup since, as you noted, it's a lot of unrelated changes.

[eddelbuettel]

Thanks for adding it.

[eddelbuettel]

I think this is good to go.

[mlin]

@eddelbuettel thanks!

@mojaveazure @aaronwolen double-checking just since this was such a tricky topic -- any last comments/concerns?