### Install powerlaw using pip

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/index.md

Installs the powerlaw package from PyPi using pip. Ensure you have pip installed.

```console
$ pip install powerlaw
```

--------------------------------

### Install powerlaw from source

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/index.md

Installs the powerlaw package directly from its source code repository. This involves cloning the repository and then installing it using pip.

```console
$ git clone https://github.com/powerlaw-devs/powerlaw
$ cd powerlaw
$ pip install .
```

--------------------------------

### Install Powerlaw from Source

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/README.rst

Install the powerlaw package directly from its source code repository. This is useful for development or when using the latest unreleased version.

```console
$ git clone https://github.com/jeffalstott/powerlaw
$ cd powerlaw
$ pip install .
```

--------------------------------

### Provide Initial Parameters for Noisy Fits

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/advanced_topics.md

If fitting is problematic due to a noisy landscape, provide an explicit initial condition using the `initial_parameters` argument to guide the fitting process.

```python
fit = powerlaw.Fit(data, initial_parameters={\"alpha\": 2.4})
```

--------------------------------

### Load Test Dataset and Initialize Power Law

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Loads a test dataset and initializes a Power_Law object. This is a common starting point for fitting power-law distributions.

```python
data = powerlaw.load_test_dataset('blackouts')

pl = powerlaw.Power_Law(data)
```

--------------------------------

### Create Constraint Dictionary

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Construct a dictionary to define the constraint type, the constraint function, and the distributions to which it applies. This example sets up an inequality constraint for 'power_law' distributions.

```python
constraint_dict = {"type": 'ineq',
                   "fun": constraint,
                   "dists": ['power_law']}
```

--------------------------------

### Saving Fits with complex constraints

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Shows an example of saving a `Fit` object that includes a constraint function. It highlights potential issues with external dependencies when loading the fit.

```python
import powerlaw
import numpy as np

data = np.genfromtxt('data.txt')

def constraint(dist):
    """
    Some constraint that depends on the library numpy
    """
    E = np.exp(...)
    ...

constraint_dict = {"type": 'eq',
                   "fun": constraint}

fit = powerlaw.Fit(data, parameter_constraints=constraint_dict)

fit.save('output.h5')
```

--------------------------------

### Example Constraint: Scale > Exponent

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Illustrate defining a constraint where the exponential scale parameter (Lamda) must be larger than the power law exponent (alpha). This demonstrates how to create constraints involving multiple distribution parameters.

```python
def constraint(dist):
    """
    Require that the exponential scale is larger than the power law
    exponent (doesn't really make sense, but just to illustrate).
    """
    return dist.Lamda - dist.alpha
```

--------------------------------

### Custom Cost Function Example

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/other_libraries.md

An example of a custom cost function used for fitting. This function calculates the distance between the actual PDF and the fitted function.

```python
def cost_function(p):
    return distance_function(pdf(y) - fit_function(p))
```

--------------------------------

### Plotting PDF with powerlaw

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/index.md

Generates a plot of the Probability Density Function (PDF) for the data and its fitted power law, using matplotlib. Ensure matplotlib is installed and imported.

```python
import matplotlib.pyplot as plt
fig, ax = plt.subplots()

fit.plot_pdf(ax=ax, label='PDF')
fit.power_law.plot_pdf(ax=ax, label='Power law fit')

plt.legend()
plt.show()
```

--------------------------------

### Fit Discrete Data and Prepare for Comparison

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Load a discrete dataset and initialize the Fit object with `discrete=True`. This prepares the data for subsequent distribution comparisons.

```python
data = powerlaw.load_test_dataset('word')

# Remember this is a discrete dataset
fit = powerlaw.Fit(data, discrete=True)

...
```

--------------------------------

### Plotting with $x_{min}$ and $x_{max}$

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/scaling_range.md

Demonstrates plotting both the cropped PDF (using $x_{min}$ and $x_{max}$) and the full PDF (using all original data) for comparison.

```python
xmin = 10
xmax = 1e4

fit = powerlaw.Fit(data, xmin=xmin, xmax=xmax)

fit.plot_pdf(label='Cropped PDF')
fit.plot_pdf(original_data=True, label='Full PDF')

...
```

--------------------------------

### Creating Multi-Extension FITS Files

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Demonstrates the creation of a FITS file containing multiple extensions, such as images and tables. Each extension can hold different types of data.

