ABRSQOL 1.0.2
Numerical solution algorithm to invert a quality of life measure.
License: MIT

# Python toolkit for measuring quality of life under spatial frictions
(c) Gabriel M. Ahlfeldt, Fabian Bald, Duncan Roth, Tobias Seidel
Version 1.0.2, 2024-10
This repository contains the Python implementation of the [ARBSQOL-toolkit](https://github.com/Ahlfeldt/ABRSQOL-toolkit).

## 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, run the following command in your python environment in your terminal. 

```console
pip install ABRSQOL
```
Alternatively you can also install it from within your python script:
```python
import subprocess, sys
subprocess.check_call([sys.executable, "-m", "pip", "install", 'ABRSQOL'])
```
<details>
<summary>In case an error occurs at the installation...</summary>

with an erorr message like 'metadata-generation-failed', it is likely caused by incompatabile versions of `setuptools` and `packaging`. 
This can be fixed by upgrading `setuptools` and `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
```

</details>



## Usage
You may then load the package by running:
```python
import ABRSQOL
```
Or if you prefer alternatively import the function and testdata explicitly:
```python
from ABRSQOL import invert_quality_of_life, testdata
```

### 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`](https://github.com/Ahlfeldt/ABRSQOL-toolkit-python/blob/main/Example.py) (or [`Example.ipynb`](https://github.com/Ahlfeldt/ABRSQOL-toolkit-python/blob/main/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.

## Acknowledgements
The Python version of the toolkit was developed by [Max von Mylius](https://github.com/maximylius) based on the Stata and MATLAB functions.