Improvement Proposal over bvbabel APIs

[ChengranAA]

Dear Faruk,

I have a proposed improvement over general API calls.

I implemented a higher abstraction layer that allows bvbabel to read typed objects rather than named dictionaries and numpy arrays, which also does not break the original dependency since it relies only on Python built-in features.

This way it lets users take advantage of IDE syntax suggesting for easy access to fields.

Example change like this:

https://github.com/ChengranAA/bvbabel/blob/main/bvbabel/vmr.py

And code for reading a VMR file will be like this:

from bvbabel.vmr import VMR

vmr = VMR.read("example.vmr")
print(vmr.dim_x, vmr.data.shape)
vmr.write("output.vmr")

# header-only (skip voxel data)
header = VMR.read("example.vmr", load_data=False)
print(header.data)  # None

And this does not break the original APIs:

header, data = bvbabel.vmr.read_vmr("subject.vmr")
bvbabel.vmr.write_vmr("output.vmr", header, data)

Regarding issue #21, the data attribute can be skipped by providing the read method with load_data=False.

Currently it's only proof of concept. Let me know your thoughts!

[ofgulban]

Hi @ChengranAA , thanks for opening this issue and asking.

A few initial reactions:

1. Why do we need a higher abstraction layer?
2. Do these changes solve previously unsolved problems? Please provide cases.
3. I am not sure if I like the load_data=False design. I think better/simple solution is splitting header read and data read functions apart. Also note that bvbabel is designed to serve as a file format specification. This is why read write functions are shallow and very sequential. I do not want to complicate this by inserting abstraction layers or more complicated coding patterns like using lambdas. I feel that your VMR changes are too extensive and too over-engineered.
4. I see that you have _bv_to_tal function. I intentionally avoided providing second order utility functions (I mean beyond read, write, create) to keep the library simple. I feel that your changes are going against this design choice as well.

Overall, I am currently failing to see the real-life benefits of this extensive proposal. In addition, I worry that If I accept these changes, bvbabel is going to have a much higher cost of maintenance in the future. Sure, your code looks more sophisticated, advanced, or "modern"; but this exactly against the design principles of bvbabel. If you think I am missing the benefits, please elaborate further and argue more specifically for your proposal.