```python
import numpy as np
from astropy.io import fits

# Create primary data (e.g., an image)
image_data = np.random.rand(20, 20)
primary_hdu = fits.PrimaryHDU(image_data)

# Create table data
col1 = fits.Column(name='ID', format='J', array=np.arange(5))
col2 = fits.Column(name='Value', format='E', array=np.random.rand(5))

columns = fits.ColDefs([col1, col2])
table_hdu = fits.BinTableHDU.from_columns(columns)

# Create an HDUList and append the HDUs
hdul = fits.HDUList([primary_hdu, table_hdu])

# Save the multi-extension FITS file
hdul.writeto('multi_extension.fits', overwrite=True)
```

--------------------------------

### Define Parameter Initialization

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/new_distributions.md

Implement the `generate_initial_parameters` method to provide initial parameter values based on the input data.

```python
class NewDistribution(Distribution):

    ...

    def generate_initial_parameters(self, data):
        """
        Generate initial values for parameters based on the provided
        data.
        """
        params = {}

        # For example, for an exponential:
        # params["Lambda"] = 1 / np.mean(data)

        return params
```

--------------------------------

### Specify Fit object save format

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Demonstrates how to explicitly specify the file format (HDF5 or pickle) when saving a `Fit` object, either by file extension or using the `format` keyword.

```python
fit.save('output.h5') # saves in hdf5 format
fit.save('output', format='h5') # saves in hdf5 format
fit.save('output.pkl') # saves in pickle format
fit.save('output', format='pkl') # saves in pickle format
```

--------------------------------

### Define Inequality Constraint Function

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Implement a constraint function that takes a distribution object and returns a value. For inequality constraints, the function should return a positive value when the constraint is satisfied and zero or negative otherwise. This example ensures at least N points remain in the distribution's domain.

```python
def constraint(dist):
    # Some value
    N = 100

    # Note that dist.data property is already cropped from xmin to
    # xmax, so its length is a true measure of the points in the range.
    return len(dist.data) - N
```

--------------------------------

### Plot Original and Sampled PDF

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Compare the PDF of the original power-law distribution with the PDF of the generated random samples.

```python
pl.plot_pdf(label='Original PDF')
powerlaw.plot_pdf(samples, label='Sampled PDF')
```

--------------------------------

### Analyze Multiple Possible Fits with xmin_fitting_results

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/advanced_topics.md

Examine the `xmin_fitting_results` property to understand alternative fits. This property stores information on all possible xmin values and their corresponding fit parameters, useful when multiple local minima exist in the distance metric.

```python
data = powerlaw.load_test_dataset('blackouts')

fit = powerlaw.Fit(data / 1e3)

# Now examine the xmin fitting results
plt.plot(fit.xmin_fitting_results["xmin"], fit.xmin_fitting_results["distance"])
```

--------------------------------

### Generate Bounded Random Samples

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Create a power-law distribution with a specified xmax and generate random samples within the [xmin, xmax] range.

```python
pl = powerlaw.Power_Law(xmin=1, xmax=1e5, alpha=2.0)
samples = pl.generate_random((10000,))
```

--------------------------------

### Implement Core Distribution Functions

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/new_distributions.md

Define the unnormalized PDF, CDF, and normalization constants for the distribution. These methods should access parameters directly from `self`.

```python
class NewDistribution(Distribution):

    ...

    def _pdf_base_function(self, x):
        """
        The (unnormalized) PDF.
        """
        # For example, for an exponential:
        # return np.exp(-self.Lambda * x)

    def _cdf_base_function(self, x):
        """
        The (unnormalized) CDF.
        """
        # For example, for an exponential:
        # return 1 - np.exp(-self.Lambda * x)

    @property
    def _pdf_continuous_normalizer(self):
        """
        Normalization constant :math:`A` for the continuous PDF such
        that :math:`p(x) = A q(x)` where :math:`p` is the proper
        PDF and :math:`q` is the base function.
        """
        # For example, for an exponential:
        # return self.Lambda * np.exp(self.Lambda * self.xmin)

    @property
    def _pdf_discrete_normalizer(self):
        """
        Normalization constant :math:`A` for the discrete PDF such
        that :math:`p(x) = A q(x)` where :math:`p` is the proper
        PDF and :math:`q` is the base function.

        If no exact expression exists for this, you can remove this
        function.
        """
```

--------------------------------

### Checking Initial Conditions for Fit Failures

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/warnings.md

If `Distribution.fit()` fails to find valid parameters, examine the `initial_condition` attribute. This can help diagnose issues related to parameter constraints or unreasonable initial guesses.

```python
import powerlaw

# Assuming 'data' is defined and causes the warning
# fit = powerlaw.Fit(data, ...)
# print(fit.<dist_name>.initial_condition)

# Or directly from a distribution
# dist = powerlaw.Power_Law(data, ...)
# print(dist.initial_condition)
```

