The rendered version can be found here.

I am not sure what to make of the error message:

scipy/signal/_signaltools.py:2467: in <module>
    def envelope(z: np.ndarray, bp_in: tuple[int | None, int | None] = (1, None), *,
E   TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

This is the only error I found in the failing tests which could be related this PR.

That syntax is not supported in Python < 3.10. from __future__ import annotations at the top of the file might work. Keeping the typing in a stub .pyi file may be easier to work with for now. Alternatively, you can use Union, however, I think the linter may complain about that (not sure).

Thanks @lucascolley, for the prompt answer. It could have been that I asked this question before 😅
Unfortunately, python dev.py lint does not complain...

@yagizolmez would you be interested in reviewing this given your heavy involvement in previous discussions?

@j-bowhay I will leave a review in the upcoming days. I want to note that this is NOT a competing PR with #19814. Following the discussion we had there, I decided to break up the envelope function I proposed and not implement the analytical envelope.

@DietBru I have a quick question before I leave a more detailed review. Comparing this function with hilbert, major additions seem to be:

1. Support for complex-valued signals.
2. The option to upsample the envelope.
3. The option to apply a bandpass filter.

Have you considered extending hilbert rather than adding a new function?

Have you considered extending hilbert rather than adding a new function?

I did, but I came to the conclusion that that would only lead to confusion:

The analytic signal is a concept based on real-valued signals. Rightfully, hilbert() raises a ValueError for complex-valued inputs. Also, changing that behavior could break existing implementations.

The envelope on the other hand is a concept that is inherent to complex-valued signals with real-valued signals being a special case. Note that the treatment of real-valued signals depends on the underlying assumptions of what the signal represents. This is illustrated in the second example of the envelope()'s doc string.

@DietBru I am sorry for the delay. I have been very busy these days, so I am not yet able to provide a detailed review. One thing catched my eye. Under certain circumstances, this function must give the same result with hilbert(), i.e. when z is real and bp_in is selected appropriately. Have you considered writing some tests and benchmarks covering these situations?

One thing catched my eye. Under certain circumstances, this function must give the same result with hilbert(), ...

Good catch, thank you. I found an edge case where the results differ. Hence, I did some refactoring to ensure that envelope() and hilbert() always behave identically. I think it should ready for complete review now.

@yagizolmez would you like to take another look at this?

@lucascolley Thanks for reminding me Lucas. I have gotten extremely busy in the school lately. I will take a look when I have time. @DietBru I apologize.

Resolved merge conflict. Current version of the rendered documentation can be found here.
Test failures seem unrelated.

Thanks for the review @yagizolmez. The updated rendered version of the documentation can be found here,

Do you know anyone who could provide a better review for the complex-valued signal case?

Perhaps @roryyorke or @larsoner ?

The failure in building the docs seem to be a jupyterlite_sphinx problem, hence, unreleated to this PR—will look into that later on.

Rebased this branch on the documentation is building again. The current envelope documentation can be found here. The test failures are generated by special/tests/test_orthogonal_eval.py, hence unrelated to this PR.

Thanks again for your input @yagizolmez — I hope I have sufficiently addressed all your remarks by now.

@DietBru Thanks. I will check in a few days.

Thanks for the feedback @j-bowhay! I think I have incorporated all your suggestions—the rendered documentation can be found here.

Thanks @lucascolley for the review and spotting the typos—I think, I addressed all your comments in the last commit.
The CI errors seem to be caused by #21988 and thus unrelated. From my side it is ready for merging.

thanks Dietrich, let's check the rendered docs once gh-21988 is resolved.

thanks Dietrich, let's check the rendered docs once gh-21988 is resolved.

Glancing at the rendered docs, I saw no surprises. 🎉