Add harp-python migration guide - #23
Conversation
|
@bruno-f-cruz wouldn't it be better to add this to harp-python instead? If anyone is already starting with pyharp they can just follow the getting started guide and examples and I feel would be cleaner if we didn't have back references. The plan I was considering is to release one last version of harp-python that officially deprecates everything and includes guide and warnings covering all this. |
|
@bruno-f-cruz, I was trying to figure out how to do some of the same things from harp-python, so a migration guide is great! As an aside, I am still playing around with the package, but I was wondering about the difference between accessing the register by address and by name in pyharp: Coming from harp-python, I feel it's a bit clunky where both are accessed in the same way (swapping a string or an int in the same call). Would you consider changing reader.read() to accept a string instead (e.g. reader.read("AnalogData") and then inferring that it's accessing the device module and register class. Sorry, I might have missed a prior discussion regarding this! |
|
We could add yet another overload but I kinda don't like it tbh. The address is an useful overload since it is something that exists in the binary protocol. If you want to use a string it will match the name of the register that you need to pass anyway so not really sure what the gain would be. But try to convince @glopesdev 😆 he may agree with you. |
|
@banchan86 @bruno-f-cruz The advantage of using modules directly is that you have "strings" which are type-safe and discoverable (and faster to type since you don't need quotes and have auto-completion). What I think may be the problem here is that access to the module is circuitous via the Intuitively I would expect the following for consistency: from harp.device import behavior
# passing behavior below would be optional but validate
# that the dataset does match the behavior whoAmI
reader = create_dataset_reader(behavior, "session.harp")
df = reader.read(behavior.AnalogData) |
e6f5fe9 to
a8d3c54
Compare
a8d3c54 to
44d14b5
Compare
44d14b5 to
85f6373
Compare
85f6373 to
fee81da
Compare
c555285 to
f4d0a22
Compare
f4d0a22 to
f6836c3
Compare
f6836c3 to
d3cd6c5
Compare
d3cd6c5 to
7e167a0
Compare
open_dataset replaces create_dataset_reader throughout, read takes a register name as well as a class or address, and the epoch example and the parameter table match the current reader: epoch is set once on open_dataset, keep_type keeps its harp-python spelling, and time_index is new, since harp-python inferred the index from the first frame. read_all is gone, so whole-session loading becomes a comprehension over contents, which gains a section of its own. A new section warns that harp-data returns a bitmask register as a single integer column unless demux_bit_masks is set, so a script selecting a flag by name needs it. The static package example imports from the harp.device namespace and names no distribution. Em-dashes, second person and two mid-sentence enumerations are rephrased, and the horizontal rules are removed.
7e167a0 to
ed43955
Compare
The guide maps each harp-python workflow to its harp-data equivalent: create_reader to open_dataset, attribute access on the reader to read by class, name or address, read_all to a comprehension over contents, and harp.read to harp.data.read. A parameter table pairs the old keyword arguments with the new ones. It also records the change most likely to break working code. A bitmask register no longer expands into a boolean column per flag, so selecting a flag by name needs demux_bit_masks=True. --------- Co-authored-by: glopesdev <g.lopes@neurogears.org>
3 participants
This PR adds a short description on how to migrate from the harp-python package to help with the eventual deprecation of that package