--------------------------------

### Loading a cached Fit object

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Illustrates how a `Fit` object is loaded from the cache in a new session if the data and fitting parameters are identical to a previously cached fit.

```python
# In another session

powerlaw.Fit.set_cache_folder('data/')

# The same data as before
data = np.genfromtxt('data.txt')

# This will just load the previously cached file
fit = powerlaw.Fit(data)
```

--------------------------------

### Find $x_{min}$ with Progress Bar

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/scaling_range.md

To monitor the progress of the computationally intensive `find_xmin()` method, set `verbose=2` when creating the `Fit` instance.

```python
# This will use find_xmin() to get the best value for xmin and
# show a progress bar.
fit = powerlaw.Fit(data, verbose=2)
```

--------------------------------

### Compare Power Law and Exponential Fits

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Load data, fit a power law, and compare its fit against an exponential distribution using loglikelihood ratios. This is useful for determining if a dataset is truly heavy-tailed.

```python
data = powerlaw.load_test_dataset('blackouts')

fit = powerlaw.Fit(data)

# Plot the data and two candidate distributions
fit.plot_pdf(label='Data')
fit.power_law.plot_pdf(label='Power law fit')
fit.exponential.plot_pdf(label='Exponential fit')

... 

# See which distribution fits the data better
R, p = fit.distribution_compare('power_law', 'exponential',
                                normalized_ratio=True)

print(R, p)
```

--------------------------------

### Generate Samples from Fitted Distribution

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Fit a power-law distribution to existing data and then generate random samples from the fitted distribution. Note that if xmax is not provided during fitting, samples will be unbounded.

```python
data = powerlaw.load_test_dataset('flares')
pl = powerlaw.Fit(data)
samples = pl.generate_random((10000,))
```

--------------------------------

### Plotting PDF with Linear Bins

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/visualization.md

Visualize the PDF of a dataset using linearly spaced bins. This can be useful for comparison but may suffer from sparsity in the tails of heavy-tailed distributions.

```python
data = powerlaw.load_test_dataset('blackouts')

#powerlaw.plot_pdf(data, linear_bins=False, label='PDF')
powerlaw.plot_pdf(data, linear_bins=True, label='PDF')
plt.legend()
plt.show()
```

--------------------------------

### Generate Random Samples from Distribution

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Generate random samples from a power-law distribution. The size of the sample is specified as a tuple.

```python
samples = pl.generate_random((10000,))
```

--------------------------------

### Loading Fits with complex constraints

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Illustrates the potential error when loading a `Fit` object with complex constraints in a new session if the necessary libraries (like numpy) are not imported.

```python
# In another session

import powerlaw
# numpy is *not* imported

fit = powerlaw.Fit.load('output.h5')

constraint = fit.parameter_constraints[0]["fun"]

# This will give an error that the function can't find numpy since we
# haven't imported it.
constraint(...)
```

--------------------------------

### Calculate Log-Likelihood Ratio for Distributions

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Compares two distributions (Power Law and Exponential) by calculating their log-likelihood ratio. This is useful for determining which distribution better fits the data. Ensure data is loaded and distributions are instantiated before use.

```python
data = powerlaw.load_test_dataset('fires')

loglikelihoods_pl = powerlaw.Power_Law(data=data).loglikelihoods()
loglikelihoods_exp = powerlaw.Exponential(data=data).loglikelihoods()

powerlaw.loglikelihood_ratio(loglikelihoods_pl, loglikelihoods_exp, nested=False)
```

--------------------------------

### Saving Data to a FITS File

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Demonstrates how to save a NumPy array to a FITS file. Ensure the numpy library is imported.

```python
import numpy as np
from astropy.io import fits

# Create some sample data
data = np.random.rand(10, 10)

# Create a new FITS file
hdu = fits.PrimaryHDU(data)

# Save the FITS file
hdu.writeto('my_data.fits', overwrite=True)
```

--------------------------------

### Load and Fit Continuous vs. Discrete Data

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/discrete_continuous.md

Load a dataset and fit it using powerlaw. Specify 'discrete=True' for discrete (integer) datasets.

```python
# This is a continuous dataset
data = powerlaw.load_test_dataset('quakes')
fit = powerlaw.Fit(data)

# This is a discrete dataset, so we should specify that
data = powerlaw.load_test_dataset('words')
fit = powerlaw.Fit(data, discrete=True)
```

--------------------------------

### Load a Fit object from a file

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Loads a previously saved `Fit` object from a file. This allows you to resume your work without recalculating parameters.

