Metadata-Version: 2.4
Name: shiftshare
Version: 0.1.2
Summary: Regional economic analysis for planners: location quotients (SLQ, CILQ, FLQ, AFLQ), shift-share decompositions (Dunn, Esteban-Marquillas, Arcelus, dynamic), Krugman and Hoover indices, Ellison-Glaeser agglomeration and economic base multipliers.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/shiftshare_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/shiftshare_sdk
Project-URL: Documentation, https://gitlab.com/geophilo1/shiftshare_sdk#readme
Project-URL: Issues, https://gitlab.com/geophilo1/shiftshare_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/shiftshare_sdk/-/blob/main/CHANGELOG.md
Project-URL: SDK dashboard, https://geophilo.com/sdk-dashboard/
Project-URL: DOI, https://doi.org/10.5281/zenodo.24235554
Keywords: shift-share,location-quotient,flq,regional-economics,regional-science,economic-base,base-multiplier,minimum-requirements,krugman-index,hoover,ellison-glaeser,agglomeration,specialization,urban-planning
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://geophilo.com/sdk-dashboard/"><img src="https://geophilo.com/assets/sdk_icons/shiftshare_sdk.svg" width="120" height="120" alt="shiftshare icon"></a>
</p>

# shiftshare

[![PyPI version](https://img.shields.io/pypi/v/shiftshare.svg)](https://pypi.org/project/shiftshare/)
[![Python versions](https://img.shields.io/pypi/pyversions/shiftshare.svg)](https://pypi.org/project/shiftshare/)
[![pipeline status](https://gitlab.com/geophilo1/shiftshare_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/shiftshare_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/shiftshare_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235554.svg)](https://doi.org/10.5281/zenodo.24235554)
[![Downloads](https://static.pepy.tech/badge/shiftshare/month)](https://pepy.tech/project/shiftshare)

**Regional economic analysis on region x sector employment tables.**

`shiftshare` collects the standard tools of regional economic analysis used in planning
practice and regional science, working on a matrix of employment (or output, or
establishments) by region and sector:

- **Location quotients**: simple (SLQ), cross-industry (CILQ), Flegg (FLQ) with a
  user-chosen `delta` or `lambda*`, augmented FLQ (AFLQ), and regionalisation of national
  input-output coefficients.
- **Shift-share**: classic (Dunn 1960), Esteban-Marquillas (1972) with homothetic
  employment and allocation effect, Arcelus (1984) eight-component model, and dynamic
  shift-share (Barff & Knight 1988).
- **Specialisation and localisation**: Krugman specialisation index (against the nation,
  the rest of the nation, or pairwise), Hoover coefficients of localisation and
  specialisation, localisation curve with locational Gini, Herfindahl index.
- **Agglomeration**: Ellison-Glaeser (1997) index and coagglomeration index, plant
  Herfindahl from plant sizes.
- **Economic base**: basic employment and base multiplier by the assumption, location
  quotient and minimum requirements (Ullman & Dacey 1960) methods.

It needs only NumPy. Inputs can be NumPy arrays, nested lists, or labelled
`EmploymentTable`s read from CSV (wide or long) or JSON. A command-line tool is included.

## Installation

```bash
pip install shiftshare
```

Requires Python 3.9 or newer.

## Quickstart

```python
import numpy as np
import shiftshare as ss

# rows = regions, columns = sectors
base = np.array([[60, 40], [40, 60]], dtype=float)
end = np.array([[75, 40], [45, 70]], dtype=float)

ss.location_quotient(base)            # [[1.2, 0.8], [0.8, 1.2]]

res = ss.classic(base, end)           # Dunn (1960)
res.national_share                    # [[9, 6], [6, 9]]
res.industry_mix                      # [[3, -2], [2, -3]]
res.regional_shift                    # [[3, -4], [-3, 4]]
res.region_totals()                   # each component summed per region

em = ss.esteban_marquillas(base, end)
em.competitive, em.allocation         # split of the regional shift
em.allocation_type()                  # "competitive advantage, specialized", ...

ss.arcelus(base, end).components()    # eight components that add up to the change
ss.dynamic([base, end, end * 1.05])   # year-by-year shift-share, summed

ss.krugman_index(base, versus="rest")         # [0.4, 0.4]
ss.coefficient_of_localization(base)          # Hoover, per sector
ss.lq_method(base).multiplier                 # economic base multiplier, LQ method
ss.minimum_requirements(base).multiplier      # Ullman & Dacey
ss.flq(base[0], base.sum(axis=0), delta=0.3)  # FLQ matrix for region 0
```

With labels:

```python
t = ss.read_table("employment_2015.csv")      # wide: region,Agri,Manuf,...  or long
t.label(ss.location_quotient(t), "lq")        # [{"region":..., "sector":..., "lq":...}]
ss.profile(t)                                 # LQs, specialisation, localisation, multipliers
ss.decompose(t, ss.read_table("employment_2023.csv"), "esteban-marquillas")
```

National totals default to the column sums of the matrix (the regions make up the
nation). When the regions are only part of the nation, pass the national sector totals as
`reference=` (structure measures) or `national_base=` / `national_end=` (shift-share).

## Features

| Area | Functions |
| --- | --- |
| Location quotients | `location_quotient`, `cross_industry_lq`, `flegg_lambda`, `flq`, `aflq`, `regionalize` |
| Shift-share | `classic`, `esteban_marquillas`, `arcelus`, `dynamic`, `growth_rates` |
| Specialisation | `krugman_index`, `krugman_pairwise`, `coefficient_of_specialization`, `herfindahl`, `sector_shares` |
| Localisation | `coefficient_of_localization`, `localization_curve` |
| Agglomeration | `ellison_glaeser`, `coagglomeration`, `raw_concentration`, `plant_herfindahl` |
| Economic base | `assumption_method`, `lq_method`, `minimum_requirements`, `base_multiplier` |
| Tables and I/O | `EmploymentTable`, `read_table`, `read_vector`, `write_csv`, `write_json`, `profile`, `decompose`, `decompose_dynamic` |

## Methods and sources

Notation: `e[r,i]` employment of sector `i` in region `r`, `e[r]` regional total, `E[i]`
national sector total, `E` national total; `0` base year, `1` end year; `G = E1/E0 - 1`,
`G[i] = E1[i]/E0[i] - 1`, `g[r] = e1[r]/e0[r] - 1`, `g[r,i] = e1[r,i]/e0[r,i] - 1`.

| Measure | Definition | Source |
| --- | --- | --- |
| SLQ | `(e[r,i]/e[r]) / (E[i]/E)` | Isard (1960); Miller & Blair (2009) |
| CILQ | `SLQ[i] / SLQ[j]` (supplying `i`, purchasing `j`) | Miller & Blair (2009) |
| FLQ | `lambda* CILQ[i,j]`, diagonal `lambda* SLQ[i]`, `lambda* = [log2(1 + RE/NE)]^delta`, `0 <= delta < 1` | Flegg, Webber & Elliott (1995) |
| AFLQ | `FLQ[i,j] log2(1 + SLQ[j])` where `SLQ[j] > 1` | Flegg & Webber (2000) |
| Regionalisation | `r[i,j] = a[i,j] min(LQ, 1)` | Miller & Blair (2009) |
| Classic shift-share | `NS = e0 G`, `IM = e0 (G[i] - G)`, `RS = e0 (g[r,i] - G[i])` | Dunn (1960) |
| Esteban-Marquillas | `e_hat = e0[r] E0[i]/E0`; `C' = e_hat (g[r,i] - G[i])`, `A = (e0 - e_hat)(g[r,i] - G[i])` | Esteban-Marquillas (1972) |
| Arcelus | rate split `G + (G[i]-G) + (g[r]-G) + [(g[r,i]-g[r]) - (G[i]-G)]`, each applied to `e_hat` and `e0 - e_hat` | Arcelus (1984) |
| Dynamic shift-share | classic model on each consecutive pair of years, summed | Barff & Knight (1988) |
| Krugman index | `sum_i |s[r,i] - s_ref[i]|`, 0 to 2 | Krugman (1991) |
| Coefficient of specialisation | `0.5 sum_i |e[r,i]/e[r] - E[i]/E|` | Hoover (1936); Isard (1960) |
| Coefficient of localisation | `0.5 sum_r |e[r,i]/E[i] - e[r]/E|` | Hoover (1936) |
| Locational Gini | `2 x` area between the localisation curve (regions by decreasing LQ) and the diagonal (Krugman reports the undoubled area, maximum 0.5) | Hoover (1936); Krugman (1991, app. D) |
| Herfindahl | `sum_i s[r,i]^2` | Hirschman (1964) |
| Ellison-Glaeser | `gamma = (G - (1 - sum x^2) H) / ((1 - sum x^2)(1 - H))`, `G = sum_r (s_r - x_r)^2` | Ellison & Glaeser (1997) |
| Coagglomeration | `[G/(1 - sum x^2) - H - sum_j gamma_j w_j^2 (1 - H_j)] / (1 - sum_j w_j^2)` | Ellison & Glaeser (1997) |
| LQ basic employment | `max(e[r,i] - e[r] E[i]/E, 0)` | Isard (1960); Tiebout (1962) |
| Minimum requirements | `max(e[r,i] - m[i] e[r], 0)`, `m[i]` the smallest share among comparable regions | Ullman & Dacey (1960) |
| Base multiplier | `total / basic` | Tiebout (1962) |

Conventions and choices:

- Every shift-share decomposition adds up exactly to `e1 - e0` for every cell. Cells with
  zero base employment have no growth rate; their change is booked as regional shift
  (classic), as competitive effect with zero allocation (Esteban-Marquillas, flagged in
  `undefined`), or in the regional industry-mix term (Arcelus).
- No calibration constants are built in. Flegg's `delta`, the plant Herfindahl for the
  Ellison-Glaeser index, assumption-method basic sectors or fractions, and the comparable
  region set and rank for minimum requirements are all supplied by the user.

References:

- Arcelus, F.J. (1984) An extension of shift-share analysis. *Growth and Change* 15(1), 3-8.
- Barff, R.A. and Knight, P.L. (1988) Dynamic shift-share analysis. *Growth and Change* 19(2), 1-10.
- Dunn, E.S. (1960) A statistical and analytical technique for regional analysis. *Papers and Proceedings of the Regional Science Association* 6, 97-112.
- Ellison, G. and Glaeser, E.L. (1997) Geographic concentration in U.S. manufacturing industries: a dartboard approach. *Journal of Political Economy* 105(5), 889-927.
- Esteban-Marquillas, J.M. (1972) A reinterpretation of shift-share analysis. *Regional and Urban Economics* 2(3), 249-255.
- Flegg, A.T., Webber, C.D. and Elliott, M.V. (1995) On the appropriate use of location quotients in generating regional input-output tables. *Regional Studies* 29(6), 547-561.
- Flegg, A.T. and Webber, C.D. (2000) Regional size, regional specialization and the FLQ formula. *Regional Studies* 34(6), 563-569.
- Hirschman, A.O. (1964) The paternity of an index. *American Economic Review* 54(5), 761-762.
- Hoover, E.M. (1936) The measurement of industrial localization. *Review of Economics and Statistics* 18(4), 162-171.
- Isard, W. (1960) *Methods of Regional Analysis: An Introduction to Regional Science*. MIT Press.
- Krugman, P. (1991) *Geography and Trade*. MIT Press.
- Miller, R.E. and Blair, P.D. (2009) *Input-Output Analysis: Foundations and Extensions*, 2nd ed. Cambridge University Press.
- Tiebout, C.M. (1962) *The Community Economic Base Study*. Committee for Economic Development.
- Ullman, E.L. and Dacey, M.F. (1960) The minimum requirements approach to the urban economic base. *Papers and Proceedings of the Regional Science Association* 6, 175-194.

## Command line

```bash
shiftshare profile employment_2015.csv --csv lq.csv -o profile.json
shiftshare decompose employment_2015.csv employment_2023.csv --method esteban-marquillas \
    --national-base nation_2015.csv --national-end nation_2023.csv --csv components.csv
shiftshare dynamic emp_2019.csv emp_2020.csv emp_2021.csv emp_2022.csv
shiftshare base employment_2023.csv --method mr --csv basic.csv
shiftshare base employment_2023.csv --method assumption --basic-sectors Manufacturing,Mining
shiftshare flq employment_2023.csv --region Coast --delta 0.3 --coefficients national_A.csv
shiftshare eg plants_by_region.csv --herfindahl plant_herfindahl.csv
```

Tables are CSV (wide: first column region, one column per sector; or long: `region`,
`sector`, `employment`/`value` columns; `,`, `;` or tab separated) or JSON. Sector vectors
(national totals, Herfindahl values) are CSV `sector,value` rows or a JSON object. Results
are printed as JSON or written with `-o`; `--csv` writes the detailed table.

## Citation

If you use `shiftshare` in your work, please cite it (see `CITATION.cff`):

```bibtex
@software{eminoglu_shiftshare,
  author  = {Eminoğlu, Yusuf},
  title   = {shiftshare: regional economic analysis on region x sector employment tables},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24235554},
  year    = {2026},
  url     = {https://gitlab.com/geophilo1/shiftshare_sdk}
}
```

and the original sources of the methods you use.

## Related Geophilo SDKs

- [urbanscaling](https://pypi.org/project/urbanscaling/): urban scaling laws `Y = Y0 N^beta` with OLS, RMA, robust fits and SAMIs.
- [ranksize](https://pypi.org/project/ranksize/): city-size distributions, Zipf rank-size regression, power-law tails and primacy indices.
- [homeafford](https://pypi.org/project/homeafford/): housing affordability metrics such as price-to-income, cost burden and residual income.
- [cohortproj](https://pypi.org/project/cohortproj/): cohort-component population projection, life tables and Leslie matrices.

## License

MIT. See `LICENSE`.
