# neurostatx.cli.PartialLeastSquareRegression

*module*

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/PartialLeastSquareRegression.py#L1-L1)

## neurostatx.cli.PartialLeastSquareRegression.app

*attribute* · *module attribute*

```python
app = App(default_parameter=Parameter(negative=()))
```

Cyclopts application for the PartialLeastSquareRegression
command-line tool.

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/PartialLeastSquareRegression.py#L23-L23)

## neurostatx.cli.PartialLeastSquareRegression.PartialLeastSquareRegression

*function*

```python
def PartialLeastSquareRegression(in_graph: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], out_folder: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], attributes: Annotated[List[str], Parameter(group='Model Parameters', show_default=True)] = None, weight: Annotated[str, Parameter(group='Model Parameters', show_default=True)] = 'membership', splits: Annotated[int, Parameter(group='Model Parameters', show_default=True)] = 10, permutations: Annotated[int, Parameter(group='Model Parameters', show_default=True)] = 1000, scoring: Annotated[ScoringMethod, Parameter(group='Model Parameters', show_default=True)] = ScoringMethod.r2, processes: Annotated[int, Parameter(group='Model Parameters', show_default=True)] = 1, plot_distributions: Annotated[bool, Parameter(show_default=True, group='Visualization Options')] = False, verbose: Annotated[bool, Parameter(-v, --verbose, group='Optional parameters')] = False, save_parameters: Annotated[bool, Parameter(-s, --save_parameters, group='Optional parameters')] = False, overwrite: Annotated[bool, Parameter(-f, --overwrite, group='Optional parameters')] = False)
```

Fit partial least squares regression of node attributes against
graph edges.

PartialLeastSquareRegression uses node attributes as predictors and edge
weights as the response. It cross-validates to choose the number of
components, then runs permutation testing for statistical significance. It
writes PLSR coefficients, statistics, and plots of attribute and
edge-weight distributions and of the coefficients.

> **Notes**
>
> **Preprocessing**
> 
> Data are scaled to unit variance and zero mean. Edge weights are
> log-transformed; for now this assumes the weights are membership values
> from a fuzzy clustering analysis.
> 
> **Node attributes**
> 
> The script takes a single .gexf graph file, fetches node attributes from
> it, and runs PLSR on those attributes and the edge weights. If no
> attributes are provided, all attributes in the graph are used. To attach
> attributes to nodes, see
> [AddNodesAttributes][neurostatx.cli.AddNodesAttributes.AddNodesAttributes].
> 
> **Scoring**
> 
> Permutation testing assesses whether the model is statistically
> significant. The p-value uses the R2 score by default; other scores are
> listed in the scikit-learn scoring documentation [1]. The single-tailed
> p-value is:
> 
>     p-value = ∑(score_perm >= score) / (nb_permutations)
> 
> **Coefficient significance**
> 
> Coefficient p-values are also computed from the permutation distribution
> by comparing PLSR coefficients to permuted coefficients. The two-tailed
> p-value is:
> 
>     p-value = ∑(abs(coef_perm) >= abs(coef)) / (nb_permutations)

> **References**
>
> [1] [scikit-learn scoring
> parameter](https://scikit-learn.org/stable/modules/model_evaluation.html#scoring-parameter)

**Parameters**

- `in_graph` (`str`) — Graph file containing the data for the PLSR model.
- `out_folder` (`str`) — Output folder.
- `attributes` (`List[str]`) (default: `None`) — Attribute names to include in the PLSR model. If None are provided, all attributes will be included. Defaults to None.
- `weight` (`str`) (default: `'membership'`) — Edge weight to use for the PLSR model. Defaults to ``membership``.
- `splits` (`int`) (default: `10`) — Number of splits to use for the cross-validation. Defaults to 10.
- `permutations` (`int`) (default: `1000`) — Number of permutations to use for the permutation testing. Defaults to 1000.
- `scoring` (`ScoringMethod`) (default: `ScoringMethod.r2`) — Scoring method to use for the permutation testing. Defaults to r2.
- `processes` (`int`) (default: `1`) — Number of processes to use for the cross-validation. Defaults to 1.
- `plot_distributions` (`bool`) (default: `False`) — If true, will plot the distributions of the edges' weights. Defaults to False.
- `verbose` (`bool`) (default: `False`) — If true, produce verbose output. Defaults to False.
- `save_parameters` (`bool`) (default: `False`) — If true, will save input parameters to .txt file. Defaults to False.
- `overwrite` (`bool`) (default: `False`) — If true, force overwriting of existing output files. Defaults to False.

**Examples**

```bash
PartialLeastSquareRegression --in-graph graph.gexf
--out-folder output_folder -v -s
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/PartialLeastSquareRegression.py#L28-L350)