```python
# In another session

fit = powerlaw.Fit.load('output.h5')

fit.plot_pdf()
...
```

--------------------------------

### Cache miss due to different parameters

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Demonstrates a cache miss scenario where a `Fit` object is not loaded from the cache because the fitting parameters (e.g., `xmin`) differ from the cached version.

```python
# In another session

# The same data as before
data = np.genfromtxt('data.txt')

# This will *not* load the previously cached file since xmin is different
fit = powerlaw.Fit(data, xmin=1)
```

--------------------------------

### Compare Power Law and Exponential Distributions

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Compares the 'power_law' distribution against the 'exponential' distribution. Set `normalized_ratio=True` for a normalized likelihood ratio. Prints the R and p values.

```python
R, p = fit.distribution_compare('power_law', 'exponential',
                                normalized_ratio=True)

print(R, p)
```

--------------------------------

### Appending Data to an Existing FITS File

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Shows how to append new data as an extension to an existing FITS file. This is useful for adding more information without overwriting previous data.

```python
import numpy as np
from astropy.io import fits

# Create some sample data for the extension
new_data = np.random.rand(5, 5)

# Open the existing FITS file in append mode
with fits.open('my_data.fits', mode='append') as hdul:
    # Create a new HDU for the new data
    new_hdu = fits.ImageHDU(new_data)
    # Append the new HDU
    hdul.append(new_hdu)
    # Save the changes
    hdul.flush()
```

--------------------------------

### Create Power Law Distribution

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Manually specify parameters to create a power-law distribution. Accepts alpha as a dictionary value, a list, or a keyword argument.

```python
pl = powerlaw.Power_Law(xmin=1, parameters={'alpha': 2.0})
pl = powerlaw.Power_Law(xmin=1, parameters=[2.0])
pl = powerlaw.Power_Law(xmin=1, alpha=2.0)
```

--------------------------------

### Fit Powerlaw Distribution With Constraints

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Load a dataset and perform a powerlaw fit after applying custom constraints defined in a dictionary. This demonstrates how constraints modify the fitting process.

```python
data = powerlaw.load_test_dataset('blackouts')

# Assuming constraint_dict is defined as shown previously
# fit = powerlaw.Fit(data / 1e3, parameter_constraints=constraint_dict)

# The actual fitting with constraints would follow here, likely involving
# re-fitting or initializing the Fit object with the constraints.
# For brevity, the full application is commented out as per the source.
```

--------------------------------

### Automatic caching during Fit object creation

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Shows how `Fit` objects are automatically saved to the cache folder upon creation when caching is enabled. Subsequent identical fits will be loaded from the cache.

```python
powerlaw.Fit.set_cache_folder('data/')

data = np.genfromtxt('data.txt')

# This will calculate xmin, and then cache the object
fit = powerlaw.Fit(data)
```

--------------------------------

### Load a Test Dataset

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/loading_data.md

Load a predefined test dataset, such as 'blackouts', for exploring powerlaw functionality when you don't have your own data.

```python
import powerlaw

data = powerlaw.load_test_dataset('blackouts')
```

--------------------------------

### Compare Power Law and Lognormal Distributions

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Compares the 'power_law' distribution against the 'lognormal' distribution. Set `normalized_ratio=True` for a normalized likelihood ratio. Prints the R and p values.

```python
# See which distribution fits the data better
R, p = fit.distribution_compare('power_law', 'lognormal',
                                normalized_ratio=True)

print(R, p)
```

--------------------------------

### Specify Lower Limit ($x_{min}$)

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/scaling_range.md

When the lower bound ($x_{min}$) is known from external factors, it can be directly provided during the `Fit` object creation.

```python
data = ...
xmin = 1 # Or some other value

fit = powerlaw.Fit(data, xmin=xmin)
```

--------------------------------

### Output of Distribution Comparison

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

The output of `distribution_compare` provides the loglikelihood ratio (R) and the significance value (p). A positive R suggests the first distribution is favored, while a low p indicates strong evidence for that preference.

```output
(1.4314804849576281, 0.15229255604426545)
```

--------------------------------

### Compare Power Law to Positive Lognormal Distribution

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/README.rst

Use this to compare a fitted power law distribution against a lognormal distribution where the `mu` parameter is constrained to be positive. This is useful when the generative process is assumed to involve only positive random variables.

```python
R, p = results.distribution_compare('power_law', 'lognormal_positive')
```

--------------------------------

### Implement Random Number Generation

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/new_distributions.md

Add the `generate_random` method to transform a uniform random variable into a sample from the distribution using inverse transform sampling.

