Moxie - masterand în informatică, încerc să înțeleg de ce uneori anexele unui proiect de diplomă par, pur și simplu, să existe ca să existe. La început povestea părea simplă: „pune în anexă toate fișierele alea pe care nu încape în corpul lucrării". După prima respirație de după susținere însă, mi-am dat seama că anexele au o misiune reală: să dea cititorului posibilitatea să reproducă, să verifice și să umanizeze propriul meu traseu de cercetare.
Pe scurt, ce conțin cu adevărat anexele pentru un proiect de diplomă? În felul meu de a vedea, răspunsul nu e doar „ce am avut eu caiet" sau „ce am rulat în laborator". E mai mult despre a oferi un suport tehnic și metodologic care să justifice deciziile din corpul lucrării. De exemplu, datele brute sau simulările: un fișier CSV cu 1200 de înregistrări, cu descriere clară a coloanelor, explicații despre transformările aplicate (cum s-au tratat valorile lipsă, de ce s-au ales anumite filtre) și un raport scurt despre limitările setului de date. În cazul unui studiu cantitativ, apare și un dataset cât de cât ireproducibil? atunci să menționezi exact sursa, condițiile de colectare, eventual acorduri de confidențialitate și, dacă e posibil, o versiune pseudonimizată.
Codul sursă e altă brigadă. Nu o lăsăm să se risipească în comentarii de proiect; includem fișierele esențiale: scripturi de preprocesare, implementarea algoritmului, notițe despre dependențe (un requirements.txt sau un environment.yml), poate un Dockerfile pentru reproducere, un README despre cum să rulezi totul pas cu pas. Am învățat că mulți cititori privesc anexele ca pe un manual de „cum să obții rezultatele din corpul lucrării" și de aceea claritatea e crucială: ordine, comentarii utile, exemple rapide despre input și output.
Instrumentele și materialele folosite merită o atenție aparte. Dacă ai folosit echipamente de laborator, seria de protocoale poate intra în anexă ca un jurnal tehnic: pașii de conformitate, parametrii de calibrare, versiuni de software pentru analiza datelor, fișiere de configurare a instrumentelor. Chestionarele, interviurile sau consimțămintele își găsesc locul în anexele metodologice, cu versiuni anonimizate, itinerarii etice și formulare de acorduri. În practică, am avut o anexă în care am atașat versiunea finală a chestionarului, un cod de etică al cercetării, precum și un sumar cu condițiile de confidențialitate pentru participanți.
În planul meu personal, anexele au fost o oglindă a rigurii și a clarității: un plan de reproducere detaliat, de la cum se instalează environment-ul până la modul în care se generează rezultatele. Am avut și un set de grafice și tabele suplimentare, suficiente să explice variațiile observate, dar suficient de concise încât să nu se suprapună peste prezentarea principală. Un exemplu concret: într-un proiect despre modele predictive, anexele conțineau o listă cu hiperparametri, desemnările de random seed, rezultatele complete pentru fiecare configurație testată și heatmap-ul erorilor, toate însoțite de un scurt ghid despre interpretarea lor.
Un alt element de valoare este reproducerea: un pachet de fișiere care să permită unui cititor să ridice exact aceleași rezultate în propriul mediu. Aici intră un README clar, pași simpli, instrucțiuni de instalare, eventual un script de rulare în linie de comandă, sau un notebook unde se poate urmări procesul de la date brute la rezultat final. E ca și cum angrenăm o mică cutie de instrumente ce poate fi adusă în fața unui evaluator fără a-l împinge să caute prin rețete ascunse în fișiere dispersate.
Desigur, există și o disciplină a anexelor: nu încărcăm în ele informații sensibile sau nejustificate. Nu adăugăm acolo datele totale ale participanților, dacă nu există de fapt consimțământ și o claritate despre utilizarea datelor; nu includem cod proprietar sau resurse licențiate fără permisiune; și, în toate, o bună practică este să legăm anexele de corpul lucrării prin referințe în cuprins, astfel încât cititorul să știe exact unde găsește ceea ce caută. Anexa nu este un depozit de „lucruri pe care nu știu unde să le pun", ci un suport pentru evidențierea metodei și a grefelor practice.
Mi-a fost mie greu să decid ce să includ sau ce să las în corp. Am învățat să clarific de la început scopul anexelor: reproducere, verificabilitate, transparență. În această lumină, anexele devin un partener al textului principal, nu un appendice oarecum secundar. Dacă ar fi să dau un sfat practic tuturor celor aflați în fața unei liste interminabile de fișiere, ar fi să definești în prealabil un „pachet de reproducere" și să păstrezi în anexă doar ceea ce e necesar pentru a reproduce rezultatele, evitând dublaje inutile.
Cum abordați voi anexele în proiectele voastre? Ce ați considerat indispensabil și ce ați lăsa în corpul principal? Vă interesează exemple concrete din lucrări reale sau doar experiențe personale legate de organizare și timp? Sunt curios să aflu cum gestionați echilibrul între detaliu tehnic în anexă și lizibilitatea generală a lucrării.
Felicitări pentru modul în care ai structur: clar, practic și cu grijă la cititor. Sunt complet de acord cu ideea ta că anexele nu sunt o saltea de rezolvat, ci un spațiu unde reproducerea devine posibilă. Îmi spune mult despre rigurozitatea ta dacă vezi anexele ca un partener al corpului principal, nu ca un depozit oarecum pustiu.
Iată cum încerc să tranșez lucrurile, din perspectiva mea, într-un fel care poate fi accesibil altor colegi care se luptă cu aceeași dilemă: cât să pui în corp și cât în anexă, cum să organizezi pachetul de reproducere, și cum să nu transformi anexele într-un monstru de întreținere.
Un cadru practic în trei paliere pentru anexele unui proiect de diplomă
- Pachetul de reproducere, ca obiect central
- README de reproducere: acest document ar trebui să poată ghida un cititor în 15-30 de minute prin pornire, rulare și obținerea rezultatelor de bază. Include comenzi clare de implementare, exemple de input/output, și o listă mică de verificări de sanity (de ex. o primă rulare cu un set de date redus).
- Environment și dependențe: un fișier de tip environment.yml sau requirements.txt, versiuni exacte ale librăriilor, cu note despre motivele alegerilor (de ce o anumită versiune, ce se întâmplă dacă se folosește o versiune mai nouă).
- Scripturi esențiale, nu tot istoricul că e "în proiect": pachetele principale, modulele cu logica, utilitare de preprocesare, scripturi de reproducere a rezultatelor. Dacă există un pipeline, prezintă-l într-un folder bine compartimentat (ex: src/, pipelines/, executabile/).
- Dockerfile sau un mic vigniet de reproducere pentru HPC: dacă e posibil, o imagine minimă care să pornească exact în aceeași manieră ca în studiu.
- Instrucțiuni pentru rulare în linie de comandă sau în notebook, cu exemple clare de input/output și o verificare de rezultat (ex: un hash sau un grafic de referință).
- Datele și definițiile
- Dicționar de date (data dictionary): descrieri clare ale câmpurilor, tipuri, scale, valori posibile, tratări pentru valorile lipsă, orice transformare efectuată în preprocesare.
- Sursa și etica datelor: sursa datelor, condițiile de colectare, eventuale acorduri și acorduri de confidențialitate. Dacă datele pot fi pseudonimizate, includ o descriere a metodei și a limitărilor.
- Măsuri de reproducibilitate a seturilor: dacă s-au creat subseturi, regulile pentru selecție, numerele de seed, orice procedură de randomizare. Dacă e necesar, poate exista un set de date de tip simulare/iris-like pentru a demonstra procesul fără date sensibile.
- Stuburi pentru date sensibile: dacă nu pot fi afișate, indică cum pot fi accesate în mod controlat (de exemplu, poate exista o versiune pseudonimizată sau un protocol de acces în cadrul instituției).
- Codul sursă, organizat, nu dispersat
- Dimensiuni clare: folderul principal ar trebui să conțină doar punți esențiale - preprocesare, antrenare/model, evaluare, utilitare. În corpul lucrării nu intră marea parte din cod, ci referințe clare către locația lui.
- Notițe despre dependențe și config: fișierul de configurare cu parametri-cheie, descrieri despre alegerea lor (de ce anume hiperparametri, ce efecte au).
- Teste și exemple mici: dacă simți, include o suită de teste minimale cu date mici, ca să se valideze fluxul în 2-3 ore dintr-un calculator obișnuit.
- Elemente etice, legalitate, licențe
- Anexe dedicate eticii (dacă ai interviuri sau chestionare): versiuni anonimizate, formulare de consimțământ, copii ale acordurilor, sumare ale limitelor de confidențialitate.
- Licențe și drepturi de utilizare pentru cod și date: clarifică ce poate fi reutilizat, ce poate fi redistribuit, ce necesită permisiuni speciale.
- Legături clare între corp și anexă
- Referințe în cuprins spre Anexa A, Anexa B etc., cu o hartă mentală în care cititorul poate să-și dea seama ce găsește acolo și de ce.
- În corp, indică exact ce element are nevoie cititorul să verifice sau să înțeleagă din anexă (ex: „detalii despre hiperparametri în Anexa C, secțiunea C2").
- Organizare practică pentru timp și claritate
- Limitează repetitivitatea: dacă ceva e clar în corp, nu repeta în anexă. Anexa ar trebui să completeze, nu să repete pas-cu-pas ceea ce cititorul poate vedea deja în text.
- Oferă un "pachet minim reproducibil" ca standard: dacă cineva dorește doar să reînregistreze rezultatele principale, să aibă suficient pentru asta, iar restul poate fi consultat dacă vrea să aprofundeze.
- Împachetează în mod incremental: în cazul în care anexele devin mari, gândește-te la o mitralieră de sub-anexe etichetate (Anexa A1, A2, …) pentru a nu copleși, dar totuși a da ordine.
Experiențe personale și avertismente
- Am avut teze unde partea de reproducere era crucială pentru evaluare: în aceste cazuri, am alocat un pachet dedicat reproducibilității începutului lucrării, în timp ce corpul principal trata problema, interpretările și concluziile. Anexele conțineau configurările experimentale complete, lista de parametri, versiuni de software etc. A fost supravegheat ca să nu devină un "manual de reținut toate fișierele" ci să rămână o poartă către înțelegerea deciziilor mele.
- Un dezavantaj comun: volumul. Dacă aduni toate detaliile, anexele pot crește semnificativ. Soluția este să definești, de la început, ce „pachet de reproducere" vrei să ofere cititorului și să ții restul în corp, doar referențe scurte.
- Un alt risc: să incluzi informații sensibile sau proprietare. Aici regula de aur este claritatea asupra (i) ce poate fi văzut, (ii) ce poate fi reprodus, (iii) unde se poate accesa în condiții de confidențialitate.
Întrebări pentru comunitate
- Cum decideți voi ce se califică drept „intru în anexă" vs „merge în corp"? Aveți reguli interne sau un checklist util?
- Ați avut exemple concrete de lucrări reale sau doctorate unde ați apreciat anume imensa claritate a anexelor? Ce ar fi trebuit să fie diferit?
- Cum gestionați situațiile în care datele sunt sensibile sau limitate de confidențialitate, dar reproducerea ar crește în mod semnificativ valoarea lucrării?
Mi-ar plăcea să aud experiențe, exemple de pachete de reproducere pe care le-ați folosit și, dacă este cazul, fragmente din documentație pe care o considerați exemplare. Pentru mine, anexele nu sunt un „bonus" - ele sunt oglinda riguroasă a modului în care ai gândit metoda, iar organizarea lor bună poate face diferența între o lucrare cu adevărat reproducibilă și una cu potențial mare, dar greu verificabil.
Mulțumesc pentru această sumă de gânduri și pentru claritatea cu care ai conturat toate palierele. Da, oamenii adesea uită că anexele pot fi exact oglinda metodicii tale, nu doar un " depozit de fișiere". Îmi place cum ai împărțit în pachete, cum ai punctat reproducerea ca nucleu, dar și cum ai atenționat la riscurile supraîncărcării.
Câteva reflecții suplimentare, ca o evoluție firească a discuției, din experiența mea de masterand în informatică și din feedback-ul pe care l-am primit de la comisie:
Cum decid eu ce intră în corp vs. anexă
- Întrebarea tricky: ce informație este indispensabilă pentru înțelegerea deciziilor metodologice, a interpretării rezultatelor și a limitelor, fără să cazi în detalii de implementare care pot fi verificabile dar nu încântă cititorul? Dacă răspunsul e "nu, nu ar trebui să fie în corp", atunci e candidatul perfect pentru anexă.
- Regula de aur pe care încerc să o folosesc: dacă o concluzie sau un rezultat poate fi evaluat sau replicat fără să parcurgi o întreagă tirade de date și cod, atunci păstrează în corp; dacă reproducerea depinde de suflețelul procesului (configuri multiple, seturi de date, etape de preprocesare, teste de sensibilitate etc.), mută în anexă.
- O heuristica practică: pentru fiecare tabel sau grafic major din corp, întreabă-te dacă cititorul are nevoie să vadă detalii complete (versiuni, hiperparametri, seed-uri, transformări exacte) ca să înțeleagă de ce ai ajuns la concluzia X. Dacă da, marchează/impachetează în anexă și dă o referință scurtă în corp.
Checklist util pe care îl folosesc (sau l-aș recomanda ca punct de plecare)
- Scopul anexelor clar definit încă de la început: reproducibilitate, transparență, sau ambele. Dacă e doar transparență, gândește-te ce adăugă, de ce nu poate sta în corp.
- Structură modulară a anexelor: Anexa A (pachet de reproducere), Anexa B (date și definiții), Anexa C (configuri și parametri), Anexa D (aspecte etice și licențe), Anexa E (teste și exemple minime). Dacă devin mari, utilizează sub-anexe: A1, A2, etc.
- Legături ferme între corp și anexă: în corp, referințe clare către secțiunile/capitolele din Anexa A sau B; citează precis ce vor să vadă cititorul în anexă pentru a verifica o afirmație din corp.
- Pachetul de reproducere minim suficient: un README clar, un fișier de dependențe în versiuni exacte, un script de rulare în linie de comandă (sau un notebook cu pași reproducibili), un set mic de date de test sau un dataset sintetizat care reproduce procesul fără date sensibile.
- Controlul calității legate de cod și date: versiuni de software, liste de dependențe, hash-urile rezultatelor cheie, un mic set de „sanity checks" în README (de ex. un output de referință pentru o rulare de bază).
- Etică și licențe la locul potrivit: un paragraf în anexă (sau într-un document separat) despre consimțământ, anonimizare, acces la date, licențe de utilizare a codului și a datelor.
- Documentația de alegere a parametrilor: nu doar ce-a fost setat, ci de ce a fost ales a priori; dacă o versiune de librărie poate schimba rezultatul, notează-l clar și pune un „versus" într-un tabel scurt în anexă.
Experiențe personale relevante
- Am avut teze în care am încercat să păstrez corpul extrem de clar, iar anexele să funcționeze ca un manual de reproducere. Aceasta a redus timpul de evaluare pentru colegi și comisie, deoarece practica reproducibilității a devenit o parte integrantă a metodei mele, nu un capitol suplimentar.
- Un risc familiar: anexele cresc în volum peste măsură dacă le tratezi ca un "backup total" al tuturor fișierelor. Soluția pentru mine a fost să definesc de la început pachetul minim de reproducere și să adaug în anexă doar ce este necesar pentru a recrea rezultatele principale, plus secțiuni suplimentare ca salvare pentru cei care vor să se aventureze în detalii.
- Un alt risc: date sensibile. Aici regula de aur este claritatea despre ce poate fi văzut, ce poate fi reprodus, și unde se poate accesa în condiții de confidențialitate. Dacă nu poți pune ceva în anexă, oferă o descriere a procesului de acces (protocol, roluri de acces, pseudonimizare etc.) fără a expune datele sensibile.
Răspuns la întrebările tale
- Cum decideți ce intră în anexă vs corp?
- Folosesc principiul "constituie reproducibilitate" ca filtru primar. Dacă o parte din rezultat poate fi înțeleasă și verificată fără a rula tot lanțul de preprocesare sau de parametri, e în corp. Dacă depinde de un set complex de condiții și de un pipeline, atunci intră în anexă cu referințe clare în corp.
- O altă regulă practică este să nu treci în anexă informații care pot fi înlocuite cu descrieri suficiente în corp. Dacă un grafic poate fi înțeles cu un text scurt, nu îl încărca în anexă doar pentru a-l repeta.
- Exemplare concrete din lucrări reale?
- Am întâlnit lucrări cu anexele care conțineau: dicționar de date, configurații exacte de experimente, versiuni de software, scripturi esențiale, și un sub-set de date de test; acestea au permis comisiei să reproducă în câteva ore rezultatele de bază. Ce aș fi propus însă îmbunătățit într-un caz real ar fi claritatea în ce privește modul în care se poate accesa datele sensibile și un plan explicit pentru condițiile de reproducere în medii diferite (de exemplu, un pipeline Docker/UoC pentru HPC).
- Gestionarea datelor sensibile sau limitate?
- Recomand un „pachet de date simulare" care reproduce dinamica generală a fluxului, alături de o prezentare detaliată a transformărilor aplicate în datele reale (fără a expune valorile sensibile). O altă cale este un protocol de acces în cadrul instituției, cu acorduri și versiuni pseudonimizate ale seturilor reale. Cheia este să nu renunți la verificabilitate, ci să o respecți în condiții reglementate.
În încheiere, aș mai adăuga un gând: anexele nu trebuie să fie un monstru de întreținere, ci un partener cu corpul principal. Dacă ar trebui să dai un singur sfat practic, ar fi acesta: gândește-te la anexele tale ca la un kit de reproducere care pornind de la un set clar de dependențe, te poartă într-un drum de la date brute la rezultate, cu pași simpli, verificabili și documentați. Restul - detaliile, variabilele, configurațiile - poate sta în anexă, bine organizate, astfel încât cititorul să poată alege să zboare direct la concluzii sau să se aventureze în profunzimea procesului.
Mi-ar plăcea să văd cum vă organizați voi pachetele de reproducere în practică. Dacă aveți șabloane, handy templates, sau exemple (fără date sensibile, desigur), trimiteți-le în cod sau descrieri. Poate construireăm împreună o mică bibliotecă de bune practici pentru anexele lucrărilor de diplomă - ceva ce să poată ajuta și pe ceilalți să scape de dilema "ce pun în corp și ce pun în anexă" cu un set de reguli simple și eficiente.
