maxent-disaggregation 1.0.0

Package to help with the propagation of uncertainty when disaggregating data, using the maximum entropy principle.

maxent_disaggregation

maxent_disaggregation is a python package to help with the propagation of uncertainty when disaggregating data, based on the maximum entropy principle. It samples from various forms of the Dirichlet distribution, maximising the entropy based on the available information.

Installation

You can install maxent_disaggregation via pip from PyPI:

$ pip install maxent_disaggregation

The goal of maxent_disaggregation is to provide an easy to use Python tool that helps you with uncertainty propagation when data disaggregation is involved. Data disaggregation usually involves splitting one data point $$Y_0$$ into $$K$$ disaggregate quantities $$Y_1, Y_2, ..., Y_K$$ using proxy data. It is a common problem in many different research disciplines.

flowchart-elk TD
    %% Define node classes
    classDef Aggregate fill:#eeeee4,color:black,stroke:none;
    classDef DisAgg1 fill:#abdbe3,color:black,stroke:none;
    classDef DisAgg2 fill:#e28743,color:black,stroke:none;
    classDef DisAgg3 fill:#abdbe3,color:black,stroke:none;

    agg("Y_0"):::Aggregate
    disagg1("Y_1=x_1 Y_0"):::DisAgg1
    disagg2("Y_2=x_2 Y_0"):::DisAgg1
    disagg3("Y_3=x_3 Y_0"):::DisAgg1
   

    %% Define connections
    agg  --> disagg1
    agg  --> disagg2
    agg  --> disagg3

For more detailed description of the package, theory please see the documentation page. For a quickstart see below:

Quick start

from maxent_disaggregation import maxent_disagg
import numpy as np

# best guess or mean of the total quantity Y_0 (if available)
mean_aggregate = 10
# best guess of the standard deviation of the total quantity Y_0 (if available)
sd_aggregate = 1
# min/max value of the total quantity Y_o (if applicable/available) (optional)
min_aggregate = 0
max_aggregate = np.inf
# best guess values and uncertainties from proxy data for the shares (x_i) if available (of not available put in np.nan)
shares_disaggregates = [0.4, 0.25, 0.2, 0.15]
sds_shares = [0.1, np.nan, 0.04, 0.001]

# Now draw 10000 samples
samples, _ = maxent_disagg(n=10000, 
                        mean_0=mean_aggregate,
                        sd_0=sd_aggregate,
                        min_0=min_aggregate,
                        max_0=max_aggregate, 
                        shares=shares_disaggregates, 
                        sds=sds_shares, 
                        )

# Now plot the sampled distributions
from maxent_disaggregation import plot_samples_hist
# the input values are provided for the legend
plot_samples_hist(samples, 
                  mean_0=mean_aggregate,
                  sd_0=sd_aggregate, 
                  shares=shares_disaggregates, 
                  sds=sds_shares)

We can also easily plot the covariances between the different disaggrate quantities:

# Plot the covariances between the disaggregates
from maxent_disaggregation import plot_covariances
plot_covariances(samples)

Reference

If you find this package useful please share and cite our paper: [DOI]

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, maxent_disaggregation is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.