```python
class NewDistribution(Distribution):

    ...

    def generate_random(self, r):
        """
        Transform a uniform random variable :math:`r` into a random
        variable sampled from this distribution.
        """
        # For example, for an exponential:
        # return self.xmin - (1 / self.Lambda) * np.log(1 - r)
```

--------------------------------

### Providing `xmax` for Noisy Power Laws near Alpha=1

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/warnings.md

For power law distributions with an exponent `alpha` close to 1 (specifically between 1 and 1.1) and no `xmax` specified, a warning is issued due to potential noise. Providing an `xmax` value, such as `np.max(data)`, is recommended to stabilize the fit.

```python
import powerlaw
import numpy as np

# Assuming 'data' is defined and might lead to alpha near 1
# Without xmax, this might raise a warning:
# fit = powerlaw.Power_Law(data)

# Recommended approach: provide xmax
fit_with_xmax = powerlaw.Power_Law(data, xmax=np.max(data))

```

--------------------------------

### Plot Power Law PDF and CCDF

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Visualize the probability density function (PDF) and complementary cumulative distribution function (CCDF) of a power-law distribution.

```python
pl.plot_pdf(label='PDF')
pl.plot_ccdf(label='CCDF')
```

--------------------------------

### Adding Metadata to FITS Headers

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Illustrates how to add or modify header keywords in a FITS file. Metadata is crucial for understanding the data.

```python
import numpy as np
from astropy.io import fits

# Create sample data
data = np.random.rand(8, 8)

# Create an HDU with header
hdu = fits.PrimaryHDU(data)

# Add custom header keywords
hdu.header['OBSERVER'] = 'Dr. Astro'
hdu.header['OBJECT'] = 'Test Galaxy'

# Save the FITS file
hdu.writeto('data_with_header.fits', overwrite=True)
```

--------------------------------

### Fit Powerlaw Distribution Without Constraints

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Load a dataset and perform a powerlaw fit without applying any custom constraints. This serves as a baseline for comparison.

```python
data = powerlaw.load_test_dataset('blackouts')

fit = powerlaw.Fit(data / 1e3)

plt.plot(fit.xmin_fitting_results["xmins"], fit.xmin_fitting_results["distances"], label='KS distance')
plt.plot(fit.xmin_fitting_results["xmins"], fit.xmin_fitting_results["valid_fits"], label='Is valid fit')

plt.axvline(fit.xmin, linestyle='--', c='black', label='Optimal $x_{min}$')

...
```

--------------------------------

### Validate Fitting Algorithm with Simulated Data

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/generating_data.md

Generate random data from theoretical power-law distributions with varying alpha values and then fit the data to validate the fitting algorithm's accuracy. This snippet sets a seed for reproducibility.

```python
np.random.seed(0)

alphaArr = np.linspace(0.5, 2.5, 100)
numSamples = 30 # per alpha value
N = 3000

fitAlphaArr = np.zeros((len(alphaArr), numSamples))

for j in range(len(alphaArr)):
    for k in range(numSamples):
        theoretical_dist = powerlaw.Power_Law(xmin=1, xmax=1e6, parameters=[alphaArr[j]])
        data = theoretical_dist.generate_random(N)

        fit = powerlaw.Fit(data, xmin=1, xmax=np.max(data))

        fitAlphaArr[j,k] = fit.power_law.alpha
```

--------------------------------

### Fit Data and Extract Parameters with Powerlaw

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/README.rst

Use this snippet to fit a powerlaw distribution to your data and extract the alpha and xmin parameters. Ensure numpy is imported.

```python
import powerlaw
import numpy as np

data = np.array([1.7, 3.2, 5.4, 2.1, 1.5, 2.8]) # data can be a list or a numpy array
fit = powerlaw.Fit(data)

print(fit.power_law.alpha)
print(fit.power_law.xmin)

R, p = fit.distribution_compare('power_law', 'lognormal')
```

--------------------------------

### Traditional Cost Function Minimization

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/other_libraries.md

Illustrates a typical cost function minimization approach used in libraries like scipy or lmfit, where a function is fitted to data by minimizing the difference between predicted and actual values.

```python
# Some function, eg. a power law
def fit_function(x, p):
    return p[0] * x**(p[1])

# Some data values
y = ...

# Some cost, eg. MSE
def cost_function(p):
    return np.sqrt(np.sum((y - fit_function(x, p))**2))

# Now we minimize this with scipy, lmfit, or some other library
minimize(cost, p0, ...)
```

--------------------------------

### Run Powerlaw Test Suite with Pytest

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/README.rst

Execute the comprehensive test suite for the powerlaw package using pytest. This ensures the library is functioning correctly.

