Add documentation example for DecompositionSeries

[stephprince]

Motivation

Fix #1938.

Note that this example is pending these schema updates: NeurodataWithoutBorders/nwb-schema#593, which make band_mean and band_std optional.

How to test the behavior?

cd docs
make clean && make html

Checklist

• Did you update CHANGELOG.md with your changes?
• Have you checked our Contributing document?
• Have you ensured the PR clearly describes the problem and the solution?
• Is your contribution compliant with our coding style? This can be checked running ruff check . && codespell from the source directory.
• Have you checked to ensure that there aren't other open Pull Requests for the same change?
• Have you included the relevant issue number using "Fix #XXX" notation where XXX is the issue number? By including "Fix #XXX" you allow GitHub to close issue #XXX when the PR is merged.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.04%. Comparing base (084aa55) to head (b3a7934).
Report is 1 commits behind head on dev.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev    #1981   +/-   ##
=======================================
  Coverage   92.04%   92.04%           
=======================================
  Files          27       27           
  Lines        2704     2704           
  Branches      705      705           
=======================================
  Hits         2489     2489           
  Misses        141      141           
  Partials       74       74           

Flag	Coverage Δ
integration	72.92% <ø> (ø)
unit	82.98% <ø> (ø)

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

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[ehennestad]

Hi @stephprince. I replicated this example in the ecephys tutorial for matnwb and then I ran nwbinspector on the output file. The nwbinspector errored out before generating the results with the following error:
TypeError: 'MissingDataType' object is not iterable.
The nwbinspector works fine prior to adding the DecompositionSeries to the nwb file.

I thought it was something matnwb specific, but got the same issue when running nwb inspector on the output of the pynwb tutorial with the new DecompositionSeries example. Could you check if you see the same?

[stephprince]

@ehennestad which version of the schema were you using?

I'm waiting to merge this until we release version 2.8.0 of the schema, because this current example will generate invalid files until band_mean and band_stdev are made to be optional columns on the DecompositionSeries.bandstable.

I get the same error as you with the current example + schema, but the inspector should run ok on the file if you change the code to be:

for band_name, band_limits in bands.items():
    decomp_series.add_band(band_name=band_name, band_limits=band_limits, band_mean=1.0, band_stdev=1.0)

but I don't think band_mean or band_stdev are applicable in many cases so ideally we would wait until the next schema release (which should be happening in the next week).

[ehennestad]

I was using v2.7.0. Thanks for pointing that out again about the extra required properties. I had tried to add them, but found a typo and after correcting that, it works!

[stephprince]

@rly I've updated the example to add the required band_mean and band_stdev columns as nans so that the tutorial generates valid files using schema v2.7.0 (though it violates best practice suggestions by having a column of all nans).

Once schema v2.8.0 is released, we can update this tutorial to remove those optional columns.