FileMigrator

Ce fichier contient la classe FileMigrator permettant de lire un dossier de résultat de PALMTracer depuis Metamorph vers le format actuel.

class Link(old: str, new: str)

Bases : NamedTuple

Structure permettant le lien entre nouvelle et ancienne nomenclature.

Paramètres:

• old (str) – Ancien nom de fichier.

• new (str) – Nouveau nom de fichier.

old: str

Alias for field number 0

new: str

Alias for field number 1

class FileMigrator

Bases : object

Outil de migration d’un dossier de traitement PALMTracer (ancien format Metamorph) vers le format Python plus récent.

Le principe est :

• l’utilisateur pointe un dossier d’entrée (un dossier se terminant par .PT) ;

• analyze() inspecte les fichiers et les classes par type (loc/trc/MSD/…) ;

• migrate() crée un dossier de sortie et exécute ensuite les conversions nécessaires.

Note

Cette classe ne modifie pas le dossier d’entrée : elle lit depuis input_folder et écrit dans output_folder.

Attributs :

• input_folder: Dossier source sélectionné par l’utilisateur.

• output_folder: Dossier cible où seront écrits les fichiers convertis.

• files: Dictionnaire {type: [paths...]} rempli par analyze().

• suffix: Suffixe optionnel ajouté au nom du dossier de sortie.

• meta: Métadonnées globales du jeu de données. Une ligne initialisée à -1 qui sera mis à jour avec durant la migration des fichiers.

FILES_LINK: dict[str, Link]

Correspondances entre les anciens noms et les nouveaux.

input_folder: Path

Dossier source sélectionné par l’utilisateur.

output_folder: Path

Dossier cible où seront écrits les fichiers convertis.

files: dict[str, list[Path]]

Dictionnaire {type: [paths...]} rempli par analyze().

suffix: str = ''

Suffixe optionnel ajouté au nom du dossier de sortie.

meta: DataFrame

Métadonnées globales du jeu de données. Une ligne initialisée à -1 qui sera mis à jour avec durant la migration des fichiers.

open(folder: Path)

Sélectionne le dossier d’entrée contenant les résultats PALMTracer.

Le dossier Metamorph / PALMTracer est généralement nommé <monfichier>.PT. Si ce n’est pas le cas, un avertissement est affiché (sans empêcher l’analyse).

Paramètres:

folder (Path) – Chemin du dossier à analyser.

Lève:

• FileNotFoundError – Si folder n’existe pas.

• NotADirectoryError – Si folder n’est pas un dossier.

• ValueError – Si folder ne finit pas par .PT comme un dossier de sortie type de PALMTracer sur Metamorph.

analyze()

Analyse input_folder et classe les fichiers reconnus par catégorie.

Effets de bord :

• réinitialise files puis la remplit avec des chemins trouvés.

• ne lit pas le contenu des fichiers (uniquement leur présence).

Lève:

RuntimeError – Si aucun dossier n’a été sélectionné via open().

migrate()

Lance la migration vers le format récent.

Règle de nommage du dossier de sortie : - si l’entrée est monfichierdebase.PT alors sortie monfichierdebase_PALM_Tracer

Avertissement

Cette méthode suppose que open() et analyze() ont déjà été appelées.

Lève:

RuntimeError – Si input_folder n’est pas défini.

make_meta()

Écriture du fichier meta uniquement si au moins une valeur est différente de -1.

update_meta(column: str, v: int | float)

Mets à jour l’objet meta et vérifie si une valeur différente est présente.

Paramètres:

• column (str) – Colonne à mettre à jour

• v (int | float) – Valeur à insérer

migrate_localization()

Migre le fichier de localisations PALMTracer vers le format courant.

Cette méthode :

• lit le fichier locPALMTracer.txt s’il est présent

• extrait les métadonnées globales (dimensions, calibration temporelle et spatiale)

• mets à jour meta via update_meta()

• renomme et complète les colonnes selon FILES_COLUMNS["Localization"]

• écrit le fichier CSV converti dans output_folder.

Le fichier de sortie est nommé : <new_name>-<timestamp>.csv où new_name correspond à FILES_LINK["loc"].new.

migrate_tracks()

Migre le fichier de tracking PALMTracer vers le format courant.

Cette méthode :

• lit le fichier trcPALMTracer.txt s’il est présent

• extrait et harmonise les métadonnées globales (image, calibration)

• renomme et complète les colonnes selon FILES_COLUMNS["Tracking"]

• écrit le fichier CSV converti dans output_folder.

Le fichier de sortie est nommé : <new_name>-<timestamp>.csv où new_name correspond à FILES_LINK["trc"].new.

migrate_astigmatism_3d_model()

Migre le fichier de modèle d’astigmatisme 3D PALMTracer.

Cette méthode :

• lit le fichier 3DFit.txt s’il est présent

• assigne explicitement les noms de colonnes et les indices de lignes à partir de FILES_COLUMNS["Astigmatism 3D Model"] et MODEL_ROWS

• écrit le modèle sous forme de CSV dans output_folder.

Le fichier de sortie est nommé : <new_name>-<timestamp>.csv où new_name correspond à FILES_LINK["A3D"].new.