```console
python -m pytest testing/ -v
```

--------------------------------

### Discrete Normalization Approximation: 'sum'

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/discrete_continuous.md

Use the 'sum' method for discrete normalization, which calculates the normalization constant by summing the continuous probability distribution over all integer values. This can be computationally expensive.

```python
fit = powerlaw.Fit(data, discrete=True, discrete_normalization='sum')
```

--------------------------------

### Basic powerlaw data fitting and parameter extraction

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/index.md

Fits a power law distribution to provided data and extracts the alpha and xmin parameters. The data can be a list or a numpy array.

```python
import powerlaw
import numpy as np

data = np.array([1.7, 3.2 ...]) # data can be list or numpy array
fit = powerlaw.Fit(data)

print(fit.power_law.alpha)
print(fit.power_law.xmin)

R, p = fit.distribution_compare('power_law', 'lognormal')
```

--------------------------------

### Force Discrete Estimation Technique

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/discrete_continuous.md

Explicitly set 'estimate_discrete=True' to force the use of the discrete estimation technique, even if data conditions are not met. Use with caution as it may lead to inaccurate fits.

```python
# This will require the use of the estimation technique,
# regardless of the properties of data.
# Be careful when doing this, as you may get very incorrect
# fits if you data violates the conditions!
fit = powerlaw.Fit(data, discrete=True, estimate_discrete=True)
```

--------------------------------

### Compare Power Law to Lognormal Distribution

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/README.rst

Use this to compare a fitted power law distribution against a standard lognormal distribution. This is a common step when analyzing heavy-tailed data.

```python
R, p = results.distribution_compare('power_law', 'lognormal')
```

--------------------------------

### Powerlaw PDF Comparison

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/other_libraries.md

Shows the conceptual difference in cost function for powerlaw, which compares the PDF of the data to the fitted function, rather than just the raw data values.

```python
# This compares the original data to the fit function
def cost_function(p):
    return distance_function(y - fit_function(p))

# This compares the PDF of the original data to the fit function

```

--------------------------------

### Self-contained constraint function for saving

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Presents the best practice for defining constraint functions to ensure they can be saved and loaded correctly by being fully self-contained, including necessary imports.

```python
# Best practice: fully self-contained
def constraint(dist):
    import numpy as np

    T = 100
    E = np.exp(-dist.Lambda * T)
    ...

```

--------------------------------

### Plotting PDF, CDF, and CCDF

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/visualization.md

Use these functions to visualize the PDF, CDF, and CCDF of a dataset. Accepts matplotlib keywords for customization. Ensure matplotlib is imported as plt.

```python
import powerlaw

data = powerlaw.load_test_dataset('words')

# These accept matplotlib plot keywords like 'label'
powerlaw.plot_pdf(data, label='PDF')
powerlaw.plot_cdf(data, label='CDF')
powerlaw.plot_ccdf(data, label='CCDF')
plt.legend()
plt.show()
```

--------------------------------

### Define and Apply Multiple Constraints

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Define multiple constraints, some specific to certain distributions and others general. These can be passed as a list to the Fit class for comprehensive model fitting.

```python
def constraint_1(dist):
    """
    Require that the number of points is greater than a specific value
    (so this is designed for xmin fitting).
    """
    return len(dist.data) - 1000

# This constraint applies to all distributions
constraint_dict_1 = {"type": 'ineq',
                     "fun": constraint_1}

def constraint_2(dist):
    """
    Require that the ratio of beta to Lambda is a certain value
    (only applies to a stretched exponential).
    """
    return 10 - dist.Lambda / dist.beta

# This constraint applies to only stretched exponentials
constraint_dict_2 = {"type": 'eq',
                     "fun": constraint_2,
                     "dists": ['stretched_exponential']}


all_constraints = [constraint_dict_1, constraint_dict_2]

# Pass it to a fit
fit = powerlaw.Fit(..., parameter_constraints=all_constraints)
```

--------------------------------

### Manually Compare Distributions

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Manually compares two distributions without using a `Fit` object. This method can be used when you have the parameters for the distributions and want to compare their likelihoods directly.

```python
# Manually compare two distributions without the fit object; can still
```

--------------------------------

### Define and Apply a Constraint Function

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Use the `parameter_constraints` argument to pass a dictionary defining custom inequality constraints for fitting. The constraint function should return a value that is non-negative when the constraint is satisfied.

```python
def constraint(dist):
    N = 100
    return len(dist.data) - N

constraint_dict = {"type": 'ineq',
                   "fun": constraint,
                   "dists": ['power_law']}

fit = powerlaw.Fit(data / 1e3, parameter_constraints=constraint_dict)
```

