Registry / data / nfoursid

nfoursid

JSON →
library1.0.2pypypi✓ verified 85d ago

NFoursID is a Python library that implements the N4SID algorithm for subspace identification, along with Kalman filtering and state-space models. State-space models are versatile tools for representing multi-dimensional time series, encompassing models like ARMAX. The current version is 1.0.2. The project appears active, with its latest release (1.0.2) showing an unusual future publication date of July 24, 2025, on PyPI.

pip install nfoursid
INSTALL
IMPORT
SIG · NFOURSID
N
nfoursid
datapythonv1.0.2
Install
11.3s avg
Import
2966ms
Disk
255MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 3.045s · 252.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 11.3s · import 2.886s · 241MB
255MB installed
● package 255MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

NFourSID
from nfoursid.nfoursid import NFourSID
Kalman
from nfoursid.kalman import Kalman
StateSpace
from nfoursid.state_space import StateSpace

This quickstart demonstrates the core workflow of `nfoursid`: defining a true state-space model, simulating data, using the `NFourSID` class for system identification to recover a model from data, and then applying a `Kalman` filter for state estimation.

import numpy as np import pandas as pd from nfoursid.nfoursid import NFourSID from nfoursid.state_space import StateSpace from nfoursid.kalman import Kalman # 1. Define a state-space model (example parameters) A = np.array([[0.9, 0.1], [0, 0.9]]) B = np.array([[1], [0]]) C = np.array([[0.5, 0.5]]) D = np.array([[0]]) state_space_true = StateSpace(A, B, C, D) # 2. Simulate some data num_datapoints = 100 inputs = np.random.randn(num_datapoints, 1) * 0.1 # Small random inputs outputs = [] for i in range(num_datapoints): output_step = state_space_true.step(inputs[i].reshape(-1, 1), noise=np.random.randn(1, 1) * 0.05) outputs.append(output_step.flatten()) data = pd.DataFrame({ 'input_0': inputs.flatten(), 'output_0': np.array(outputs).flatten() }) # 3. Perform N4SID identification output_columns = ['output_0'] input_columns = ['input_0'] num_block_rows = 2 # See warnings regarding this parameter nfoursid_estimator = NFourSID( dataframe=data, output_columns=output_columns, input_columns=input_columns, num_block_rows=num_block_rows ) nfoursid_estimator.subspace_identification() # Essential before system_identification for proper order detection # Determine system order (e.g., from eigenvalue plot, assume 2 for this example) rank = 2 state_space_identified, covariance_matrix = nfoursid_estimator.system_identification(rank=rank) print("Identified State-Space A matrix:\n", state_space_identified.a) print("Identified State-Space C matrix:\n", state_space_identified.c) # 4. Use a Kalman filter for prediction/estimation kalman_filter = Kalman(state_space_identified, covariance_matrix) # Simulate a few steps with the Kalman filter filtered_outputs = [] for i in range(num_datapoints): kalman_filter.step(data[output_columns].iloc[i].values.reshape(-1,1), data[input_columns].iloc[i].values.reshape(-1,1)) filtered_outputs.append(kalman_filter.to_dataframe()['output_0']['filtered'].iloc[-1]) print("First 5 actual outputs:", data['output_0'].head().tolist()) print("First 5 filtered outputs:", filtered_outputs[:5])
Debug
Known issues
gotchaThe `num_block_rows` parameter in the `NFourSID` constructor significantly impacts both computational complexity and the ability to correctly determine the system order. Choosing it too large increases computation, while choosing it too small may prevent accurate order determination or violate theoretical assumptions.
fix
Experiment with `num_block_rows` values, typically starting with values related to expected system order and data length. Refer to subspace identification literature (e.g., the cited references [1] for guidance). The `plot_eigenvalues` method can help in assessing the choice.
affects: All versions
gotchaFor effective system order determination, it's generally recommended to call `nfoursid_estimator.subspace_identification()` before `nfoursid_estimator.system_identification()` and inspect the eigenvalues using `plot_eigenvalues`. Skipping `subspace_identification` might lead to an incorrect system order if the `rank` parameter is not chosen carefully in `system_identification`.
fix
Always perform `subspace_identification()` first, then analyze `nfoursid_estimator.plot_eigenvalues()` to visually confirm the appropriate `rank` before calling `system_identification(rank=...)`.
affects: All versions
gotchaThe `nfoursid` library assumes a foundational understanding of subspace identification, Kalman filtering, and state-space models. Users new to these concepts may struggle with model setup, parameter interpretation, and result validation, leading to potential misapplication.
fix
Familiarize yourself with the theoretical background of N4SID and Kalman filters (e.g., through the references provided in the documentation [1, 2]). Carefully review the example notebooks and documentation to understand how to correctly define models and interpret outputs.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nfoursid'
The 'nfoursid' library is not installed in your Python environment or the environment where your code is being run.
fix
pip install nfoursid
ValueError: The shapes of the matrices are inconsistent. Matrix A has shape (2, 2) but B has shape (2, 1) and expected (2, 2).
The input matrices (A, B, C, D) provided to the `StateSpace` constructor have incompatible dimensions, which violates the requirements for a valid state-space model.
fix
Ensure that the `A`, `B`, `C`, and `D` matrices adhere to the expected dimensions: `A` (dx, dx), `B` (dx, du), `C` (dy, dx), `D` (dy, du), where dx is the internal state dimension, du is the input dimension, and dy is the output dimension. For example, if `A` is `(dx, dx)`, then `B` must have `dx` rows, and `C` must have `dx` columns.
AttributeError: 'NFourSID' object has no attribute 'R32_decomposition'
You are attempting to access an attribute, such as `R32_decomposition` or call a method like `plot_eigenvalues` or `system_identification`, before the necessary `subspace_identification()` method has been called on the `NFourSID` object. The `R32_decomposition` is computed as a result of `subspace_identification` and is required for subsequent steps like plotting eigenvalues or performing system identification.
fix
Call the `subspace_identification()` method on your `NFourSID` object before attempting to access its results or dependent methods. Example: `nfoursid_instance.subspace_identification()` then `nfoursid_instance.plot_eigenvalues(ax)`.
Upgrade
Version history
1.0.2latest on PyPI · released Jul 24, 2025
Audit
Dependencies
numpyrequiredNumerical operations and array handling.
pandasrequiredDataframe manipulation for input/output.
matplotlibrequiredPlotting functionalities for analysis and visualization.
Agent activity
7 hits · last 30 days
node
6
Amazon
1
Resources
nfoursid — pip install nfoursid · libregistry