IDEAS home Printed from https://ideas.repec.org/a/sae/envirb/v52y2025i4p1014-1024.html

tscluster: A python package for the optimal temporal clustering framework

Author

Listed:
  • Jolomi Tosanwumi
  • Jiazhou Liang
  • Daniel Silver
  • Ethan Fosse
  • Scott Sanner

Abstract

Temporal clustering extends the conventional task of data clustering by grouping time series data according to shared temporal trends across sociospatial units, with diverse applications in the social sciences, especially urban science. The two dominant methods are as follows: Time Series Clustering (TSC), with dynamic cluster centres but static labels for each entity, and Sequence Label Analysis (SLA), with static cluster centres but dynamic labels. To implement the universe of models spanning the design space between TSC and SLA, we present tscluster , an open-source Python framework. tscluster offers: (1) several innovative techniques, such as Bounded Dynamic Clustering (BDC), that are not available in existing libraries, allowing users to set an upper bound on the number of label changes and identify the most dynamically evolving time series; (2) a user-friendly interface for applying and comparing these methods; (3) globally optimal solutions for the clustering objective by employing a mixed-integer linear programming formulation, enhancing the reproducibility and robustness of the results in contrast to existing methods based on initialization-sensitive local optimization; and (4) a suite of visualization tools for interpretability and comparison of clustering results. We present our framework using a case study of neighbourhood change in Toronto, comparing two methods available in tscluster . Supplemental materials provide an additional case study of local business development in Chicago and a detailed mathematical exposition of our framework. tscluster can be installed via PyPI (pypi.org/project/tscluster), and the source code is accessible on Github (github.com/tscluster-project/tscluster). Documentation is available online at the tscluster website (tscluster.readthedocs.io).