--------------------------------

### Save a Fit object to a file

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Saves the current `Fit` object to a file for later use. This is useful for preserving computationally expensive calculations like `xmin`.

```python
data = [1.1, 5.3, 3.7, ...]
fit = powerlaw.Fit(data, xmin=0.1)

fit.save('output.h5')
```

--------------------------------

### Specify Upper Limit ($x_{max}$)

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/scaling_range.md

To exclude data points larger than a certain value from fitting, specify the upper bound ($x_{max}$) when creating the `Fit` object. Data exceeding this value will be ignored.

```python
# Any data that is larger than 100 will be ignored in fitting
xmax = 100
fit = powerlaw.Fit(data, xmax=xmax)
```

--------------------------------

### Discrete Normalization Approximation: 'round'

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/discrete_continuous.md

Use the 'round' method for discrete normalization, which is the default. It approximates the probability mass at each integer by summing the continuous distribution over a small range around that integer.

```python
fit = powerlaw.Fit(data, discrete=True, discrete_normalization='round')
```

--------------------------------

### Visualize Constraint Impact

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Plot the KS distance and valid fit indicators against different xmins to visualize how constraints affect the fitting results and the optimal xmin.

```python
plt.plot(fit.xmin_fitting_results["xmins"], fit.xmin_fitting_results["distances"], label='KS distance')
plt.plot(fit.xmin_fitting_results["xmins"], fit.xmin_fitting_results["valid_fits"], label='Is valid fit')

plt.axvline(fit.xmin, linestyle='--', c='black', label='Optimal $x_{min}$')
```

--------------------------------

### Define Distribution Metadata

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/new_distributions.md

Assign the distribution's name, parameter names, and default parameter ranges when extending the `Distribution` class.

```python
class NewDistribution(Distribution):

    # This is the name of this type of distribution, that you would
    # use in eg. distribution_compare
    name = 'dist_name'

    # This should be a list with the names of parameters.
    parameter_names = ['parameter1', 'parameter2']

    # This should be a dictionary where each key is a parameter name
    # (defined above) and each value is a range [lower_bound, upper_bound].
    DEFAULT_PARAMETER_RANGES = {"parameter1": [x1, x2],
                                "parameter2": [y1, y2]}
```

--------------------------------

### Examining Parameter Ranges for Edge Fits

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/warnings.md

When fitted parameters are very close to the edge of their defined ranges, expand the parameter ranges to ensure the fitting process can find a proper solution. Inspect `parameters` and `parameter_ranges` to understand the current bounds.

```python
import powerlaw

# Assuming 'data' is defined
# fit = powerlaw.Power_Law(data, ...)
# print(fit.parameters, fit.parameter_ranges)

# To expand ranges, you would typically re-initialize with new bounds:
# new_ranges = { 'alpha': [0.1, 5.0] } # Example: expand alpha range
# fit = powerlaw.Power_Law(data, parameter_ranges=new_ranges)
```

--------------------------------

### Automatically Find Best Lower Limit ($x_{min}$)

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/scaling_range.md

If $x_{min}$ is not known, `powerlaw` can automatically find the optimal value by minimizing the distance between the data and the fit. This method is called by default when `xmin` is not specified.

```python
# This will use find_xmin() to get the best value for xmin.
fit = powerlaw.Fit(data)
```

--------------------------------

### Compare Nested Distributions Automatically

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Compares 'power_law' and 'truncated_power_law' distributions, allowing `powerlaw` to automatically determine if they are nested based on their names. This is the default behavior when comparing distributions that might be nested.

```python
# Default behavior; let powerlaw decide if they are nested based on name
fit.distribution_compare(’power_law’, ’truncated_power_law’)
```

--------------------------------

### Find $x_{min}$ within a Fixed Range

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/scaling_range.md

Restrict the search for the optimal $x_{min}$ to a specific range by providing a tuple of bounds to the `xmin` parameter.

```python
# This will use find_xmin() to get the best value for xmin in the
# fixed range 50 to 100.
fit = powerlaw.Fit(data, xmin=(50, 100))
```

--------------------------------

### Access Default Parameter Ranges for Power Law

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Retrieves the default parameter ranges defined for the Power_Law distribution. This shows the default bounds for the 'alpha' parameter.

```python
powerlaw.Power_Law.DEFAULT_PARAMETER_RANGES
```

--------------------------------

### Load Custom Data with NumPy

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/loading_data.md

Load data from a CSV file into a NumPy array for use with powerlaw. Ensure data is not binned prior to loading.

