Documentation Restructuring Proposal

[wilsonrljr]

I’m currently working on several updates to the documentation.

@oliveira-mark made a huge contribution by creating the new landing page and is also working on various backend improvements.
Additionally, @dj-gauthier provided valuable feedback some time ago regarding the structure of the documentation, highlighting how it was difficult for users to find the information they needed.

Following @oliveira-mark's suggestions and after reviewing the recent NumPy NEP 44 on restructuring documentation, I’ve started implementing changes.
Today, I made the first major update, but this is just the beginning.

I’ve created a draft page outlining the proposed restructuring: Documentation Overview.

You might notice some small improvements while navigating the docs already, but I’d love to hear your thoughts.
Any feedback or suggestions would be greatly appreciated!

@samirmartins, I'd like to hear you too.

[oliveira-mark]

Awesome! I will keep improving the appearance of the documentation following this new structure.

[wilsonrljr]

I am considering creating templates for tutorials and how-to materials to make it easier for beginners and ensure greater consistency throughout the documentation. Additionally, I plan to add a section that guides users on how they can contribute, particularly in areas such as basis functions, model structure selection methods, and parameter estimation. Currently, this information is missing, which may make it difficult for potential contributors to get involved.

[oliveira-mark]

I agree. The "How to contribute" section needs to be revised. I have some ideas to make this page more user-friendly. I'll bring updates soon.

[dj-gauthier]

Currently, the documentation is not great for problems like generative forecasting of chaotic systems. I can create a module that teaches this, but I probably can’t get to it until June. Having a template would be great. Do you prefer a Jupyter notebook or straight Python?

…

On Wed, Mar 5, 2025 at 5:43 PM Marcos Oliveira ***@***.***> wrote: I agree. The "How to contribute" section needs to be revised. I have some ideas to make this page more user-friendly. I'll bring updates soon. — Reply to this email directly, view it on GitHub <#175 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALEY24WQCXMYYI5V7D5NDRL2S542FAVCNFSM6AAAAABXVQYX3SVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTENBQG4ZDENA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[wilsonrljr]

No problem at all, and absolutely no rush! Whenever you have time to work on it is perfectly fine. I prefer Jupyter notebooks for tutorials since they make it easy for people to download and run on the go, but I’m happy to discuss other formats if you have a different preference. Thanks again for your help!

[samirmartins]

Hey @wilsonrljr! Thanks for getting in touch.

@oliveira-mark, congratulations on the modern and incredible landing page!

Following the proposed key categories, I believe that smoothing the beginner's learning curve should be a key point of attention, since System Identification is, by definition, surrounded by deep math and algebra.

For experienced users, a good starting point would be to clearly indicate where contributions are most needed.

Questions like "Are deep models the library's main focus?" or "Is the library focused on parsimonious modeling?" should be directly addressed in the Documentation (within the How to contribute section). This way, users will know if what they are working on aligns with SysIdentPy's scope.

@wilsonrljr, taking the opportunity to share that I'm still working on the MERR implementation, as you know, and I'll reach out soon with updates.

Let me know if you need any help with the documentation, including writing parts of it/sections.

[oliveira-mark]

Thank you, @samirmartins!

[wilsonrljr]

Good suggestions, Samir! I'm writing a new page for the developer guide section that goes in the same direction you've suggested.

I'm also working on a new model structure selection based on sobolev spaces. It's an adaptation of the ERR and because a lot of code are shared from FROLS, I'm writing a base class for ERR based methods like FROLS. You'll probably have to change part of your code (if you are using FROLS as a base code), but it should be straightforward to do it.

I'm trying to reach the author of the method I'm trying to implement to check if he can review what I've did, but the changes should be available soon.

[wilsonrljr]

Hello @samirmartins,

I plan to merge the changes I've implemented tomorrow. These updates are currently available on the api/base_classes branch. Notably, changes 1 and 2 may directly impact your MERR implementation:

1. Refactoring Utility Modules: The InformationMatrix class has been relocated from narmax_base to a new module, utils.information_matrix. Additionally, certain methods have been moved to the newly created utils.lags and utils.simulation modules.

2. New OFRBase Class: A new OFRBase class has been introduced, encapsulating the core methods required for ERR-based algorithms. Consequently, the FROLS class now inherits from OFRBase and focuses solely on the ERR algorithm. Similarly, a new UOFR algorithm class has been structured to align with this inheritance model.

3. Code Style Improvements: Variable names have been revised to enhance readability and ensure compliance with PEP 8 standards.

4. Test Coverage: Numerous tests have been added across various modules, resulting in a test coverage improvement to 92%.

While these modifications are extensive, adapting existing methods to the new structure should be straightforward. If you encounter any challenges during this transition, please feel free to reach out. We can arrange a call to guide you through the adaptation process.