Enhance docstrings for JansenRitParams and JansenRitModel

[Copilot]

Docstrings in whobpyt/models/jansen_rit/jansen_rit.py were incomplete, inconsistent, and contained unresolved ??? placeholders and TODO comments leaking into public-facing docs. This PR rewrites all class- and method-level docstrings to NumPy style with no code logic changes.

JansenRitParams

• Resolved ambiguous attributes: g (P-to-P gain), y0 (EEG baseline offset), k/ki (external input scaling), cy0 (leadfield projection scale)
• Documented g_f, g_b, lm as kwargs-only attributes with appropriate notes

JansenRitModel

• Fixed typo (Attibutes), removed TODO comments from docstring
• Added missing attribute docs: steps_per_TR, w_p2e, w_p2i, w_p2p
• __init__: documented all parameters including params; clarified that output_size is overridden by lm.shape[0]

Methods

• createIC / createDelayIC: added docs for state_lb, state_ub, delays_max
• setModelSCParameters: rewrote to explain gain matrix initialization; added Notes that this is auto-called in __init__
• forward: corrected tensor shapes (e.g. external is (node_size, steps_per_TR, TRs_per_window)), documented all keys of the returned next_state dict, and clarified the two-level integration loop

Original prompt

The docstrings for the Jansen-Rit model classes and relevant methods within whobpyt/models/jansen_rit/jansen_rit.py are inconsistent and incomplete, although partial documentation exists. Please enhance all class-level and function-level docstrings for both JansenRitParams and JansenRitModel, as well as all their methods (such as __init__, createIC, createDelayIC, setModelSCParameters, and forward).

• Follow standard Python docstring conventions (Google or NumPy style)
• Ensure parameter, return, and attribute documentation is clear and specific
• Clarify ambiguous parameters when possible
• If docstrings exist but are incomplete or unclear, rewrite for clarity

Do not modify any code logic. Only update docstrings in whobpyt/models/jansen_rit/jansen_rit.py.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: add doctrings on jansen rid model?

Assistant: The Jansen-Rit model in the GriffithsLab/whobpyt repository is implemented in the file:

• whobpyt/models/jansen_rit/jansen_rit.py (GitHub link)

This file already has some docstrings, but improvements and additions can be made for function-level docstrings, especially for the JansenRitModel and JansenRitParams classes and their main methods such as __init__, createIC, createDelayIC, setModelSCParameters, and forward.

Here is a suggested update for function and class docstrings, focusing on clarity and completeness, following standard Python conventions:

class JansenRitParams(AbstractParams):
    """
    Class to manage the parameters of the Jansen-Rit neural mass model.

    Provides default values and allows customization through keyword arguments.

    Args:
        **kwargs: Model parameters can be provided to override defaults.

    Attributes:
        A, a, B, b, g, c1, c2, c3, c4, std_in, vmax, v0, r, y0, mu, k, cy0, ki, g_f, g_b, lm: 
            Model parameters, most as floats.
    """

    def __init__(self, **kwargs):
        """
        Initializes the JansenRitParams object.

        Args:
            **kwargs: Keyword arguments for model parameters. All parameters have defaults.
        """

class JansenRitModel(AbstractNeuralModel):
    """
    Jansen-Rit neural mass model for simulating whole-brain EEG signals.

    Attributes:
        state_size (int): Number of state variables.
        output_size (int): Number of EEG output channels.
        node_size (int): Number of regions of interest (ROIs).
        step_size (float): Integration step size for the forward model.
        tr (float): Sampling interval for simulated EEG signals.
        TRs_per_window (int): Number of time points per simulation window.
        sc (ndarray): Structural connectivity.
        lm (ndarray): Leadfield matrix mapping sources to EEG space.
        dist (ndarray): Distance matrix.
        use_fit_gains (bool): If True, fitting gains are enabled.
        use_laplacian (bool): If True, Laplacian regularization is used.
        use_fit_lfm (bool): If True, the leadfield matrix is fit.

    Methods:
        createIC(ver, state_lb=-0.5, state_ub=0.5): Creates initial conditions for the model.
        createDelayIC(ver, delays_max=500, state_lb=-0.5, state_ub=0.5): Initial conditions for delays.
        setModelSCParameters(small_constant=0.05): Set model's structural connectivity parameters.
        forward(external, hx, hE): Run model simulation over a window given external inputs and states.
    """

    def __init__(self, params: JansenRitParams, node_size=200, TRs_per_window=20, step_size=0.0001,
                 output_size=64, tr=0.001, sc=ones((200,200)), lm=ones((64,200)), dist=ones((200,200)),
                 use_fit_gains=True, use_laplacian=True, use_fit_lfm=False):
        """
        Construct a JansenRitModel instance.

        Args:
            params (JansenRitParams): Model parameters.
            node_size (int): Number of ROIs.
            TRs_per_window (int): Number of simulated EEG points per window.
            step_size (float): ODE integration step.
            output_size (int): Number of EEG output channels.
            tr (float): Sampling interval (sec).
            sc (ndarray): Structural connectivity, shape (node_size, node_size).
            lm (ndarray): Leadfield matrix, shape (output_size, node_size).
            dist (ndarray): Inter-ROI distance matrix.
            use_fit_gains (bool): Flag to fit gain parameters.
            use_laplacian (bool): Flag to use Laplacian-based connectivity.
            use_fit_lfm (bool): Flag to fit the leadfield matrix.
        """

    def createIC(self, ver, state_lb=-0.5, state_ub=0.5):
        """
        Create random initial conditions for each node and state.

        Args:
            ver (int): Placeholder ve...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. [Learn more about Advanced Security.](https://gh.io/cca-advanced-security)

[JohnGriffiths]

@JohnWangDataAnalyst please do the following for this:

1. from this PR thread, click on the 'chat with copilot' button at top of the screen

2. ask copilot to pull updates from main branch to PR 317

3. if auto-workflows are not triggered by that update, re-run all workflows for this PR

4. ideally then the CI will successfully run on this PR. Also ideall the auto docs build viewable link will be generated.