1.0 Refactor & Updates

[tom]

Note: this issue has been updated to re-organized into an overall plan for refactors and updates for an API breaking, major update 1.0.0 release.

This refactor is modeled on the refactor for NDSP for the 2.0 release. The main PR for that was in neurodsp-tools/neurodsp#150. Checking some of the commits / diffs / updates, if they are readable, should hopefully be something of a model for this update.

To have an easier organizations of the updates, and review process, let's do a one-thing-at-a-time process, so probably each of the following points should be 1 PR (or possibly more). I think it makes sense to do these in order, top to bottom.

Scoping & Dependency Structure (#31)

• remove the sim code, and associated test code, etc (this now lives in NDSP)
• remove the current filter code, and add NDSP as a dependency for this stuff, updating to use the now updated versions of the same code, from NDSP
• work through the burst file, and remove copied code. Burst procedures are to be considered a core functionality of ByCycle, but for the moment we need to balance shared code between NDSP / ByCycle.

Code Style

• consolidate var names to be consistent with how NDSP has things, and also to match code style (for example, snake_case for all variables, all vars at least 2 characters, etc)
  • for example x -> sig and Fs -> fs
  • run a linter, and update code accordingly
• check through for code & doc style (for example, capitalization & punctuation in docstrings)

Modularize & Code Updates

• move any plotting functions to their own /plts/ folder
  • Plot code that is written out to create plots in the tutorials, could also be made into functions that are added to the module.
• split out some of the larger functions, increasing the modularity of the code, and providing more access to some meta-data components (this could be done file-by-file. Example: #46)
  • for example, separating out the metadata for peak, trough and zero-crossings from the analysis, so that it is independently accessible and useable (comment from Erik)
  • this will also include updating and splitting up the tests
• For the new modularized organization, add doctest examples

Tutorials / Documentation

• Update tutorials, reflecting all the new code updates. Work through and see if we should extend, add new things to the tutorials, make sure we have good coverage of ideas, etc.
• Update the README. The code overview can probably be minimized, and point more directly to the documentation website.
• Add glossary (#62) & reference pages to the docsite
• Add helper function to download data for the tutorials / examples (so they can be downloaded & run)
  • See example on NDSP: https://github.com/neurodsp-tools/neurodsp/blob/master/neurodsp/utils/download.py

Code tests

• Check through the tests, re-organizing anything needed given the updates.
• Add / expand new more tests to expand testing of the module. Do so with simulation, and drops old approach of data loading.
• Organize tests into sub-folders, like it is now in NDSP

Extensions

• Add 2D & 3D support (#52)

Installation

• Add conda support, to be able to download from conda-forge

[Scott Cole]

all those 3 points make sense.

but in the last point's example, isn't this already available in bycycle.cyclepoints.find_extrema() and find_zerox()?

[tom]

The quick discussion I had with Erik was not necessarily about computing them, but about how they are stored - basically putting the meta-data into a separate data frame, for easier recycling between different runs, where as as is because it's all by default stored in the same df, it's harder to do so.

I might have gotten that all wrong - I don't really know the use-case - so maybe @parenthetical-e can clear up my clobbered second-hand messages.

I don't think the idea rests on that example in particular though - as someone steps through the code for the first couple points, maybe there will be some places to refactor and modularize, maybe not so much (at this point in time, I'm not super familiar with the details of how it all works).

[Scott Cole]

I think I gotcha. Yeah. This could definitely be improved.

I never got around to making the dataframe more modular, but it would be nice for the user to be able to only compute certain columns (a lot of them are really unnecessary and I myself almost never used them).

And it would also be nice for us to easily add new features to that dataframe, if desired.

[tom]

Thanks @ryanhammonds for a TON of work doing the 1.0 re-furbish of ByCycle!

Everything here is now addressed - closing now!