istat-census-data 1.4.1__tar.gz

istat_census_data-1.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Massimiliano Moraca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

istat_census_data-1.4.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: istat-census-data
+Version: 1.4.1
+Summary: Python package to download and process ISTAT census grid cell data for Italian population censuses (1991-2021)
+License: MIT
+License-File: LICENSE
+Keywords: istat,census,gis,geospatial,italy,demographics,population
+Author: Massimiliano Moraca
+Author-email: gis.massimilianomoraca@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Italian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Dist: chardet (>=5.2.0,<6.0.0)
+Requires-Dist: geopandas (>=1.0.1,<2.0.0)
+Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
+Requires-Dist: requests (>=2.32.0,<3.0.0)
+Requires-Dist: tqdm (>=4.66.5,<5.0.0)
+Requires-Dist: xlrd (>=2.0.1,<3.0.0)
+Project-URL: Documentation, https://maxdragonheart.github.io/istat-census-data/
+Project-URL: Homepage, https://maxdragonheart.github.io/istat-census-data/
+Project-URL: Repository, https://github.com/MaxDragonheart/istat-census-data
+Description-Content-Type: text/markdown
+
+# ISTAT Cell Data
+
+[![CI](https://github.com/MaxDragonheart/istat-census-data/actions/workflows/ci.yml/badge.svg)](https://github.com/MaxDragonheart/istat-census-data/actions/workflows/ci.yml)
+[![Documentation](https://github.com/MaxDragonheart/istat-census-data/actions/workflows/docs.yml/badge.svg)](https://maxdragonheart.github.io/istat-census-data/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/istat-census-data.svg)](https://badge.fury.io/py/istat-census-data)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Con **ISTAT Cell Data** puoi ottenere facilmente il set di dati riferiti ai censimenti ISTAT in cui sono stati
+rilasciati anche i dati delle celle censuarie.
+
+E' possibile scaricare e processare i dati dal 1991 al 2021.
+
+## Installazione
+
+```bash
+pip install istat-census-data
+```
+
+## Rinomina del progetto e manutenzione
+
+`istat-census-data` è la distribuzione PyPI mantenuta a partire dalla versione 1.4.0
+ed è la continuazione del precedente progetto `istatcelldata`.
+
+Il nome della distribuzione PyPI è `istat-census-data`, mentre il package Python
+da importare resta `istatcelldata`:
+
+```python
+import istatcelldata
+```
+
+La vecchia distribuzione/repository `istatcelldata` non è più mantenuta e non riceverà
+nuove release. Aggiorna le dipendenze di installazione da `istatcelldata` a
+`istat-census-data`; il codice Python esistente può continuare a usare
+`import istatcelldata`.
+
+## Pubblicazione release
+
+Le nuove release PyPI devono essere pubblicate da GitHub Actions tramite PyPI Trusted
+Publishing. Il workflow di rilascio non usa token PyPI salvati in locale o nei GitHub
+secrets.
+
+Prima della prima pubblicazione, configura su PyPI un pending Trusted Publisher che
+corrisponda al workflow di rilascio del repository e usa un environment GitHub protetto
+per approvare la pubblicazione.
+
+Per pubblicare, crea una GitHub Release sul tag che corrisponde alla versione in
+`pyproject.toml`. Lo script `release.sh` resta solo una verifica locale pre-rilascio:
+non pubblica più su PyPI e non effettua il deploy della documentazione.
+
+!!! INFO
+
+    Questo progetto non è collegato ad ISTAT nè supportato da ISTAT ed è una iniziativa autonoma di [Massimiliano Moraca](https://massimilianomoraca.me/).
+
+Questo repository è stato creato grazie a [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material) e [mkdocstring](https://mkdocstrings.github.io/).
+

istat_census_data-1.4.1/README.md

@@ -0,0 +1,55 @@
+# ISTAT Cell Data
+
+[![CI](https://github.com/MaxDragonheart/istat-census-data/actions/workflows/ci.yml/badge.svg)](https://github.com/MaxDragonheart/istat-census-data/actions/workflows/ci.yml)
+[![Documentation](https://github.com/MaxDragonheart/istat-census-data/actions/workflows/docs.yml/badge.svg)](https://maxdragonheart.github.io/istat-census-data/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/istat-census-data.svg)](https://badge.fury.io/py/istat-census-data)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Con **ISTAT Cell Data** puoi ottenere facilmente il set di dati riferiti ai censimenti ISTAT in cui sono stati
+rilasciati anche i dati delle celle censuarie.
+
+E' possibile scaricare e processare i dati dal 1991 al 2021.
+
+## Installazione
+
+```bash
+pip install istat-census-data
+```
+
+## Rinomina del progetto e manutenzione
+
+`istat-census-data` è la distribuzione PyPI mantenuta a partire dalla versione 1.4.0
+ed è la continuazione del precedente progetto `istatcelldata`.
+
+Il nome della distribuzione PyPI è `istat-census-data`, mentre il package Python
+da importare resta `istatcelldata`:
+
+```python
+import istatcelldata
+```
+
+La vecchia distribuzione/repository `istatcelldata` non è più mantenuta e non riceverà
+nuove release. Aggiorna le dipendenze di installazione da `istatcelldata` a
+`istat-census-data`; il codice Python esistente può continuare a usare
+`import istatcelldata`.
+
+## Pubblicazione release
+
+Le nuove release PyPI devono essere pubblicate da GitHub Actions tramite PyPI Trusted
+Publishing. Il workflow di rilascio non usa token PyPI salvati in locale o nei GitHub
+secrets.
+
+Prima della prima pubblicazione, configura su PyPI un pending Trusted Publisher che
+corrisponda al workflow di rilascio del repository e usa un environment GitHub protetto
+per approvare la pubblicazione.
+
+Per pubblicare, crea una GitHub Release sul tag che corrisponde alla versione in
+`pyproject.toml`. Lo script `release.sh` resta solo una verifica locale pre-rilascio:
+non pubblica più su PyPI e non effettua il deploy della documentazione.
+
+!!! INFO
+
+    Questo progetto non è collegato ad ISTAT nè supportato da ISTAT ed è una iniziativa autonoma di [Massimiliano Moraca](https://massimilianomoraca.me/).
+
+Questo repository è stato creato grazie a [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material) e [mkdocstring](https://mkdocstrings.github.io/).

istat_census_data-1.4.1/istatcelldata/__init__.py

@@ -0,0 +1,49 @@
+"""ISTAT Cell Data - Italian census cell data processing library.
+
+ISTAT Cell Data provides easy access to Italian National Institute of Statistics
+(ISTAT) census data, including census grid cell datasets from complete population
+censuses.
+
+This library allows you to download and process census data from 1991 to 2021,
+including demographic data and geographic information (shapefiles, administrative
+boundaries) for census sections across Italy.
+"""
+
+__version__ = "1.3.0"
+__author__ = "Massimiliano Moraca"
+__email__ = "gis.massimilianomoraca@gmail.com"
+
+# Expose main modules for convenient imports
+from istatcelldata import census1991, census2001, census2011, census2021, executor
+from istatcelldata.config import DOWNLOAD_RAW_DATA, census_data
+from istatcelldata.data import preprocess_data
+from istatcelldata.download import download_base
+from istatcelldata.executor.process import finalize_census_data
+from istatcelldata.geodata import (
+    preprocess_geodata,
+    read_administrative_boundaries,
+    read_census,
+)
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    "__email__",
+    # Submodules
+    "census1991",
+    "census2001",
+    "census2011",
+    "census2021",
+    "executor",
+    # Configuration
+    "census_data",
+    "DOWNLOAD_RAW_DATA",
+    # Main functions
+    "download_base",
+    "preprocess_data",
+    "read_administrative_boundaries",
+    "read_census",
+    "preprocess_geodata",
+    "finalize_census_data",
+]

istat_census_data-1.4.1/istatcelldata/census1991/download.py

@@ -0,0 +1,121 @@
+import logging
+from pathlib import Path
+
+from istatcelldata.census1991.utils import census_trace, read_xls
+from istatcelldata.census2011.download import download_administrative_boundaries, download_geodata
+from istatcelldata.census2011.download import download_data as dwn
+from istatcelldata.config import CENSUS_DATA_FOLDER, DATA_FOLDER, PREPROCESSING_FOLDER
+from istatcelldata.utils import get_census_dictionary, remove_files
+
+# Define the logger as a global variable
+logger = logging.getLogger(__name__)
+
+
+def download_data(output_data_folder: Path, census_year: int) -> Path:
+    """Download, organize, and process census data for a specific year.
+
+    This function manages the complete workflow for acquiring census data from
+    source through to producing final CSV files. The following operations are
+    performed:
+
+    1. Retrieval of the dictionary of links for the census year.
+    2. Download of raw data via the `dwn()` function.
+    3. Creation of the output folder structure.
+    4. Identification and reading of `.xls` files.
+    5. Conversion of Excel files to CSV.
+    6. Extraction of tracking metadata (codifications) from the first available file.
+    7. Removal of original Excel files.
+
+    Args:
+        output_data_folder: Root folder path where downloaded data will be saved.
+        census_year: Reference year for the census data to process.
+
+    Returns:
+        Path to the folder containing the downloaded and processed census data.
+
+    Raises:
+        Exception: If no `.xls` file is found in the data folder.
+
+    Note:
+        Conversion from XLS to CSV is performed via the `read_xls()` function.
+        Dataset tracking is performed only on the first XLS file found.
+        XLS files are removed at the end of the process to reduce disk space usage.
+    """
+    link_dict = get_census_dictionary(census_year=census_year)
+    census_code = link_dict[f"census{census_year}"]["census_code"]
+
+    data_folder = dwn(output_data_folder=output_data_folder, census_year=census_year)
+
+    final_folder = data_folder.joinpath(DATA_FOLDER, CENSUS_DATA_FOLDER)
+    Path(final_folder).mkdir(parents=True, exist_ok=True)
+
+    # Esegui il tracciamento dei dati dal primo file XLS trovato
+    files_list = list(data_folder.rglob("*.xls"))
+    if not files_list:
+        logging.error("Nessun file XLS trovato nella cartella dei dati.")
+        raise Exception("Nessun file XLS trovato per il tracciamento.")
+
+    logging.info("Estrazione dei dati censuari in formato xls e conversione in csv.")
+    # Convert xls to csv
+    for file_path in files_list:
+        read_xls(file_path=file_path, census_code=census_code, output_path=final_folder)
+
+    first_element = files_list[0]
+    logging.info(f"Extracting data trace from file {first_element}")
+    census_trace(file_path=first_element, year=census_year, output_path=final_folder)
+
+    # Remove unnecessary XLS files
+    logging.info(f"Removing XLS files from folder {data_folder}")
+    remove_files(files_path=files_list)
+
+    logging.info(f"Census data download completed and saved in {data_folder}")
+    return data_folder
+
+
+def download_all_census_data_1991(
+    output_data_folder: Path, region_list: list[int] | None = None
+) -> Path:
+    """Download complete census and geographic dataset for the 1991 Census.
+
+    This function coordinates all necessary operations to obtain census data
+    and geographic information associated with the 1991 Census. It enables
+    downloading of:
+
+    - Tabular census data
+    - Geodata specific to one or more regions
+    - Official administrative boundaries
+
+    If no value is provided for `region_list`, geodata for all regions is
+    downloaded.
+
+    Args:
+        output_data_folder: Main path where all downloaded and processed data
+            will be saved.
+        region_list: List containing region codes or names for which to download
+            geodata. If empty, all available regions are considered.
+
+    Returns:
+        Path to the root folder containing the downloaded data.
+
+    Note:
+        This function operates exclusively on the 1991 Census.
+        It uses support functions such as `download_data()`,
+        `download_geodata()`, and `download_administrative_boundaries()`.
+        The necessary folder structure is created automatically.
+    """
+    selected_regions = [] if region_list is None else list(region_list)
+
+    # Make data folder
+    data_folder = output_data_folder.joinpath(PREPROCESSING_FOLDER)
+    Path(data_folder).mkdir(parents=True, exist_ok=True)
+
+    # Download data
+    download_data(output_data_folder=data_folder, census_year=1991)
+
+    # Download geodata
+    download_geodata(output_data_folder=data_folder, region_list=selected_regions, census_year=1991)
+
+    # Download administrative boundaries
+    download_administrative_boundaries(output_data_folder=data_folder, census_year=1991)
+
+    return output_data_folder

istat_census_data-1.4.1/istatcelldata/census1991/process.py

@@ -0,0 +1,136 @@
+import logging
+from pathlib import Path
+
+import pandas as pd
+
+from istatcelldata.geodata import read_administrative_boundaries
+
+# Define the logger as a global variable
+logger = logging.getLogger(__name__)
+
+
+def add_administrative_info(
+    census_data: pd.DataFrame,
+    regions_data_path: Path,
+    regions_target_columns: list,
+    provinces_data_path: Path,
+    provinces_target_columns: list,
+    municipalities_data_path: Path,
+    municipalities_target_columns: list,
+) -> pd.DataFrame:
+    """Enrich census data with administrative information (municipalities, provinces, regions).
+
+    This function integrates corresponding administrative codes and names into the
+    census data, sourced from three external datasets: regional, provincial, and
+    municipal boundaries.
+
+    The logical workflow includes:
+    1. Standardization of census dataset column names.
+    2. Reading of administrative datasets (regions, provinces, municipalities).
+    3. Merge of municipalities with provinces.
+    4. Merge of result with regions.
+    5. Final join with census dataset on the municipal key (`PRO_COM`).
+    6. Cleanup and renaming of final administrative columns.
+
+    Args:
+        census_data: Census dataset to which administrative information will be added.
+        regions_data_path: Path to the file containing regional data.
+        regions_target_columns: List of columns to extract from the regional dataset
+            (the first column is used as the index).
+        provinces_data_path: Path to the file containing provincial data.
+        provinces_target_columns: List of columns to extract from the provincial dataset
+            (the first column is used as the index).
+        municipalities_data_path: Path to the file containing municipal data.
+        municipalities_target_columns: List of columns to extract from the municipal
+            dataset (the first column is used as the index).
+
+    Returns:
+        Census DataFrame enriched with administrative information on municipalities,
+        provinces, and regions.
+
+    Note:
+        Administrative codes used for merges are assumed to be:
+        `PRO_COM` (municipality), `COD_PROV`/`COD_PRO` (province), `COD_REG` (region).
+        The function uses `read_administrative_boundaries()` to load and filter
+        administrative datasets.
+    """
+    logging.info("Starting to add administrative information to census data.")
+
+    # Convert census column names to uppercase for uniformity
+    census_data.columns = census_data.columns.str.upper()
+    logging.info("Census dataset column names converted to uppercase.")
+
+    # Read regional administrative boundaries
+    logging.info(f"Reading regional data from {regions_data_path}")
+    regions_data = read_administrative_boundaries(
+        file_path=regions_data_path,
+        target_columns=regions_target_columns,
+        index_column=regions_target_columns[0],
+    )
+    if isinstance(regions_data, Path):
+        raise ValueError("Expected DataFrame but got Path from read_administrative_boundaries")
+    regions_data.reset_index(inplace=True)
+    logging.info(f"Regional data read successfully. {len(regions_data)} records found.")
+
+    # Read provincial administrative boundaries
+    logging.info(f"Reading provincial data from {provinces_data_path}")
+    provinces_data = read_administrative_boundaries(
+        file_path=provinces_data_path,
+        target_columns=provinces_target_columns,
+        index_column=provinces_target_columns[0],
+    )
+    if isinstance(provinces_data, Path):
+        raise ValueError("Expected DataFrame but got Path from read_administrative_boundaries")
+    provinces_data.reset_index(inplace=True)
+    logging.info(f"Provincial data read successfully. {len(provinces_data)} records found.")
+
+    # Read municipal administrative boundaries
+    logging.info(f"Reading municipal data from {municipalities_data_path}")
+    municipalities_data = read_administrative_boundaries(
+        file_path=municipalities_data_path,
+        target_columns=municipalities_target_columns,
+        index_column=municipalities_target_columns[0],
+    )
+    if isinstance(municipalities_data, Path):
+        raise ValueError("Expected DataFrame but got Path from read_administrative_boundaries")
+    municipalities_data.reset_index(inplace=True)
+    logging.info(f"Municipal data read successfully. {len(municipalities_data)} records found.")
+
+    # Merge municipal data with provincial data
+    logging.info("Starting merge between municipal and provincial data.")
+    add_provinces = pd.merge(
+        left=municipalities_data, right=provinces_data, how="left", on="COD_PROV"
+    )
+    logging.info(
+        f"Merge between municipalities and provinces completed. "
+        f"{len(add_provinces)} resulting records."
+    )
+
+    # Merge resulting data with regional data
+    logging.info("Starting merge between municipal-provincial and regional data.")
+    add_regions = pd.merge(left=add_provinces, right=regions_data, how="left", on="COD_REG")
+    logging.info(
+        f"Merge between municipalities, provinces and regions completed. "
+        f"{len(add_regions)} resulting records."
+    )
+
+    # Final merge of census data with added administrative information
+    logging.info("Starting final merge with census data.")
+    add_municipalities = pd.merge(left=census_data, right=add_regions, how="left", on="PRO_COM")
+    logging.info(f"Final merge completed. {len(add_municipalities)} records in final dataset.")
+    columns_to_drop = [column for column in ["COD_PRO", "PRO_COM"] if column in add_municipalities]
+    add_municipalities.drop(columns=columns_to_drop, inplace=True)
+    add_municipalities.rename(
+        columns={
+            "COD_COM": "CODCOM",
+            "COD_PROV": "CODPRO",
+            "COD_REG": "CODREG",
+            "DEN_PROV": "PROVINCIA",
+            "DEN_REG": "REGIONE",
+        },
+        inplace=True,
+    )
+
+    logging.info("Addition of administrative information completed successfully.")
+
+    return add_municipalities

istat_census_data-1.4.1/istatcelldata/census1991/utils.py

@@ -0,0 +1,154 @@
+import logging
+from pathlib import Path
+
+import pandas as pd
+import xlrd
+from tqdm import tqdm
+
+
+def read_xls(
+    file_path: Path,
+    census_code: str,
+    output_path: Path | None = None,
+) -> pd.DataFrame | Path:
+    """Read an Excel file (.xls) and return a DataFrame or save data as CSV.
+
+    This function opens an Excel file in `.xls` format, automatically selects
+    the first useful sheet (excluding any sheets named "Metadati"), extracts
+    the sheet rows, constructs a pandas DataFrame, and sets as index the column
+    corresponding to the provided census code.
+
+    If an output path is specified, the DataFrame is saved in CSV format;
+    otherwise, it is returned directly.
+
+    Args:
+        file_path: Path to the Excel file to read.
+        census_code: Name of the column to use as the DataFrame index
+            (e.g., ISTAT municipality code).
+        output_path: Path to the folder where the resulting CSV will be saved.
+            If None, the DataFrame is returned without saving.
+
+    Returns:
+        A DataFrame containing data read from the Excel file if `output_path`
+        is None, or the path to the saved CSV file if `output_path` is specified.
+
+    Raises:
+        FileNotFoundError: If the specified file does not exist.
+        xlrd.XLRDError: If an error occurs while reading the Excel file.
+        Exception: For any unexpected error during parsing or saving.
+    """
+    try:
+        logging.info(f"Lettura del file Excel da {file_path}")
+
+        # Legge il file Excel
+        read_data = xlrd.open_workbook(file_path)
+
+        # Estrae il nome del foglio, ignorando 'Metadati'
+        sheet_list = read_data.sheet_names()
+        if "Metadati" in sheet_list:
+            sheet_list.remove("Metadati")
+        sheet_name = sheet_list[0]
+        get_sheet = read_data.sheet_by_name(sheet_name)
+
+        # Estrae i dati dal foglio
+        dataset = []
+        for row_id in tqdm(range(get_sheet.nrows), desc="Lettura righe..."):
+            dataset.append(get_sheet.row_values(row_id))
+
+        # Crea il DataFrame
+        df_columns = [column_name.lower() for column_name in dataset[0]]
+        df_data = dataset[1:]
+        df = pd.DataFrame(data=df_data, columns=df_columns)
+
+        # Imposta il tipo di dati e l'indice
+        df = df.astype(int)
+        df.set_index(census_code, inplace=True)
+        df.sort_index(inplace=True)
+
+        # Se non viene fornito un percorso di output, restituisce il DataFrame
+        if output_path is None:
+            return df
+        else:
+            file_name = file_path.stem.split("\\")[1]
+            logging.info(f"Salvataggio dei dati in {output_path.joinpath(f'{file_name}.csv')}")
+            df.to_csv(path_or_buf=output_path.joinpath(f"{file_name}.csv"), sep=";")
+            return output_path.joinpath(
+                f"{file_name}.csv"
+            )  # Restituisce il percorso del file CSV salvato
+
+    except FileNotFoundError as e:
+        logging.error(f"Excel file not found: {file_path}")
+        raise e
+    except xlrd.XLRDError as e:
+        logging.error(f"Error reading Excel file: {str(e)}")
+        raise e
+    except Exception as e:
+        logging.error(f"Error reading Excel file or saving data: {str(e)}")
+        raise e
+
+
+def census_trace(
+    file_path: Path, year: int, output_path: Path | None = None
+) -> pd.DataFrame | Path:
+    """Extract metadata trace record from the "Metadati" sheet of an Excel file.
+
+    This function accesses the sheet named **"Metadati"** in an Excel file
+    related to census data, extracts the fundamental columns (field name and
+    description), and constructs a pandas DataFrame with an index based on the
+    field name. If an output path is provided, the trace record is also saved
+    in CSV format.
+
+    Args:
+        file_path: Path to the Excel file from which to extract metadata.
+        year: Reference year for the census, used to generate the output file name.
+        output_path: Path to the folder where the trace record CSV will be saved.
+            If None, a DataFrame is returned directly.
+
+    Returns:
+        Path to the generated CSV file if `output_path` is provided, or a pandas
+        DataFrame containing the metadata trace record if `output_path` is None.
+
+    Raises:
+        FileNotFoundError: If the specified Excel file does not exist.
+        xlrd.XLRDError: If an error occurs while opening or reading the Excel file.
+        Exception: For any unexpected errors during parsing or saving.
+    """
+    try:
+        logging.info(f"Lettura dei dati da {file_path}")
+        read_data = xlrd.open_workbook(file_path)
+
+        get_sheet = read_data.sheet_by_name("Metadati")
+
+        dataset = []
+        for row_id in range(get_sheet.nrows):
+            dataset.append(get_sheet.row_values(row_id)[:2])
+        dataset = dataset[7:]  # Ignora le prime 7 righe
+
+        # Crea le colonne del DataFrame
+        df_columns = [column_name for column_name in dataset[0]]
+
+        # Crea i dati del DataFrame
+        df_data = dataset[1:]
+        df = pd.DataFrame(data=df_data, columns=df_columns)
+        df.set_index("NOME CAMPO", inplace=True)
+
+        logging.info("Dati letti con successo.")
+
+        if output_path is None:
+            return df
+        else:
+            file_name = f"tracciato_{year}_sezioni.csv"
+            file_path = output_path.joinpath(file_name)
+            logging.info(f"Salvataggio dei dati in {file_path}")
+            df.to_csv(path_or_buf=file_path, sep=";")
+            return file_path  # Restituisce il percorso del file CSV salvato
+
+    except FileNotFoundError as e:
+        logging.error(f"Excel file not found: {file_path}")
+        raise e
+    except xlrd.XLRDError as e:
+        logging.error(f"Error reading Excel file: {str(e)}")
+        raise e
+    except Exception as e:
+        logging.error(f"Error reading Excel file or saving data: {str(e)}")
+        raise e