Convertire TSV in JSON

Gli strumenti ricorrono alla tabulazione quando i loro dati sono pieni di virgole e non si vuole quotare. I client database stampano insiemi di risultati con tabulazioni. I browser genomici, i file di annotazione di sequenze e le tabelle di espressione le usano per convenzione. Le piattaforme pubblicitarie e le console di analisi le esportano perché nomi campagna e titoli pagina sono pieni di punteggiatura.

Quella scelta compra affidabilità contro le virgole e rinuncia a quasi tutto il resto. Il file non ha tipi, nessuna nidificazione, nessun modo di marcare una colonna come identificatore, e nessuna difesa contro una tabulazione che appare dentro un valore. È un buon formato di trasporto e una cosa scarsa su cui calcolare, motivo per cui la prima cosa che chiunque fa con uno è convertirlo.

La riga intestazione fornisce le chiavi, e ogni riga successiva diventa un oggetto. Il risultato è un array JSON — la forma che uno script, un notebook, un fetch JavaScript e quasi ogni libreria presumono quando dicono "i dati".

Nulla lo avvolge e nulla è indicizzato per una colonna ID, perché fare entrambe le cose richiederebbe sapere quale colonna sia l'identificatore e non è una decisione che un convertitore può prendere per conto proprio. Un array presume il minimo, e trasformarlo in una lookup indicizzata per qualsiasi campo è una riga in qualunque linguaggio si stia già scrivendo.

Un file separato da tabulazioni non ha un escape accettato per una tabulazione dentro un campo, e un a capo dentro uno è peggio: la riga finisce dove il valore doveva continuare. Entrambi succedono in pratica, di solito in una colonna note, descrizione o annotazione dove qualcuno ha incollato del testo.

In JSON sono caratteri ordinari. Una tabulazione viene scritta come \t dentro la stringa e un a capo come \n, e nessuno dei due può influenzare la struttura del documento, perché la struttura è espressa da graffe e parentesi quadre invece che dai caratteri nei dati. È il motivo singolarmente più forte per convertire un file separato da tabulazioni disordinato invece di continuare a elaborarlo come testo, e vale la pena farlo prima che il file venga passato a qualcos'altro invece che dopo che una pipeline ha già prodotto una risposta plausibilmente sbagliata.

Un'intestazione `Gene symbol` diventa la chiave `Gene symbol`, spazi inclusi, e `Cost (USD)` mantiene le sue parentesi. Nulla viene rinominato, minuscolizzato o trasformato in snake_case, perché un convertitore che riscrivesse silenziosamente i nomi delle colonne renderebbe l'output impossibile da riconciliare con la sorgente.

Ha conseguenze dove lo si usa. `row.Gene symbol` non è valido nella maggior parte dei linguaggi e si scriverà `row["Gene symbol"]` invece. Se il JSON entra in codice che verrà mantenuto, rinominare le chiavi una volta — nella riga intestazione prima di convertire, o in un unico passaggio dopo — vale la pena farlo deliberatamente. Due colonne che condividono un'intestazione è il caso da tenere d'occhio: le chiavi oggetto sono uniche, quindi l'ultima vince e la precedente si perde senza avviso.

JSON distingue 7 da "7" e un file separato da tabulazioni no, quindi il parser deduce. I numeri diventano numeri, `true` e `false` diventano booleani, e tutto il resto resta stringa. Per quantità, conteggi, punteggi e prezzi è esattamente giusto e risparmia un passaggio di conversione all'altro capo.

Per gli identificatori è distruzione. Un valore 00123 diventa 123, un numero di accessione o di parte scritto in notazione dall'aspetto scientifico diventa il numero a cui somiglia, e una volta che il JSON contiene un numero non resta nulla da cui recuperare il testo originale. La regola pratica è se sommare due valori nella colonna significherebbe qualcosa; se no, la colonna è un identificatore e voleva restare una stringa. Si controllano quelle colonne nell'output prima di costruirci sopra qualsiasi cosa.

