Usage¶

The powerlawrs package offers two primary ways to analyze your data: a simple functional API and a more detailed class-based API.

Functional API (Recommended)¶

The powerlawrs.fit() function is the most straightforward way to fit a power-law distribution to your data. See the Quickstart notebook for an example.

Python demo gif

import powerlawrs
import polars as pl

# 1. Load your data into a list, Polars Series, or numpy array
# The data should be a 1-dimensional array of numbers.
data = pl.read_csv("reference_data/blackouts.txt", has_header=True).to_series()

# 2. Fit the data:
p = powerlawrs.fit(data)

# 3. Print the ParetoFit object results:
print(p.ParetoFit)

Visualizing the Fit¶

After fitting the data, you can use the plot() method to visually inspect the fit.

# Assuming 'data' is loaded and fitted as above
p.plot()

This will generate two plots: one showing the CCDF of the full data with the scaled model, and another showing just the tail of the distribution.

plot demo png

Working with Other Distributions¶

powerlawrs also provides tools for other common distributions.

import powerlawrs

# Analyze a shifted exponential distribution
data = [1.2, 1.5, 1.9, 2.3, 2.8, 3.1, 3.5]
x_min = 1.0

# Estimate the lambda parameter
lambda_hat = powerlawrs.exponential.estimation.lambda_hat(data, x_min)
print(f"Estimated Lambda: {lambda_hat}")

# Create an exponential distribution object
exp_dist = powerlawrs.exponential.Exponential(lambda_hat, x_min)
print(f"PDF at x=2.0: {exp_dist.pdf(2.0)}")

Class-based API¶

Module Hierarchy¶

The powerlawrs package is structured hierarchically to organize its functionality logically and provide a clean API. The main submodules, accessible directly from import powerlawrs, are:

powerlawrs.dist: Contains implementations of various probability distributions (e.g., Pareto, Lognormal, Exponential) for fitting and analysis.
powerlawrs.stats: Provides statistical functions, including descriptive statistics, random number generation tools, and goodness-of-fit tests like the Kolmogorov-Smirnov (KS) test.
powerlawrs.util: Offers utility functions, such as data loading, parameter calculation for simulations, and synthetic data generation.

This structure allows for clear separation of concerns and easier navigation of the library’s features. For example, to access the KS test functions, you would typically import from powerlawrs.stats.ks.

For more fine-grained control, you can see the API examples in Notebooks/02 - API.ipynb.

Jupyter Notebook Examples¶

The `Notebooks folders provides a detailed walkthrough of the package’s functionalities. After installing the development dependencies, you can run it with:

# Make sure your virtual environment is active
source powerlaw/bin/activate

# Start Jupyter Lab
uv run --active jupyter lab