Suggested Citation

  • Jolomi Tosanwumi & Jiazhou Liang & Daniel Silver & Ethan Fosse & Scott Sanner, 2025. "tscluster: A python package for the optimal temporal clustering framework," Environment and Planning B, , vol. 52(4), pages 1014-1024, May.
    • Handle: RePEc:sae:envirb:v:52:y:2025:i:4:p:1014-1024
    DOI: 10.1177/23998083241293833
    as

    Download full text from publisher

    File URL: https://journals.sagepub.com/doi/10.1177/23998083241293833
    Download Restriction: no
    File URL: https://libkey.io/10.1177/23998083241293833?utm_source=ideas
    LibKey link: if access is restricted and if your library uses this service, LibKey will redirect you to where you can use your library subscription to access this item
    ---><---

    References listed on IDEAS

    as
    1. Elizabeth C. Delmelle, 2016. "Mapping the DNA of Urban Neighborhoods: Clustering Longitudinal Sequences of Neighborhood Socioeconomic Change," Annals of the American Association of Geographers, Taylor & Francis Journals, vol. 106(1), pages 36-56, January.
    2. Daniel Silver & Thiago H Silva, 2021. "A Markov model of urban evolution: Neighbourhood change as a complex process," PLOS ONE, Public Library of Science, vol. 16(1), pages 1-29, January.
    Full references (including those not matched with items on IDEAS)

    Most related items

    These are the items that most often cite the same works as this one and are cited by the same works as this one.
    1. repec:osf:socarx:wprf8_v1 is not listed on IDEAS
    2. Silver, Daniel & Silva, Thiago H, 2021. "Complex Causal Structures of Neighbourhood Change: Evidence From a Functionalist Model and Yelp Data," SocArXiv wprf8, Center for Open Science.
    3. Sek-yum Ngai, Steven & Cheung, Chau-kiu & Ng, Yuen-hang & Joo Lee, Bong & Dupéré, Véronique & Wang, Miao & Zhou, Qiushi & Chen, Chen & Li, Yunjun & Wong, Laing-ming & Yu, Elly Ngai-hin, 2025. "Unraveling the school-to-work transition of non-engaged youth: A continuous-time Markov chain analysis," Children and Youth Services Review, Elsevier, vol. 172(C).
    4. repec:osf:socarx:8jbvg_v1 is not listed on IDEAS
    5. Nilsson, Isabelle & Delmelle, Elizabeth, 2018. "Transit investments and neighborhood change: On the likelihood of change," Journal of Transport Geography, Elsevier, vol. 66(C), pages 167-179.
    6. Megan Doherty Bea, 2024. "A Life Course Perspective of Community (Non)Investment: Historical Financial Service Trajectories and Community Outcomes," Journal of Family and Economic Issues, Springer, vol. 45(2), pages 288-307, June.
    7. Evelyn Ravuri, 2023. "Neighbourhood change in Genesee and Kent Counties, Michigan, 1970–2019," Papers in Regional Science, Wiley Blackwell, vol. 102(1), pages 107-127, February.
    8. Angelo Raherinirina & Stefana Tabera Tsilefa & Tsidikaina Nirilanto & Solym M Manou-Abi, 2025. "Bayesian inference of a spatially dependent semi-Markovian model with application to Madagascar Covid’19 data," PLOS ONE, Public Library of Science, vol. 20(7), pages 1-25, July.
    9. Matheus Pereira Libório & Oseias da Silva Martinuci & Alexei Manso Correa Machado & Renata de Mello Lyrio & Patrícia Bernardes, 2022. "Time–Space Analysis of Multidimensional Phenomena: A Composite Indicator of Social Exclusion Through k-Means," Social Indicators Research: An International and Interdisciplinary Journal for Quality-of-Life Measurement, Springer, vol. 159(2), pages 569-591, January.
    10. Levi J Wolf & Elijah Knaap & Sergio Rey, 2021. "Geosilhouettes: Geographical measures of cluster fit," Environment and Planning B, , vol. 48(3), pages 521-539, March.
    11. repec:osf:socarx:yubkr_v1 is not listed on IDEAS
    12. Thiago H Silva & Daniel Silver, 2025. "Using graph neural networks to predict local culture," Environment and Planning B, , vol. 52(2), pages 355-376, February.
    13. Olson, Alex & Calderon-Figueroa, Fernando & Bidian, Olimpia & Silver, Daniel & Sanner, Scott, 2020. "Reading the city through its neighbourhoods: Deep text embeddings of Yelp reviews as a basis for determining similarity and change," SocArXiv 8jbvg, Center for Open Science.
    14. Senkai Xie & Wenjia Zhang & Yi Zhao & De Tong, 2022. "Extracting Land Use Change Patterns of Rural Town Settlements with Sequence Alignment Method," Land, MDPI, vol. 11(2), pages 1-17, February.
    15. Le Petit-Guerin Mehdi & Velthuis Sanne & Royer Jeroen & Cauchi-Duval Nicolas & Franklin Rachel & Leibert Tim & MacKinnon Danny & Pike Andy, 2025. "Identifying trajectories of regional ‘left-behindness’ in the EU15 from 1982 to 2017," ZFW – Advances in Economic Geography, De Gruyter, vol. 69(4), pages 177-190.
    16. Lekkas, Peter & Howard, Natasha J & Stankov, Ivana & daniel, mark & Paquet, Catherine, 2019. "A Longitudinal Typology of Neighbourhood-level Social Fragmentation: A Finite Mixture Model Approach," SocArXiv 56x9c, Center for Open Science.
    17. Lu, Zhong-Wen & Xu, Yuan-Hao & Chen, Jie & Hu, Mao-Bin, 2023. "Investigation of traffic-driven epidemic spreading by taxi trip data," Physica A: Statistical Mechanics and its Applications, Elsevier, vol. 632(P1).
    18. Alex Ramiller, 2025. "Unravelling neighbourhood change: Decomposing the effects of residential mobility and incumbent change on credit access in California," Environment and Planning A, , vol. 57(8), pages 1052-1068, November.
    19. Nikos Patias, 2019. "Exploring long-term youth unemployment in Europe using sequence analysis: a reproducible notebook approach," REGION, European Regional Science Association, vol. 6, pages 53-69.
    20. Isabelle Nilsson & Elizabeth C Delmelle, 2025. "How the marketing of real estate properties explains mortgage applicants by race and income," Environment and Planning B, , vol. 52(6), pages 1407-1423, July.
    21. Seth A. Williams & John R. Hipp, 2022. "The shape of neighborhoods to come: Examining patterns of gentrification and holistic neighborhood change in Los Angeles County, 1980–2010," Environment and Planning A, , vol. 54(2), pages 265-294, March.
    22. Dias, Fabio & Silver, Daniel, 2018. "Visualizing demographic evolution using geographically inconsistent census data," SocArXiv a3gtd, Center for Open Science.
    23. Carl Grodach & Nícolas Guerra-Tão, 2025. "Zoning a productive city? A typology of clustering, diversity and specialisation in Melbourne’s urban industrial areas," Urban Studies, Urban Studies Journal Limited, vol. 62(12), pages 2371-2393, September.

    More about this item

    Keywords

    ;
    ;
    ;
    ;
    ;

    Statistics

    Access and download statistics

    Corrections

    All material on this site has been provided by the respective publishers and authors. You can help correct errors and omissions. When requesting a correction, please mention this item's handle: RePEc:sae:envirb:v:52:y:2025:i:4:p:1014-1024. See general information about how to correct material in RePEc.

    If you have authored this item and are not yet registered with RePEc, we encourage you to do it here. This allows to link your profile to this item. It also allows you to accept potential citations to this item that we are uncertain about.

    If CitEc recognized a bibliographic reference but did not link an item in RePEc to it, you can help with this form .

    If you know of missing items citing this one, you can help us creating those links by adding the relevant references in the same way as above, for each refering item. If you are a registered author of this item, you may also want to check the "citations" tab in your RePEc Author Service profile, as there may be some citations waiting for confirmation.

    For technical questions regarding this item, or to correct its authors, title, abstract, bibliographic or download information, contact: SAGE Publications (email available below). General contact details of provider: .

    Please note that corrections may take a couple of weeks to filter through the various RePEc services.

    IDEAS is a RePEc service. RePEc uses bibliographic data supplied by the respective publishers.