# neurostatx.cli.ConfirmatoryFA

*module*

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

## neurostatx.cli.ConfirmatoryFA.app

*attribute* · *module attribute*

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

Cyclopts application for the ConfirmatoryFA command-line tool.

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

## neurostatx.cli.ConfirmatoryFA.ConfirmatoryFA

*function*

```python
def ConfirmatoryFA(in_dataset: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], id_column: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], desc_columns: Annotated[int, Parameter(show_default=False, group='Essential Files Options')], out_folder: Annotated[str, Parameter(group='Essential Files Options')] = './ResultsCFA/', loadings_df: Annotated[str, Parameter(show_default=False, group='Factorial Analysis parameters')] = None, model: Annotated[List[str], Parameter(show_default=False, group='Factorial Analysis parameters')] = None, threshold: Annotated[float, Parameter(--threshold, group='Factorial Analysis parameters')] = 0.4, iterations: Annotated[int, Parameter(--iterations, group='Factorial Analysis parameters')] = None, 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)
```

Perform confirmatory factor analysis from loadings or a
lavaan-style model.

ConfirmatoryFA tests a hypothesized model of the relationships between
observed variables and latent constructs. It writes factor scores, goodness
of fit statistics (Chi-square, RMSEA, CFI, TLI), and an HTML report.

> **Notes**
>
> **EFA vs CFA scores**
> 
> Both EFA and CFA scores can be used to derive factor scores. There is no
> clear consensus on which is preferred [2], so the script outputs both. The
> two methods are highly correlated [3]; the choice is a matter of
> preference. A useful reference for the fit metrics is [1].
> 
> **Input specifications**
> 
> The dataset can contain multiple descriptive columns before the variables
> of interest. Specify that count with --desc-columns. Rows with missing
> values are removed by default; use the mean or median option to impute
> missing data (be cautious when doing this).

> **References**
>
> [1] [Costa, V., & Sarmento, R. Confirmatory Factor
> Analysis](https://arxiv.org/ftp/arxiv/papers/1905/1905.05598.pdf)
> 
> [2] [Whether to use EFA or CFA to predict latent variable
> scores](https://stats.stackexchange.com/questions/346499/whether-to-use-efa-or-cfa-to-predict-latent-variables-scores)
> 
> [3] [Comparison of factor score estimation
> methods](https://github.com/gagnonanthony/NeuroStatX/pull/11)

**Parameters**

- `in_dataset` (`str`) — Input dataset to use in the factorial analysis.
- `id_column` (`str`) — Name of the column containing the subject's ID tag. Required for proper handling of IDs.
- `desc_columns` (`int`) — Number of descriptive columns at the beginning of the dataset to exclude in statistics and descriptive tables.
- `out_folder` (`str`) (default: `'./ResultsCFA/'`) — Path of the folder in which the results will be written. If not specified, current folder and default name will be used. Defaults to ``./ResultsCFA/``.
- `loadings_df` (`str`) (default: `None`) — Filename of the dataframe containing the loadings of the EFA analysis. Columns must be factors and rows variables. Defaults to None.
- `model` (`List[str]`) (default: `None`) — Model specification for the CFA analysis. Must be provided within brackets (ex: --model "factor1 =~ var1 + var2 + var3" --model "factor2 =~ var4 + var5"). Defaults to None.
- `threshold` (`float`) (default: `0.4`) — Threshold to use to determine variables to include for each factor in CFA analysis (ex: if set to 0.40, only variables with loadings higher than 0.40 will be assigned to a factor in the CFA model). Defaults to 0.40.
- `iterations` (`int`) (default: `None`) — Number of iterations to perform the bootstrapping of the model. Defaults to None.
- `verbose` (`bool`) (default: `False`) — If true, produce verbose output. Defaults to False.
- `save_parameters` (`bool`) (default: `False`) — If true, save the parameters used in the analysis in a text file. Defaults to False.
- `overwrite` (`bool`) (default: `False`) — If true, force overwriting of existing output files. Defaults to False.

**Examples**

```bash
ConfirmatoryFA --in-dataset dataset.csv --id-column ID --desc-columns 1
--out-folder ./output/ --loadings-df loadings.csv --threshold 0.40
--mean -v -f
```

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