Getting Started with RobustNMF.jl

Installation

Install via the Julia package manager using the Git URL (since the package is not registered):

]
add https://github.com/TU-Julia-RobustNMF/RobustNMF.jl.git

Or using Pkg:

using Pkg
Pkg.add(url="https://github.com/TU-Julia-RobustNMF/RobustNMF.jl")
using RobustNMF

Requirements: Julia 1.11+ (see Project.toml)

Basic Usage

Import the package:

using RobustNMF

Your First Example

Perform robust non-negative matrix factorization with noisy data:

using Statistics  # For mean() function

# Generate synthetic non-negative data
X, W_true, H_true = generate_synthetic_data(50, 40; rank=6, seed=1)

# Add Gaussian noise (in-place)
add_gaussian_noise!(X; σ=0.2)

# Add sparse outliers (in-place)
add_sparse_outliers!(X; fraction=0.05, magnitude=5.0, seed=2)

# Normalize and rescale data to non-negative range
normalize_nonnegative!(X)

# Run standard NMF
W_nmf, H_nmf, history = nmf(X; rank=6, maxiter=500, tol=1e-4)

# Reconstruct the data matrix (X)
X_rec = W_nmf * H_nmf

# Run robust NMF
W_robust, H_robust, history_robust = robustnmf(X; rank=6, maxiter=500, tol=1e-3, seed=1)

# Compare reconstruction error (Mean Absolute Error)
mae_nmf = mean(abs.(X - W_nmf * H_nmf))
mae_robust = mean(abs.(X - W_robust * H_robust))
println("MAE Standard NMF: $mae_nmf")
println("MAE Robust NMF:   $mae_robust")

# Plot convergence of both runs
p_nmf = plot_convergence(history; objective=:frobenius, title="NMF Convergence")
p_rob = plot_convergence(history_robust; objective=:huber, title="Robust NMF Convergence")
display(p_nmf)
display(p_rob)

Important Notes

• All input data must be non-negative.
• Functions with a ! modify their input in-place (e.g., add_sparse_outliers!).
• The reconstructed matrix X_rec approximates the original data X.

When to Use What?

Next Steps

• Explore Examples - Practical workflows and use cases
• Check API Reference - Detailed function documentation