```python
import numpy as np
import powerlaw

data = np.genfromtxt('some_data.csv')

# Now we can use any powerlaw function or class
fit = powerlaw.Fit(data=data, ...)
```

--------------------------------

### Compare Nested Distributions Explicitly

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/comparing_distributions.md

Compares 'power_law' and 'truncated_power_law' distributions, explicitly specifying `nested=True` to indicate that one distribution is a nested version of the other. This ensures the correct p-value calculation for nested distributions.

```python
# Specify whether the distributions are nested
fit.distribution_compare(’power_law’, ’truncated_power_law’, nested=True)
```

--------------------------------

### Addressing Insufficient Data for Distance Metrics

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/warnings.md

If `Distribution.compute_distance_metrics()` returns `nan` due to insufficient data within the distribution's domain (`[xmin, xmax]`), review your `xmin` and `xmax` settings. Ensure they are not excessively large or small, and that fitting `xmin` was successful.

```python
import powerlaw

# Assuming 'data' is defined and causes the warning
# fit = powerlaw.Fit(data)
# fit.compute_distance_metrics()

# To fix, you might need to adjust xmin or xmax:
# fit = powerlaw.Fit(data, xmin=some_value, xmax=another_value)
```

--------------------------------

### Set Multiple Custom Parameter Ranges for Truncated Power Law

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Sets custom parameter ranges for multiple parameters ('alpha' and 'Lambda') when initializing a Truncated_Power_Law object. This allows for more complex constraints on distributions with several parameters.

```python
tpl = powerlaw.Truncated_Power_Law(data,
                                   parameter_ranges={\"alpha\": [3, 4]}, \"Lambda\": [0, 7]})
```

--------------------------------

### Apply Constraint to Truncated Power Law

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/ranges_and_constraints.md

Define and apply a constraint specifically for a truncated power law distribution. This is useful when fitting models where parameters must adhere to certain conditions.

```python
constraint_dict = {"type": 'ineq',
                   "fun": constraint,
                   "dists": ['truncated_power_law']}

# Pass it to a fit
fit = powerlaw.Fit(..., parameter_constraints=constraint_dict)

# Or could directly pass it to a truncated power law
tpl = powerlaw.Truncated_Power_Law(..., parameter_constraints=constraint_dict)
```

--------------------------------

### Enable automatic fit caching

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/saving_fits.md

Configures `powerlaw` to automatically cache all `Fit` objects by setting a cache directory. This prevents recalculations if an identical fit is encountered later.

```python
powerlaw.Fit.set_cache_folder('data/')
```

--------------------------------

### Handling Integer Data with `discrete=False`

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/warnings.md

When `discrete=False` is set but the data exclusively contains integers, consider using `discrete=True` if the underlying quantity is truly continuous but measured in discrete steps. If the data is inherently discrete, this warning can be safely ignored.

```python
import powerlaw
import numpy as np

data = np.array([1, 2, 3, 4, 5])

# Example of using discrete=True for integer data
fit = powerlaw.Fit(data, discrete=True)

# If the data is truly continuous, this warning can be ignored or handled by setting discrete=False
```

--------------------------------

### Plotting Empirical and Fitted Distributions

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/visualization.md

After fitting a distribution to data, plot the empirical PDF alongside theoretical fits like power law or exponential. The Fit object automatically handles data range and xmin/xmax.

```python
data = powerlaw.load_test_dataset('fires')

fit = powerlaw.Fit(data)

# Plot the distributions based on the data
# No need to pass the data since the Fit already has it
fit.plot_pdf(label='PDF')

# Plot some fits fit.power_law.plot_pdf(linestyle='--', label='Power law fit')
fit.exponential.plot_pdf(linestyle='--', label='Exponential fit')

...
```

--------------------------------

### Diagnose No Possible Fits with Noise Flag

Source: https://github.com/powerlaw-devs/powerlaw/blob/master/docs/source/tutorials/advanced_topics.md

Use the `noise_flag` property to diagnose issues where no valid fits are found. This can occur due to strict fitting requirements or data that doesn't match the specified form.

```python
data = powerlaw.load_test_dataset('blackouts')

# pl.noiseflag will be True since the powerlaw exponent of the
# blackouts dataset should be around 2.4, outside of the prescribed
# range.
pl = powerlaw.Power_Law(data, parameter_ranges={\"alpha\": [1, 2]})
pl.noise_flag

# fit.noiseflag will be True since the prescribed sigma_threshold
# is too low
# range.
fit = powerlaw.Fit(data, sigma_threshold=1e-12)
pl.noise_flag
```