La conversione è spesso il primo passo per leggere un file che nessuno ha documentato, e JSON rende veloce quel passo. `jq "length"` dà il conteggio righe senza che l'intestazione confonda. `jq ".[0] | keys"` elenca le colonne come le ha viste il parser. `jq "[.[].status] | unique"` mostra ogni valore distinto in una colonna, il modo per trovare la sentinella che ha silenziosamente rovinato un campo numerico.

Quest'ultimo vale la pena farlo su qualsiasi colonna che ci si aspettava numerica e che è tornata come stringhe. Il motivo è quasi sempre una manciata di righe che portano `NA`, `-`, `n/a` o una nota, e sapere quale marcatore usava la sorgente è più utile di qualsiasi congettura sullo schema. È anche considerevolmente più veloce che aprire un grande file separato da tabulazioni in un foglio di calcolo, l'alternativa, che applicherà le proprie conversioni in ingresso.

Un vuoto tra due tabulazioni viene scritto come `null`. È una decisione che vale la pena dichiarare chiaramente, perché qualsiasi cosa consumi il JSON tratterà null e "" in modo diverso: uno schema che dichiara un tipo stringa rifiuterà null, e un controllo di verità in JavaScript tratta entrambi come falsy ma un controllo di tipo no.

La sorgente non può dire quale fosse inteso. Un file delimitato ha un solo modo di scrivere "niente qui" e lo usa sia per un valore vuoto sia per un campo che non si applica. Se quella distinzione conta, deve esistere nel file prima della conversione — come sentinella, o come seconda colonna — e nessun convertitore può inventarla dopo.

Le chiavi vengono dalla riga intestazione e ogni riga successiva viene confrontata con essa, quindi una tabella dove una colonna extra inizia ad apparire dopo diecimila righe non fa crescere una chiave per essa. I valori in eccesso finiscono insieme sotto `__parsed_extra`, come array, esattamente sui record che li portano. Le righe a cui manca un campo non portano affatto quella chiave.

È più comune di quanto dovrebbe essere nelle esportazioni assemblate da diverse esecuzioni, ed è il fallimento che un lettore posizionale gestisce peggio — uno splitter ingenuo sposta ogni valore dopo la colonna mancante e produce righe che sembrano giuste e non lo sono. Avere il file come oggetti rende visibile l'incoerenza: una chiamata `keys` su qualche record mostra immediatamente che la forma non è uniforme.

Ci si aspetti che il file cresca. Ogni record ripete ogni chiave, ogni stringa è tra virgolette, e la punteggiatura di un oggetto viene aggiunta attorno ai valori. Su una tabella larga con intestazioni colonna lunghe e valori brevi, il JSON può essere diverse volte la dimensione della sorgente separata da tabulazioni.

È un prezzo equo per un file su cui si calcolerà e uno scarso per un file che serve solo archiviare. L'output è anche stampato in modo leggibile con indentazione di due spazi, il che lo rende leggibile in un editor e aggiunge ulteriori byte. Se la destinazione è archiviazione o uno stream invece di uno script, NDJSON o Parquet è la destinazione migliore e la stessa tabella converte in entrambi.

L'analisi e la serializzazione sono entrambe puro JavaScript caricato da questa pagina, quindi nulla viene caricato, non c'è coda e non c'è account. Conta per il tipo di file che è questo: una tabella di riferimento sotto embargo, un estratto cliente, un insieme di risultati inedito.

L'array viene costruito per intero prima di essere scritto, quindi la memoria è il tetto. Decine di megabyte sono normali e centinaia sono dove una scheda inizia a faticare — e a quella dimensione un singolo array JSON è comunque scomodo da gestire, dato che la maggior parte dei parser insisterà a tenerlo tutto. NDJSON è la forma che scala oltre questo punto, e converte dalla stessa sorgente.