Metadata-Version: 2.1
Name: ABRSQOL
Version: 1.0.0
Summary: Numerical solution algorithm to invert a quality of life measure.
Home-page: https://github.com/Ahlfeldt/ABRSQOL-toolkit/blob/main/Python
Author: Gabriel M Ahlfeldt
Author-email: g.ahlfeldt@hu-berlin.de
License: MIT
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Provides-Extra: ci
Requires-Dist: pytest>=4; extra == "ci"
Requires-Dist: pytest-cov>=2; extra == "ci"
Requires-Dist: python-coveralls; extra == "ci"
Provides-Extra: dev
Requires-Dist: pytest>=4; extra == "dev"
Requires-Dist: pytest-cov>=2; extra == "dev"
Requires-Dist: twine>=4.0.2; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=4; extra == "test"
Requires-Dist: pytest-cov>=2; extra == "test"


# ABRSQOL
## About
This toolkit implements a numerical solution algorithm
to invert a quality of life (QoL) from observed data
in various programming languages. The QoL measure is
based on Ahlfeldt, Bald, Roth, Seidel (2024):
Measuring quality of life under spatial frictions.
Unlike the traditional Rosen-Roback measure, this measure
accounts for mobility frictionsâ€”generated by idiosyncratic
tastes and local tiesâ€”and trade frictionsâ€”generated by
trade costs and non-tradable services, thereby reducing
non-classical measurement error.

Notice that quality of life is identified up to a constant.
Therefore, the inverted QoL measures measure has a relative
interpretation only. We normalize the QoL relative to the first
observation in the data set. It is straightforward to rescale
the QoL measure to any other location or any other value (such
as the mean or median in the distribution of QoL across locations).

When using this toolkit in your work, please cite Gabriel M. Ahlfeldt, Fabian Bald, Duncan Roth, Tobias Seidel (forthcoming): Measuring quality of life under spatial frictions

## Installation
To install the Python package of the ABRSQOL-toolkit from github, run the following command in your python environment, run the following command in you anaconda shell. 

```console
pip install "git+https://git@github.com/Ahlfeldt/ABRSQOL-toolkit.git#subdirectory=Python&egg=ABRSQOL"
```
In case an error occurs at the installation (error: metadata-generation-failed), it is likely caused by incompatabile versions of setuptools and packaging. 
This can be fixed by upgrading packaging to compatible versions:
```console
pip install --upgrade setuptools>=74.1.1
pip install --upgrade packaging>=22.0
```
Or by downgrading setuptools:
```console
pip install --upgrade setuptools==70.0.0
```
Notice that you must also install 'git' available at https://git-scm.com/ for the installation to work.

You may then load it by running:
```python
import ABRSQOL
```

## Examples
### Example 1: load testdata, run QoL inversion with default parameters, store result as 'QoL' variable, view result
```python
testdata = ABRSQOL.testdata
testdata['QoL'] = ABRSQOL.invert_quality_of_life(df=testdata)
testdata.head()
```

### Example 2: load your data from csv, run inversion, save result as csv
```python
my_dataframe = read.csv("path/to/your/csv_filename.csv")
my_dataframe['quality_of_life'] = ABRSQOL.invert_quality_of_life(
  # supply your dataset as a dataframe
  df=my_dataframe,
  # specify the corresponding variable name for your dataset
  w = 'wage',
  p_H = 'floor_space_price',
  P_t = 'tradable_goods_price',
  p_n = 'local_services_price',
  L = 'residence_pop',
  L_b = 'L_b',
  # freely adjust remaining parameters
  alpha = 0.7,
  beta = 0.5,
  gamma = 3,
  xi = 5.5,
  conv = 0.3,
  tolerance = 1e-11,
  maxiter = 50000
)
# Write output to target folder (just replace the path)
from pandas import write_csv
write_csv(my_dataframe, 'C:/FOLDER/my_data_with_qol.csv')
```

### Example 3: Reference variables in your dataset by using the column index
```python
my_dataframe['QoL'] = ABRSQOL.invert_quality_of_life(
  df=my_dataframe,
  w = 1,
  p_H = 3,
  P_t = 4,
  p_n = 2,
  L = 6,
  L_b = 5
)
```

### Example 4: Having named the variables in your data according to the default parameters, you can omit specifying variable names
```python
my_dataframe['QoL'] = ABRSQOL.invert_quality_of_life(
  df=my_dataframe,
  alpha = 0.7,
  beta = 0.5,
  gamma = 3,
  xi = 5.5,
  conv = 0.5
)
```

## Ready-to-use script

If you are new to Python, you may find it useful to execute the Example.py (or Example.ipynb) script saved in this folder. It will install the package, load the testing data set, generate a quality-of-life index, and save it to your working directory.  It should be straightforward to adapt the script to your data and preferred parameter values.
