Design strategy

[tsalo]

In our monthly developers call, we discussed how we'd like phys2denoise to be structured (along with the other packages). Here are the minutes for anyone who's interested.

There were a few ideas that were discussed. Some of these ideas have broad implications for the whole suite, and, if we decide to go with one of those, then we can figure out how to synchronize package-specific discussions within the suite.

1. phys2denoise operates on a shared object with peakdet. This class would represent physio data from a single frequency, and could end up being restricted to a single channel.
   • Pros:
     1. Classes group attributes (e.g., the time series and the sampling rate) together.
     2. peakdet will need its own class to track changes to the data. While we don't need that same functionality in phys2denoise, it's helpful to have the same design philosophy across packages.
   • Cons:
     1. We would need to either (1) duplicate our class definition across peakdet and phys2denoise or (2) define the class in one package and then manage changes to the class across both.
     2. For "higher level" users, who want to use the individual functions, having to initialize or operate on a new object for their data (instead of a common one like a numpy array or a pandas DataFrame) will make it harder for them to start using the package.
     3. Mocking up package-specific objects for tests is hard and those objects can add overhead to your CI.
2. phys2denoise's object is moved all the way up to physutils. Same pros and cons as the above, but with additional difficulties in synchronizing the class definition across packages.
3. A purely functional approach. All functions in phys2denoise would operate on arrays or possibly DataFrames, with no package-specific classes defined.
   • Pros:
     1. This makes the individual functions easier to work with.
     2. Most users will only interact with the main workflow function/CLI, so the internal structure of the function is not important (i.e., classes are not necessary).
     3. Functions are easier to test.
   • Cons:
     1. Devs who get used to OOP in peakdet and phys2bids might be confused by phys2denoise, although the opposite is more likely, since functional programming is more intuitive.

If anyone has other ideas, please comment and I can update this issue summary.