migrate_tracks_msd()

Migre le fichier MSD (Mean Square Displacement) PALMTracer.

Cette méthode :

• lit un fichier à structure irrégulière (nombre de colonnes variable par ligne)

• supprime la colonne ROI (première colonne)

• renomme les colonnes sous la forme : Track, <metric> 1, <metric> 2, ..., <metric> N ;

• écrit le fichier CSV converti dans output_folder.

Le nom de la métrique est issu de FILES_COLUMNS["MSD"]["columns"].

Le fichier de sortie est nommé : <new_name>-<timestamp>.csv où new_name correspond à FILES_LINK["MSD"].new.

migrate_tracks_instant_diffusion()

Migre le fichier de diffusion instantanée PALMTracer.

Cette méthode :

• lit un fichier à structure irrégulière (nombre de colonnes variable par ligne)

• supprime la colonne ROI (première colonne)

• renomme les colonnes sous la forme : Track, <metric> 1, <metric> 2, ..., <metric> N ;

• écrit le fichier CSV converti dans output_folder.

Le nom de la métrique est issu de FILES_COLUMNS["InD"]["columns"].

Le fichier de sortie est nommé : <new_name>-<timestamp>.csv où new_name correspond à FILES_LINK["InD"].new.

migrate_tracks_fit()

Migre le fichier d’ajustement de trajectoires PALMTracer.

Cette méthode :

• lit le fichier trcPALMTracer-Full-D.txt

• neutralise la colonne ROI (remplacée par une valeur constante)

• corrige l’ordre des colonnes (ROI / Track)

• détecte automatiquement le mode d’ajustement en fonction du nombre de colonnes

• applique les noms de colonnes appropriés à partir de FILES_COLUMNS

• écrit le fichier CSV converti dans output_folder.

Le mode d’ajustement est déterminé comme suit :

• 9 colonnes → Fit mode 1.

• 10 colonnes → Fit mode 2.

• 11 colonnes → Fit mode 3.

Avertissement

Toute incohérence sur le nombre de colonnes peut conduire à un mauvais mode d’ajustement.

static open_old_file(file: Path, header: bool = True, skiprows: int = 2, sep: str = '\t') → tuple[DataFrame, list[str]]

Ouvre un fichier PALMTracer (MetaMorph) au format texte tabulé.

Le fichier est supposé structuré de la façon suivante :

• skiprows premières lignes : informations globales (dimensions, calibration, options…)

• ligne suivante (optionnelle) : titres des colonnes

• reste du fichier : données tabulaires

Paramètres:

• file (Path) – Chemin vers le fichier PALMTracer à ouvrir.

• header (bool) – Indique si une ligne de titres de colonnes est présente après les lignes d’en-tête.

• skiprows (int) – Nombre de lignes d’informations à lire et à conserver avant les données.

• sep (str) – Séparateur de colonnes utilisé dans le fichier.

Renvoie:

Tuple (dataframe, header_lines) avec les données numériques et la liste des lignes d’informations brutes (sans \n).

Lève:

FileNotFoundError – Si le fichier n’existe pas.

Type renvoyé:

tuple[DataFrame, list[str]]

static open_old_irregular_file(file: Path, skiprows: int = 2, sep: str = '\t') → tuple[DataFrame, list[str]]

Ouvre un fichier PALMTracer (MetaMorph) au format texte tabulé, en tolérant les lignes avec un nombre de colonnes variable.

Si certaines lignes n’ont pas le même nombre de colonnes, la fonction : - détecte le nombre maximal de colonnes, - complète les lignes plus courtes avec des valeurs manquantes (NaN), - tronque les lignes plus longues à la largeur max (rare, mais protège).

Paramètres:

• file (Path) – Chemin vers le fichier PALMTracer à ouvrir.

• skiprows (int) – Nombre de lignes d’informations à lire et à conserver avant les données.

• sep (str) – Séparateur de colonnes utilisé dans le fichier.

Renvoie:

Tuple (dataframe, header_lines).

Lève:

• FileNotFoundError – Si le fichier n’existe pas.

• ValueError – Si le fichier ne contient pas assez de lignes d’en-tête.

Type renvoyé:

tuple[DataFrame, list[str]]

static column_migrator(name: str) → str

Retourne une clé actuelle à partir d’un nom de colonne ancien.

Paramètres:

name (str) – Nom de la colonne en entrée

Renvoie:

Nom de la nouvelle colonne

Type renvoyé:

str

dataframe_migrator(data: DataFrame, target_cols: list[str]) → DataFrame

Normalise un DataFrame PALMTracer vers un schéma de colonnes cible.

Cette méthode :

• renomme les colonnes existantes à l’aide de column_migrator()

• ignore les colonnes non reconnues

• ajoute les colonnes manquantes initialisées à 0

• retourne le DataFrame réordonné selon target_cols.

Paramètres:

• data (DataFrame) – DataFrame d’entrée issue du format PALMTracer.

• target_cols (list[str]) – Liste ordonnée des colonnes attendues dans le format cible.

Renvoie:

DataFrame conforme au schéma cible.

Type renvoyé:

DataFrame