Echoes of a city’s quiet catalog

Médiathèque José Cabanis, Tolosa.

From the slow, patient stacks where the pink city’s breath settles into paper and dust, this catalogue was born. Not as a tidy ledger but as a tangled testimony of lives and seasons that bears the stains and slips of human passage. Children with bright breath, adults with careful hands all interfering the patient circulation of the months and years. This is a narrative of what a town borrows and forgets; so it might be read again.

This project processes CSV exports of library loan counts and produces a set of analytical JSON outputs per category (e.g., movies, books, music). It first cleans mojibake and CSV artifacts and then provides insights by aggregating counts, detecting trends (progressions/regressions), extracting shooting stars, and computing top-n lists in several types of groupings.

The analysis is available as:

• A standalone python script
• A didactic jupyter notebook

Mojibake and misaligned CSV fields quietly break analyses. Garbled characters (mojibake) turn informations into unreadable strings, while misplaced delimiters or extra semicolons shift columns so numeric counts and category flags land in the wrong fields. Together they lead to silent data corruption — resulting in wrong aggregations and incorrect classifications.

Repairing these issues requires careful encoding detection and targeted string fixes, plus defensive parsing (line cleanup and column coercion) so the analysis recovers true data without discarding valuable records.

• Python 3.10+
• jupyterlab notebook if you want to run the notebook.
• Packages:
  • pandas
  • chardet

1. Clone or download the repository:

   • git clone https://github.com/brooks-code/toulouse-biblio-chronicle.git

2. (Recommended) Within the script's location, create and activate a virtual environment :

   • python -m venv venv
   • source venv/bin/activate (macOS / Linux) or venv\Scripts\activate (Windows)

3. Install the dependencies:

   • pip install pandas chardet

Prerequisites:

• Check the CSV files are in a folder named dataset (or set a different folder in the Config). If not, they are available in this repository or here (search for the top-500 datasets).

• CSV filenames should contain one of the keywords (default: films, imprimes, cds) so the script can find them via glob "{discriminator}.csv".

  • Run the toulouse_public_library.ipynb notebook.

  • Or run the script from the command line:

python toulouse_library.py

• Outputs are written to output/results_{discriminator}.json.

Expected CSV: semi-colon delimited files containing rows with at least:

• “–” represents missing data.
• category column (default: Cat 1) contains audience markers such as A, E, BB, P.
• Media type depends of the dataset type.

ANNEE;Nbre de prêts;TITRE;AUTEUR;Editeur;Indice;BIB;COTE;Cat 1;Cat 2
2020;95;La promesse de l'aube;Barbier, Eric;Paris : Pathé, 2018;PROM;CABANIS;PROM;A;-

Processing:

{
    "top10_all_years_all_cat1": {
        "question": "Top ten most popular items overall",
        "result": [
            {
                "Item_ID": "Le Journal de Mickey --- -",
                "Nbre de prêts": 28857,
                "Cat 1": "E"
            }
            ]
    }
}

• 'ãa' → 'â'
• 'ãe' → 'ê'
• 'ãi' → 'î'
• 'ão' → 'ô'
• 'ãu' → 'û'
• 'âe' → 'é'
• 'áa' → 'à'
• 'áe' → 'è'
• 'ðc' → 'ç'

Script layout (high-level):

 LoanAnalysis Module
 ├─ Config (dataclass)
 ├─ Utilities
 │  ├─ find_first_matching_file(pattern)
 │  ├─ detect_encoding(filepath, sample_bytes=200)
 │  ├─ fix_line(line)
 │  └─ apply_replacements(val, repl)
 ├─ LoanAnalysis (class)
 │  ├─ load_and_clean_csv(filepath, encoding=None)
 │  ├─ aggregate_by(df, groupby_fields, key_field, value_field)
 │  ├─ top_n_from_agg(agg_df, value_field, top_n)
 │  ├─ group_top_n(df, groupby_fields, key_field, value_field, top_n)
 │  ├─ _build_pivot(df, index, columns, values)
 │  ├─ compute_trends(pivot_df, trend="progression", top_n=None)
 │  ├─ compute_trend_by_group(df, group_field, value_field, trend)
 │  ├─ compute_sudden_disappearances(pivot_df, top_n=None)
 │  ├─ compute_disappearances_by_group(df, group_field, value_field)
 │  ├─ attach_cat1(record)
 │  ├─ update_records_with_cat(records)
 │  ├─ flatten_top_lists(input_data)
 │  └─ run_all(df)
 └─ main(cfg=None)

Instantiate it with a Config object: analysis = LoanAnalysis(cfg)

Contributions are welcome! I appreciate your support: each contribution and feedback helps me grow and improve.

This project is intended as a practice on a real world use case, feel free to play with it. I'm open to any suggestion that will improve the code quality and deepen my software programming skills. If you'd like to contribute to this project, please fork the repository and submit a pull request with your changes.

This project is provided as-is, without warranty. Use at your own risk.

It is provided under a Creative Commons CC0 license. See the LICENSE file for details.

Big thanks to the Toulouse Metropolis open data portal team for making these datasets publicly available:

• top 500 books loans
• top 500 movies loans
• top 500 songs loans

They are provided under a Licence Ouverte v2.0 (Etalab) license.

Done in september 2025 by brk🂽.

じゃあまた