growl-reg 0.1.1__tar.gz

growl_reg-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matheus Lopes Carrijo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

growl_reg-0.1.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include examples *

growl_reg-0.1.1/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: growl_reg
+Version: 0.1.1
+Summary: GrOWL regression estimator with OWL, OSCAR, and Lasso variants
+Author: Matheus Lopes Carrijo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/matheuscarrijo/growl_reg
+Project-URL: Repository, https://github.com/matheuscarrijo/growl_reg
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: matplotlib>=3.0.0
+Dynamic: license-file
+
+[![PyPI version](https://img.shields.io/pypi/v/growl-reg)](https://pypi.org/project/growl-reg/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python >=3.8](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+
+# 🧮 Group Ordered Weighted $\ell_1$ (GrOWL) Norm
+
+This repository provides a Python implementation of the **Group Ordered Weighted
+ $\ell_1$ (GrOWL) Norm** regularization using the **Proximal Operator 
+ algorithm** and the **Fast Iterative Shrinkage-Thresholding Algorithm (FISTA)**. 
+ It solves the following general optimization problem:
+
+$$
+\min_{B} \frac{1}{2n} \lVert Y - XB \rVert_F^2 + 
+\sum_i w_i \space \lVert \beta\_{[i], \cdot}\rVert_2 \space, \quad \quad \quad (1)
+$$
+
+where  
+- $X \in \mathbb{R}^{n \times r}$ is the design matrix,  
+- $Y \in \mathbb{R}^{n \times p}$ is the matrix of response variables,  
+- $B \in \mathbb{R}^{r \times p}$ is the coefficient matrix to be estimated,  
+- $\beta\_{[i], \cdot}$ denotes the $i$-th largest row of $B$ in terms of 
+  its $\ell_2$-norm, and  
+- $w \in \mathbb{R}^r$ is a vector of non-negative, non-increasing weights.
+
+This regularizaton problem was introduced by Oswal et al. (2016) and it is a 
+multi-task ($p > 1$) version of the standard ($p=1$) Ordered Weighted 
+$\ell_1$ (OWL) Norm introduced independently by Zeng and Figueiredo (2014a) 
+and Bogdan et al. (2013). 
+
+Due to the non-smothness of the GrOWL penalty, a closed-form solution to this 
+problem is not available. However, the objective function remains convex, 
+allowing the use of efficient proximal optimization algorithms to reliably compute 
+the solution. Specifically, it is used the Proximal Gradient Method with 
+**Fast Iterative Shrinkage-Thresholding Algorithm (FISTA)** from Beck and 
+Teboulle (2009). Readers who are not familiar with proximal algorithms are referred 
+to Parikh and Boyd (2013).
+
+---
+
+---
+
+## 📐 Mathematical Background
+
+<!-- The standard ($p = 1$) Ordered Weighted $\ell_1$ (OWL) regularization
+problem can be written as
+
+$$
+\min_{\beta} \frac{1}{2n} \lVerty - X\beta
+Vert_2^2 + \sum_i w_i |\beta\_{[i]}|,
+$$
+
+where $w$ is as before but now we have $p=1$, and then $y := Y \in 
+\mathbb{R}^{n \times 1}$ and $\beta := B \in \mathbb{R}^{r \times 1}$,
+with $\beta\_{[i]}$ being the $i$-th largest component of $\beta$. -->
+
+Due to non-smothness of the penalty term in (1), this optimization problem 
+has no closed-form solution. Proximal operator algorithms is employed to solve
+it. The proximal operator of the GrOWL norm is given by
+
+$$
+\mathrm{prox}_G(V) = \mathrm{arg min}_B \space \frac{1}{2} \lVert B - V \rVert_F^2 + 
+\sum_i w_i \space \lVert \beta\_{[i], \cdot} \rVert_2.
+$$
+
+The proximal operator of GrOWL is solved in terms of the proximal operator of 
+the standard OWL (when $p=1$) norm, denoted by $\mathrm{prox}\_{\Omega_w}$. We thus 
+have the following result:
+
+---
+
+**Theorem 4 from Oswal et al. (2016).**  
+Let $\tilde{v}_i = \lVert v\_{i,\cdot}\rVert$ for $i = 1, ..., p$. Then 
+$\mathrm{prox}_G(V) = \hat{V}$, where the $i$-th row of $\hat{V}$ is given by
+
+$$
+\hat{\mathbf{v}}\_{i,\cdot} = 
+\left(\mathrm{prox}\_{\Omega_w}(\tilde{\mathbf{v}}) \right)_i \times
+\frac{\mathbf{v}\_{i,\cdot}}{\lVert \mathbf{v}\_{i,\cdot} \rVert}.
+$$
+
+---
+
+The formulation of $\mathrm{prox}\_{\Omega_w}$ is given in equation (24) of
+Zeng and Figueiredo (2014b):
+
+$$
+\mathrm{prox}\_{\Omega_w}(\mathbf{\tilde{v}}) = 
+\mathrm{sign}(\mathbf{\tilde{v}}) \odot \left( \mathbf{P}(|\mathbf{\tilde{v}}|)^T 
+\mathrm{proj}\_{\mathbb{R}\_+^n} \left( \mathrm{proj}\_{\mathcal{K}\_m} 
+(|\mathbf{\tilde{v}}|\_{\downarrow} - \mathbf{w}) \right) \right),
+$$
+
+where
+- $\mathrm{sign}(\mathbf{\tilde{v}})$ denotes the elementwise sign 
+  of vector $\mathbf{\tilde{v}}$.
+- $\odot$ is the Hadamard (elementwise) product.
+- $\mathbf{P}(|\mathbf{\tilde{v}}|)$ is the permutation matrix that 
+  sorts the absolute values $|\mathbf{\tilde{v}}|$ in non-increasing order,
+  i.e., $|\mathbf{v}|\_{\downarrow} = \mathbf{P}(|\mathbf{\tilde{v}}|) 
+  |\mathbf{\tilde{v}}|$.
+- $\mathrm{proj}\_{\mathcal{K}_m}$ is the Euclidean projection 
+  onto the monotone cone $\mathcal{K}\_m =$ {$\mathbf{x} 
+  \in \mathbb{R}^n : x_1 \geq x_2 \geq \cdots \geq x_n$}, 
+  implemented using the Pool Adjacent Violators (PAV) algorithm.
+- $\mathrm{proj}\_{\mathbb{R}_+^n}$ is the Euclidean projection
+  onto the nonnegative orthant, i.e., it replaces negative values by zero 
+  (clipping).
+- $\mathbf{w}$ is a weight vector satisfying $w_1 \geq w_2 \geq
+  \cdots \geq w_n \geq 0$.
+- $|\mathbf{\tilde{v}}|\_{\downarrow}$ denotes the absolute values of
+  $\mathbf{\tilde{v}}$ sorted in non-increasing order.
+
+We use **FISTA** (Beck and Teboulle, 2009), which is an accelerated first-order 
+method designed for problems of the form:
+
+$$
+\min_{B} f(B) + g(B),
+$$
+
+where $f$ is convex and differentiable with Lipschitz continuous gradient, 
+and $g$ is convex (possibly non-smooth) with a proximal operator that can be 
+computed efficiently.
+
+In our case:
+- $f(B) := \frac{1}{2n} \lVert Y - XB \rVert_2^2$ is the smooth loss,
+- $g(B) := \sum_i w_i \space \lVert \beta\_{[i], \cdot}\rVert_2$ is the GrOWL
+  penalty.
+
+FISTA proceeds by alternating between gradient descent steps on $f$ and proximal 
+steps on $g$, with a Nesterov-type momentum update to accelerate convergence. Each
+iteration consists of:
+
+1. **Gradient step:**
+
+$$
+V^{(k)} = Z^{(k)} - \frac{1}{L} \nabla f(Z^{(k)}),
+$$
+
+where $L$ is the Lipschitz constant of $\nabla f$, computed as 
+$L = \lVert X \rVert_2^2/n$, where $\lVert X \rVert_2$ denotes the spectral norm of the matrix $X$.
+
+2. **Proximal step using the GrOWL operator:**
+
+$$
+B^{(k+1)} = \mathrm{prox}_G (V^{(k)}),
+$$
+
+which is implemented as described earlier, using the Pool Adjacent Violators (PAV) 
+algorithm for isotonic regression and restoring the original signs and order.
+
+3. **Nesterov momentum step:**
+
+$$
+t_{k+1} = \frac{1}{2} \left(1 + \sqrt{1 + 4t_k^2} \right), \quad
+Z^{(k+1)} = B^{(k+1)} + \left( \frac{t_k - 1}{t_{k+1}} \right) (B^{(k+1)} - B^{(k)}).
+$$
+
+The algorithm continues until convergence is detected, based on one of three 
+user-defined stopping criteria:
+- Absolute change in objective value,
+- Relative change in objective value,
+- Frobenius norm of the difference between successive iterates.
+
+This FISTA procedure is implemented in the function `growl_fista()` inside the file 
+'fista_solver.py' in the codebase. The function handles flexible weight vector definitions 
+(manual or parameterized via `lambda_1`,  `lambda_2`, and `ramp_size`) and returns the 
+estimated coefficient matrix along with the cost history. 
+
+The proximal operators evaluations are implemented in the functions 'prox_owl()' and
+'prox_growl()' inside the file 'prox_operator.py'.
+
+---
+
+---
+
+## 🗂 Repository Structure
+
+Below are the important modules in this project and their functionalities:
+
+1. **`__init__.py`**  
+   This file is part of the `growl/` module and exposes the `GrowlRegressor` class
+   as the main interface for the package. It enables clean imports such as:
+   
+   ```python
+   from growl import GrowlRegressor
+   ```
+
+3. **`base.py`**  
+   Contains the main class `GrowlRegressor`, a `scikit-learn` compatible estimator that
+   implements GrOWL regression. This class provides:
+   
+   - `.fit(X, Y)` to estimate coefficients using the GrOWL penalty
+   - `.predict(X)` for in-sample or out-of-sample predictions
+   - Integration with `GridSearchCV`
+   - Optional centering of `X` and `Y` when `fit_intercept=True`
+   - Storage of the coefficient matrix `coef_` and optimization history `cost_history_`
+
+5. **`prox_operator.py`**  
+   Implements proximal operators required for optimization:
+   - `prox_owl(v, w)`: Evaluate the proximal operator for the OWL penalty.
+   - `prox_growl(V, w)`: Evaluate the proximal operator for the GrOWL penalty.
+
+6. **`fista_solver.py`**  
+   Implements the FISTA-based optimization routine used to solve the GrOWL regularized
+   least-squares problem. This module includes:
+   
+   - `growl_fista(...)`: A solver using Nesterov’s acceleration
+   - Weight vector construction based on `lambda_1`, `lambda_2`, and `ramp_size`
+   - Convergence monitoring based on cost, relative cost, or solution change
+   - Optional scaling of the objective function to improve numerical stability
+
+8. **`growl_example.py`**  
+   Located in the `examples/` folder, this script demonstrates the usage of
+   the `GrowlRegressor`:
+   
+   - Grid search over hyperparameters (`lambda_1`, `lambda_2`, `ramp_size`)
+   - Visual comparisons between:
+     - True vs estimated coefficients
+     - GrOWL vs MultiTaskLasso (for pooled regression)
+     - GrOWL (OWL style) vs Lasso (for standard regression)
+   - Plots showing grouping behavior and coefficient shrinkage
+
+   To run the example, use:
+   ```bash
+   python examples/growl_example.py
+   ```
+
+---
+
+---
+
+## ⚙️ Setup
+
+**Install the repository:**
+
+   ```bash
+   pip install growl_reg
+   ```
+
+---
+
+---
+
+## 📚 References
+
+Beck, A. and Teboulle, M. "A fast iterative shrinkage-thresholding algorithm
+for linear inverse problems", _SIAM Journal on Imaging Sciences, vol. 2, no. 1,
+pp. 183–202_, 2009.
+
+Bogdan, J., Berg, E., Su, W. and Candes, E. "Statistical 
+estimation and testing via the ordered $\ell_1$ norm", arXiv preprint 
+[arxiv:1310.1969v2](https://arxiv.org/abs/1310.1969) 2013.
+
+Oswal, U., Cox, C., Ralph, M. A. L., and Rogers, T., Nowak, R., 2016. 
+"Representational Similarity Learning with Application to Brain Networks". 
+_Proceedings of the 33 rd International Conference on Machine Learning, 
+New York, NY, USA, 2016. JMLR: W\&CP volume 48_.
+
+Parikh, Neal and Boyd, Stephen. "Proximal algorithms". _Foundations and Trends
+in optimization_, 1(3):123–231, 2013.
+
+Zeng, X. and Figueiredo, M, 2014a. "Decreasing Weighted Sorted $\ell_1$ 
+Regularization". arXiv preprint 
+[arXiv:1404.3184v1](https://arxiv.org/abs/1404.3184), 2014.
+
+Zeng, X. and Figueiredo, M, 2014b. "The ordered weighted $\ell_1$ norm - atomic 
+formulation, projections, and Algorithms". arXiv preprint 
+[arXiv:1409.4271v5](https://arxiv.org/abs/1409.4271), 2014.
+
+---
+
+## 📑 Citation
+
+If you use `growl_reg` in your work, please cite it as:
+
+Matheus Lopes Carrijo. "GrOWL Regression Estimator (Python package)." 2025. 
+Available at: https://github.com/matheuscarrijo/growl_reg
+
+
+Or use the following BibTeX entry:
+
+```bibtex
+@misc{carrijo2025growl,
+  author       = {Carrijo, M. L.},
+  title        = {GrOWL Regression Estimator (Python Package)},
+  year         = {2025},
+  howpublished = {https://github.com/matheuscarrijo/growl_reg},
+  note         = {Version 0.1.1}
+}
+```
+

growl_reg-0.1.1/README.md

@@ -0,0 +1,291 @@
+[![PyPI version](https://img.shields.io/pypi/v/growl-reg)](https://pypi.org/project/growl-reg/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python >=3.8](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+
+# 🧮 Group Ordered Weighted $\ell_1$ (GrOWL) Norm
+
+This repository provides a Python implementation of the **Group Ordered Weighted
+ $\ell_1$ (GrOWL) Norm** regularization using the **Proximal Operator 
+ algorithm** and the **Fast Iterative Shrinkage-Thresholding Algorithm (FISTA)**. 
+ It solves the following general optimization problem:
+
+$$
+\min_{B} \frac{1}{2n} \lVert Y - XB \rVert_F^2 + 
+\sum_i w_i \space \lVert \beta\_{[i], \cdot}\rVert_2 \space, \quad \quad \quad (1)
+$$
+
+where  
+- $X \in \mathbb{R}^{n \times r}$ is the design matrix,  
+- $Y \in \mathbb{R}^{n \times p}$ is the matrix of response variables,  
+- $B \in \mathbb{R}^{r \times p}$ is the coefficient matrix to be estimated,  
+- $\beta\_{[i], \cdot}$ denotes the $i$-th largest row of $B$ in terms of 
+  its $\ell_2$-norm, and  
+- $w \in \mathbb{R}^r$ is a vector of non-negative, non-increasing weights.
+
+This regularizaton problem was introduced by Oswal et al. (2016) and it is a 
+multi-task ($p > 1$) version of the standard ($p=1$) Ordered Weighted 
+$\ell_1$ (OWL) Norm introduced independently by Zeng and Figueiredo (2014a) 
+and Bogdan et al. (2013). 
+
+Due to the non-smothness of the GrOWL penalty, a closed-form solution to this 
+problem is not available. However, the objective function remains convex, 
+allowing the use of efficient proximal optimization algorithms to reliably compute 
+the solution. Specifically, it is used the Proximal Gradient Method with 
+**Fast Iterative Shrinkage-Thresholding Algorithm (FISTA)** from Beck and 
+Teboulle (2009). Readers who are not familiar with proximal algorithms are referred 
+to Parikh and Boyd (2013).
+
+---
+
+---
+
+## 📐 Mathematical Background
+
+<!-- The standard ($p = 1$) Ordered Weighted $\ell_1$ (OWL) regularization
+problem can be written as
+
+$$
+\min_{\beta} \frac{1}{2n} \lVerty - X\beta
+Vert_2^2 + \sum_i w_i |\beta\_{[i]}|,
+$$
+
+where $w$ is as before but now we have $p=1$, and then $y := Y \in 
+\mathbb{R}^{n \times 1}$ and $\beta := B \in \mathbb{R}^{r \times 1}$,
+with $\beta\_{[i]}$ being the $i$-th largest component of $\beta$. -->
+
+Due to non-smothness of the penalty term in (1), this optimization problem 
+has no closed-form solution. Proximal operator algorithms is employed to solve
+it. The proximal operator of the GrOWL norm is given by
+
+$$
+\mathrm{prox}_G(V) = \mathrm{arg min}_B \space \frac{1}{2} \lVert B - V \rVert_F^2 + 
+\sum_i w_i \space \lVert \beta\_{[i], \cdot} \rVert_2.
+$$
+
+The proximal operator of GrOWL is solved in terms of the proximal operator of 
+the standard OWL (when $p=1$) norm, denoted by $\mathrm{prox}\_{\Omega_w}$. We thus 
+have the following result:
+
+---
+
+**Theorem 4 from Oswal et al. (2016).**  
+Let $\tilde{v}_i = \lVert v\_{i,\cdot}\rVert$ for $i = 1, ..., p$. Then 
+$\mathrm{prox}_G(V) = \hat{V}$, where the $i$-th row of $\hat{V}$ is given by
+
+$$
+\hat{\mathbf{v}}\_{i,\cdot} = 
+\left(\mathrm{prox}\_{\Omega_w}(\tilde{\mathbf{v}}) \right)_i \times
+\frac{\mathbf{v}\_{i,\cdot}}{\lVert \mathbf{v}\_{i,\cdot} \rVert}.
+$$
+
+---
+
+The formulation of $\mathrm{prox}\_{\Omega_w}$ is given in equation (24) of
+Zeng and Figueiredo (2014b):
+
+$$
+\mathrm{prox}\_{\Omega_w}(\mathbf{\tilde{v}}) = 
+\mathrm{sign}(\mathbf{\tilde{v}}) \odot \left( \mathbf{P}(|\mathbf{\tilde{v}}|)^T 
+\mathrm{proj}\_{\mathbb{R}\_+^n} \left( \mathrm{proj}\_{\mathcal{K}\_m} 
+(|\mathbf{\tilde{v}}|\_{\downarrow} - \mathbf{w}) \right) \right),
+$$
+
+where
+- $\mathrm{sign}(\mathbf{\tilde{v}})$ denotes the elementwise sign 
+  of vector $\mathbf{\tilde{v}}$.
+- $\odot$ is the Hadamard (elementwise) product.
+- $\mathbf{P}(|\mathbf{\tilde{v}}|)$ is the permutation matrix that 
+  sorts the absolute values $|\mathbf{\tilde{v}}|$ in non-increasing order,
+  i.e., $|\mathbf{v}|\_{\downarrow} = \mathbf{P}(|\mathbf{\tilde{v}}|) 
+  |\mathbf{\tilde{v}}|$.
+- $\mathrm{proj}\_{\mathcal{K}_m}$ is the Euclidean projection 
+  onto the monotone cone $\mathcal{K}\_m =$ {$\mathbf{x} 
+  \in \mathbb{R}^n : x_1 \geq x_2 \geq \cdots \geq x_n$}, 
+  implemented using the Pool Adjacent Violators (PAV) algorithm.
+- $\mathrm{proj}\_{\mathbb{R}_+^n}$ is the Euclidean projection
+  onto the nonnegative orthant, i.e., it replaces negative values by zero 
+  (clipping).
+- $\mathbf{w}$ is a weight vector satisfying $w_1 \geq w_2 \geq
+  \cdots \geq w_n \geq 0$.
+- $|\mathbf{\tilde{v}}|\_{\downarrow}$ denotes the absolute values of
+  $\mathbf{\tilde{v}}$ sorted in non-increasing order.
+
+We use **FISTA** (Beck and Teboulle, 2009), which is an accelerated first-order 
+method designed for problems of the form:
+
+$$
+\min_{B} f(B) + g(B),
+$$
+
+where $f$ is convex and differentiable with Lipschitz continuous gradient, 
+and $g$ is convex (possibly non-smooth) with a proximal operator that can be 
+computed efficiently.
+
+In our case:
+- $f(B) := \frac{1}{2n} \lVert Y - XB \rVert_2^2$ is the smooth loss,
+- $g(B) := \sum_i w_i \space \lVert \beta\_{[i], \cdot}\rVert_2$ is the GrOWL
+  penalty.
+
+FISTA proceeds by alternating between gradient descent steps on $f$ and proximal 
+steps on $g$, with a Nesterov-type momentum update to accelerate convergence. Each
+iteration consists of:
+
+1. **Gradient step:**
+
+$$
+V^{(k)} = Z^{(k)} - \frac{1}{L} \nabla f(Z^{(k)}),
+$$
+
+where $L$ is the Lipschitz constant of $\nabla f$, computed as 
+$L = \lVert X \rVert_2^2/n$, where $\lVert X \rVert_2$ denotes the spectral norm of the matrix $X$.
+
+2. **Proximal step using the GrOWL operator:**
+
+$$
+B^{(k+1)} = \mathrm{prox}_G (V^{(k)}),
+$$
+
+which is implemented as described earlier, using the Pool Adjacent Violators (PAV) 
+algorithm for isotonic regression and restoring the original signs and order.
+
+3. **Nesterov momentum step:**
+
+$$
+t_{k+1} = \frac{1}{2} \left(1 + \sqrt{1 + 4t_k^2} \right), \quad
+Z^{(k+1)} = B^{(k+1)} + \left( \frac{t_k - 1}{t_{k+1}} \right) (B^{(k+1)} - B^{(k)}).
+$$
+
+The algorithm continues until convergence is detected, based on one of three 
+user-defined stopping criteria:
+- Absolute change in objective value,
+- Relative change in objective value,
+- Frobenius norm of the difference between successive iterates.
+
+This FISTA procedure is implemented in the function `growl_fista()` inside the file 
+'fista_solver.py' in the codebase. The function handles flexible weight vector definitions 
+(manual or parameterized via `lambda_1`,  `lambda_2`, and `ramp_size`) and returns the 
+estimated coefficient matrix along with the cost history. 
+
+The proximal operators evaluations are implemented in the functions 'prox_owl()' and
+'prox_growl()' inside the file 'prox_operator.py'.
+
+---
+
+---
+
+## 🗂 Repository Structure
+
+Below are the important modules in this project and their functionalities:
+
+1. **`__init__.py`**  
+   This file is part of the `growl/` module and exposes the `GrowlRegressor` class
+   as the main interface for the package. It enables clean imports such as:
+   
+   ```python
+   from growl import GrowlRegressor
+   ```
+
+3. **`base.py`**  
+   Contains the main class `GrowlRegressor`, a `scikit-learn` compatible estimator that
+   implements GrOWL regression. This class provides:
+   
+   - `.fit(X, Y)` to estimate coefficients using the GrOWL penalty
+   - `.predict(X)` for in-sample or out-of-sample predictions
+   - Integration with `GridSearchCV`
+   - Optional centering of `X` and `Y` when `fit_intercept=True`
+   - Storage of the coefficient matrix `coef_` and optimization history `cost_history_`
+
+5. **`prox_operator.py`**  
+   Implements proximal operators required for optimization:
+   - `prox_owl(v, w)`: Evaluate the proximal operator for the OWL penalty.
+   - `prox_growl(V, w)`: Evaluate the proximal operator for the GrOWL penalty.
+
+6. **`fista_solver.py`**  
+   Implements the FISTA-based optimization routine used to solve the GrOWL regularized
+   least-squares problem. This module includes:
+   
+   - `growl_fista(...)`: A solver using Nesterov’s acceleration
+   - Weight vector construction based on `lambda_1`, `lambda_2`, and `ramp_size`
+   - Convergence monitoring based on cost, relative cost, or solution change
+   - Optional scaling of the objective function to improve numerical stability
+
+8. **`growl_example.py`**  
+   Located in the `examples/` folder, this script demonstrates the usage of
+   the `GrowlRegressor`:
+   
+   - Grid search over hyperparameters (`lambda_1`, `lambda_2`, `ramp_size`)
+   - Visual comparisons between:
+     - True vs estimated coefficients
+     - GrOWL vs MultiTaskLasso (for pooled regression)
+     - GrOWL (OWL style) vs Lasso (for standard regression)
+   - Plots showing grouping behavior and coefficient shrinkage
+
+   To run the example, use:
+   ```bash
+   python examples/growl_example.py
+   ```
+
+---
+
+---
+
+## ⚙️ Setup
+
+**Install the repository:**
+
+   ```bash
+   pip install growl_reg
+   ```
+
+---
+
+---
+
+## 📚 References
+
+Beck, A. and Teboulle, M. "A fast iterative shrinkage-thresholding algorithm
+for linear inverse problems", _SIAM Journal on Imaging Sciences, vol. 2, no. 1,
+pp. 183–202_, 2009.
+
+Bogdan, J., Berg, E., Su, W. and Candes, E. "Statistical 
+estimation and testing via the ordered $\ell_1$ norm", arXiv preprint 
+[arxiv:1310.1969v2](https://arxiv.org/abs/1310.1969) 2013.
+
+Oswal, U., Cox, C., Ralph, M. A. L., and Rogers, T., Nowak, R., 2016. 
+"Representational Similarity Learning with Application to Brain Networks". 
+_Proceedings of the 33 rd International Conference on Machine Learning, 
+New York, NY, USA, 2016. JMLR: W\&CP volume 48_.
+
+Parikh, Neal and Boyd, Stephen. "Proximal algorithms". _Foundations and Trends
+in optimization_, 1(3):123–231, 2013.
+
+Zeng, X. and Figueiredo, M, 2014a. "Decreasing Weighted Sorted $\ell_1$ 
+Regularization". arXiv preprint 
+[arXiv:1404.3184v1](https://arxiv.org/abs/1404.3184), 2014.
+
+Zeng, X. and Figueiredo, M, 2014b. "The ordered weighted $\ell_1$ norm - atomic 
+formulation, projections, and Algorithms". arXiv preprint 
+[arXiv:1409.4271v5](https://arxiv.org/abs/1409.4271), 2014.
+
+---
+
+## 📑 Citation
+
+If you use `growl_reg` in your work, please cite it as:
+
+Matheus Lopes Carrijo. "GrOWL Regression Estimator (Python package)." 2025. 
+Available at: https://github.com/matheuscarrijo/growl_reg
+
+
+Or use the following BibTeX entry:
+
+```bibtex
+@misc{carrijo2025growl,
+  author       = {Carrijo, M. L.},
+  title        = {GrOWL Regression Estimator (Python Package)},
+  year         = {2025},
+  howpublished = {https://github.com/matheuscarrijo/growl_reg},
+  note         = {Version 0.1.1}
+}
+```
+