Aunque se explicarán más en detalle en cada sección del binario correspondiente, existen una serie de pautas generales que funcionan para una gran mayoría de los comandos.

Para los binarios a los que se les pase algún flag de tabla de entrada (en la mayoría de casos con el flag -i, pero en otros casos como en 'intersect_columns' con los flags -a y -b), dichas tablas pueden venir en formato de texto plano, pero también se pueden cargar comprimidas en gzip utilizando el flag '--compressed_in'. Por ejemplo:

desaggregate_column_data -i patients_and_phens.gz -x 2 --compressed_in -o desaggregated.txt

Además, para aquellos comandos que solo necesiten una tabla de entrada (como 'aggregate_column_data', 'desaggregate_column_data' o 'transpose_table', pero no 'intersect_columns'), se puede utilizar un guión '-' con el flag de input para indicar que el contenido de la tabla proviene por stdout (por ejemplo fruto de un pipe de un comando anterior), pudiendo venir también comprimido. Por ejemplo:

cat patients_and_phens.txt | script_que_devuelve_datos_comprimidos | desaggregate_column_data -i - -x 2 --compressed_in

En los scripts que devuelvan algún tipo de output (generalmente con el flag -o), de manera similar, también se puede utilizar el flag --compressed_out para que el resultado se devuelva comprimido en gzip. Además, si no se indica un flag de output (omitiendo '-o archivo_salida') y el script solo devuelve una tabla, el contenido se devuelve al stdout en vez de ser escrito en archivo, por lo que puede aprovecharse para pipear en otro script. Por ejemplo:

desaggregate_column_data -i patients_and_phens.txt -x 2 --compressed_out | script_que_utiliza_datos_comprimidos

Se pueden usar ambos flags a la vez, de manera que se pueda recibir una tabla comprimida y devolverla también comprimida. Por ejemplo:

desaggregate_column_data -i patients_and_phens.gz -x 2 --compressed_in --compressed_out -o desaggregated.gz

O utilizando pipes:

cat patients_and_phens.txt | script_que_devuelve_datos_comprimidos | desaggregate_column_data -i - -x 2 --compressed_in --compressed_out | script_que_utiliza_datos_comprimidos

Finalmente, el flag --transposed se puede utilizar en todos aquellos scripts que carguen y/o escriban tablas, y al utilizarlo, se aplicará la transposición de la tabla en el momento de carga así como de manera previa a la escritura de la misma.

Se utiliza para filtrar registros de una o más tablas en funcion a una o varias keywords en una o más columnas

Ejemplo básico

Este script permite filtrar registros de una o varias tablas (si se usa el wildcard * en un path a archivo del flag -i se pueden cargar varias tablas y aplicar todo lo de este apartado para varias tablas, aunque en estos ejemplos se mostrará el caso solo para una tabla) en función de una o varias keywords aplicada a una o más columnas, por lo que es un script bastante versatil y completo, aunque pueda parecer complejo. Se enseñarán varios ejemplos aumentando la complejidad del caso para entender mejor su funcionamiento.

Los argumentos más básicos que se usarán siempre serán la tabla de entrada (flag -i), las columnas que se devolverán (flag -c), la columna que contiene las keywords (flag -f), la keyword/s a buscar (flag -k), -m o --match_mode para indicar si queremos que la keyword esté incluida (opción "i") en la columna (es decir match parcial) o que esté al completo (opción "c"), es decir, match completo. Finalmente con el flag -s o --search se indica (cuando queremos match en varias columnas) si queremos que el match sea completo (opción "c"), es decir, que se cumpla la keyword buscada en cada columna, o algún (some) match en alguna columna (opción "s")

Lo más esencial es entender como se construye el string de keywords de búsqueda. El patrón es el siguiente: key1_col1&key2_col1%key1_col2&key2_col2 donde cada keyword se separa por un "&" (quieres un keyword u otro en una determinada columna) y cada columna por un "%"

Vamos empezar con un caso básico en el que vamos a quedarnos con aquellos registros que contengan la keyword MONDO:0017999 (en flag -k) en la columna 1 (flag -f) de la tabla long_disease_cluster (flag -i). Además queremos que sea el match completo de la palabra (-m c) y nos retorne las columnas 1 y 2 de los registros resultantes (flag -c)

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 1 -k MONDO:0017999 -s c -m c

Output

Match completo en TODAS las columnas indicadas (dos keys, una en cada columna)

Como vemos visto, el ejemplo anterior nos devuelve varios MONDOs que cumplen la condición de match completo en la columna 1. Vamos a ampliar el caso anterior para que solo nos devuelva el MONDO que en la segunda columna (flag -f) tiene el cluster '53_ref'

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 1,2 -k MONDO:0017999%53_ref -s c -m c

Output

Buscar dos (o más registros) en una misma columna (match exacto)

Vamos a obtener las filas que contienen o bien "MONDO:0008995" o bien "MONDO:0013969".

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 1 -k MONDO:0008995&MONDO:0013969 -s c -m c

Output

Match parcial en la segunda columna

Vamos a obtener las filas que contengan el substring "ref" en la segunda columna (cambiando el flag -m o --mode a i (de include)).

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 2 -k ref -s c -m i

Output

Match parcial reverso en la segunda columna

Si lo que nos interesa no es obtener los registros que cumplen el patrón, sino los que no lo cumplen, podemos usar el flag -r o --reverse. Esto es válido tanto para un match completo como parcial. En este caso vamos a enseñar el mismo ejemplo que el anterior, pero con el caso reverso, por lo que en vez de obtener los registros que contienen "ref", obtendremos los que no lo contienen ("rand")

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 2 -k ref -s c -m i --reverse

Output

Match parcial en TODAS las columnas especificadas (dos columnas)

En el caso que filtrabamos por MONDO:0017999 en la primera columna, vimos que encontrabamos 3 clústeres, 36_rand, 53_ref y 53_rand. En este caso, para quedarnos con distintos subsets, podemos utilizar el match parcial. Por ejemplo, para quedarnos con los MONDO:0017999 del cluster 53

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 1,2 -k MONDO:0017999%53 -s c -m i

Output

Y para quedarnos con los MONDO:0017999 de clusteres random

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 1,2 -k MONDO:0017999%rand -s c -m i

Output

Match exacto en ALGUNA de las columnas especificadas (dos columnas)

Hasta ahora hemos estado viendo como hacer matches que se cumplan en todas las columnas. Si queremos buscar keywords en varias columnas pero que el patrón se cumpla solo en ALGUNA de las columnas, podemos cambiar el -s o --search a "s" (some)

Por ejemplo, si queremos quedarnos con los registros que contengan MONDO:0008995 o MONDO:0013969 en la primera columna o 22_rand o 66_ref en la segunda columna, podemos hacer lo siguiente:

Input

column_filter -i tables/long_disease_cluster -c 1,2 -f 1,2 -k MONDO:0008995&MONDO:0013969%22_rand&66_ref -s s -m c

Output

Se utiliza en una tabla para dada una columna como referencia, que tenga valores repetidos, por ejemplo un identificador, agregarte el/los valores de otra(s) columna(s) en función de la de referencia.

Ejemplo básico con una tabla con tres columnas, donde hay dos sin agregar y otra agregada.

En este caso, se desagregan los valores de la tercera columna, amoldando el resto de columnas según la cantidad de valores en cada fila de la tercera columna. Para ello el flag -i hace referencia a la tabla de entrada, el flag -x a la columna que queremos desagregar (en base 1). Con el flag -s indicamos el separador que se ha utilizado en esa columna agregada.

Input

desaggregate_column_data -i tables/cluster_genes_dis_agg -x 3 -s ,

Output

Ejemplo básico con una tabla con cuatro columnas, donde hay dos sin agregar y dos agregada.

Si existe más de una columna agregada, se puede indicar con el flag -x, separándolas por comas. Se asume que todos las columnas agregadas van a tener la misma cantidad de elementos para una determinada fila (ejemplo 1 columna con pat1,pat2,pat y otra con male,male,female).

Input

desaggregate_column_data -i tables/cluster_genes_dis_agg2 -x 3,4 -s ,

Output

Se utiliza para filtrar las filas que nos interesan de una o más tablas en función a una serie de valores que se pasan

Ejemplo básico

Tenemos nuestra tabla con la primera columna teniendo el identificador de una red (la que nos interesa para poder filtrar), y las otras columnas siendo factores y metrica-valor. Tenemos otro archivo en el que tenemos los identificadores de las redes que queremos filtrar (red1 y red3).

Pasamos la tabla de interés tabla como input al flag -i y la columna en la que están los valores que filtrarán las filas con el flag -c. El archivo de una columna con los IDs de redes que queremos filtrar se pasan al flag -t. Pasamos el path a la carpeta (si, a una carpeta, ya que el flag de input -f puede aceptar más de una tabla, separada por comas, para ser filtrada) en el que queremos que se escriba la/s tabla/s filtrada/s con el flag -o y podemos añadir un prefijo para el nombre de la tabla de salida si nos interesa (en este caso usamos "filtered_" en este caso) con el flag --prefix

Input

Archivo de 1 columna con los registros que queremos filtrar

filter_by_list -f tables/long_table -c 1 -t tables/nets_to_filter --prefix filtered_ -o outputs

Output

outputs/filtered_long_table

Usar un match complementario (usar los términos como blacklist en vez de whitelist)

Si en vez de querer quedarnos con todas las filas que tengan los términos de la tabla que pasamos con el flag -t, queremos quedarnos con todas las filas que no tengan esos términos, podemos activar el flag booleano --blacklist.

Repitiendo el mismo ejemplo anterior, pero activando ese flag, tenemos:

Input

Archivo de 1 columna con los registros que queremos omitir

filter_by_list -f tables/long_table -c 1 -t tables/nets_to_filter --prefix blackfiltered_ -o outputs --blacklist

Output

outputs/blackfiltered_long_table

Match parcial (vale tanto para whitelist como para blacklist)

Si en vez de querer filtrar los elementos de la tabla por un match exacto, queremos que sea por un match parcial, podemos activar el flag booleano --not_exact_match

En la tabla siguiente, vamos a quedarnos con todos los clústeres de referencia y descartar los random, indicando que los valores que queremos filtrar en nuestra tabla de entrada dada con el flag -i están en la segunda columna (-c 2) y el archivo que pasamos para filtrar con el flag -t solo tiene el valor 'ref', que será usado para hacer un match parcial al haber usado el flag --not_exact_match

Input

Archivo de 1 columna con los registros que queremos filtrar

filter_by_list -f tables/disease_cluster_ref_rnd -c 2 -t tables/clusts_to_filter --prefix ref_filtered_ -o outputs --not_exact_match

Output

outputs/ref_filtered_disease_cluster_ref_rnd

Filtrar múltiples tablas

Como se ha comentado antes, el flag -f acepta múltiples tablas separadas por comas. Es por ello que el flag -o para el output indica carpeta de salida y no archivo de salida. Además, si vamos a escribir los archivos en la misma carpeta, podemos utilizar el flag --prefix para que no se escriban con el mismo nombre y nos reemplacen las tablas de entrada.

Por lo tanto, podemos filtrar varias tablas a la vez utilizando el mismo archivo de filtrado. Esto es util si tenemos distintos archivos de métricas con los mismos identificadores y queremos filtrar todos ellos por los mismos términos.

Un script muy versatil en torno a la unión de dos tablas

Ejemplo básico

El caso más básico será obtener los registros comunes de dos columnas de dos tablas distintas. Para este caso (además de todos los siguientes) el funcionamiento es simple: tenemos los flag -a y -b para indicar las dos tablas de interés, y los flags -A y -B para indicar las columnas de interés en las respectivas tablas. El flag -s nos servirá para indicar el separador (tabulador por defecto). Por defecto se obtienen los identificadores que estén en las dos tablas (inner join), que es el valor por defecto del flag --keep, aunque luego veremos otros casos de uso

Vamos a ver un ejemplo con dos tablas , ambas con una columna que tienen identificadores de enfermedad de MONDO, para encontrar los registros comunes entre ambas tablas.

Input

Tabla B

intersect_columns -a tables/disease_cluster -b tables/disease_gene -A 1 -B 1 -s \t

Output

Obtener el resto de columnas para los registros comunes encontrados

Si no nos interesa obtener solo los registros comunes de las dos tablas en esa columna, sino también obtener el resto de columnas de ambas tablas, podemos usar el flag -full

Input

Tabla B

intersect_columns -a tables/disease_cluster -b tables/disease_gene -A 1 -B 1 -s \t --keep c --full

Output

Obtener registros específicos de tabla

Hemos visto antes un ejemplo de inner join, que es el caso por defecto. Con el binario de table_linker podemos también podemos utilizar los casos de left join. y right join.

No obstante, con intersect_columns podemos podemos obtener los registros específicos de una tabla, ya sea la A o la B, utilizando el flag --keep. Por ejemplo, si queremos quedarnos con los registros que son específicos de la tabla A, podemos usar el flag --keep a. Y si además nos interesa quedarnos con el resto de columnas de la tabla A para los registros específicos de esta tabla, también podemos usar el flag --full. En el próximo ejemplo, enseñamos como devolver los registros específicos de la tabla A , pero sin devolver el resto de columnas (que podríamos hacer con el flag --full)

Input

Tabla B

intersect_columns -a tables/disease_cluster -b tables/disease_gene -A 1 -B 1 --keep a

Output

De la misma manera, si queremos quedarnos con los registros específicos de la tabla B, podemos usar el flag --keep b. Finalmente, si queremos los registros específicos de la tabla A y los específicos de la tabla B, podemos usar el flag --keep ab (este caso sería el complementario de --keep c, en el que se obtenían los comunes de ambos). Vamos a mostrar este caso, devolviendo además el resto de columnas de las 2 tablas para esos registros

Input

Tabla B

intersect_columns -a tables/disease_cluster -b tables/disease_gene -A 1 -B 1 --keep ab --full

Output

Se utiliza para obtener el número de ocurrencias de todos los términos en una columna de una tabla

Ejemplo básico

Se indica la tabla a utilizar con el flag -i y la columna (indice basado en 1) en la que queremos obtener los conteos con el flag -x

Vamos a ver la cantidad de ocurrencias de los distintos términos en la columna 2 de la tabla 'cluster_genes_dis_agg'

Input

records_count -i tables/cluster_genes_dis_agg -x 2

Output

Se utiliza para obtener un subset de la tabla original, empezando por la fila X y cogiendo Y filas desde ahí.

Ejemplo básico

La tabla de entrada se indica con el flag -i. La fila por la que se empieza con el flag -s o --start_line (indice basado en 1) y la cantidad de filas que se extraen desde ese punto con el flag -l o --lines_to_subset. Además, si la tabla original tiene un header y se quiere mantener en la tabla subseteada, se puede utilizar el flag -H o --header

En este caso, vamos a coger 4 filas de la tabla de métricas, empezando por la fila 3 y manteniendo el header.

Input

subset_table -i tables/metrics_table -s 3 -l 4 -H

Output

Partiendo toda la tabla en distintos archivos con K líneas cada uno

Si se quiere partir la tabla en distintos archivos, cada uno con K líneas, se puede utilizar el flag -k o --chunk_size en vez de los flags -s y -l. En este caso el flag de output -o indica la carpeta donde se guardarán los archivos.

En este caso, vamos a partir la tabla de clusters de enfermedades en distintos archivos, cada uno con 4 líneas (veremos que el ultimo se queda con 2, ya que la tabla inicial tiene 10 registros)

Input

subset_table -i tables/disease_cluster_ref_rnd -k 4 -o outputs/subset_table

Output

outputs/subset_table/disease_cluster_ref_rnd_chunk0

outputs/subset_table/disease_cluster_ref_rnd_chunk1

outputs/subset_table/disease_cluster_ref_rnd_chunk2

Partiendo toda la tabla en N archivos diferentes con la misma cantidad de registros cada uno

Si se quiere partir la tabla en una cantidad fija de N archivos , cada uno de ellos con la misma cantidad de registros, se puede utilizar el flag -n o --number_of_files en vez de los flags -s y -l o --chunk_size. En este caso el flag de output -o también indica la carpeta donde se guardarán los archivos.

En este caso, vamos a partir la tabla de clusters de enfermedades en 2 archivos

Input

subset_table -i tables/disease_cluster_ref_rnd -n 2 -o outputs/subset_table2

Output

outputs/subset_table2/disease_cluster_ref_rnd_chunk0

outputs/subset_table2/disease_cluster_ref_rnd_chunk1

Añade una o varias etiquetas (ej: factores adicionales de una variable y su valor) a todas las filas de una tabla

Ejemplo básico utilizando un string con tags separador por comas

Se pasa la tabla a la que se quiere añadir los tags con el flag -i y un string con los tags separados por comas al flag -t

Input

tag_table -i tables/cluster_stats -t red1,colapsada,traducida

Output

Ejemplo pasando el nombre de un archivo como tag al flag -t

Si en vez de pasarle un string separado por comas con los tags, se le pasa el nombre de un archivo, cmdtabs puede reconocerlo y en ese caso cargar el contenido del archivo para utilizarlo como tags. Se especifica en este caso con el flag -s cual es el separador en ese archvio

Input

Tabla usada en el flag -t con los tags a añadir a la tabla de entrada (1 fila con los valores separados por tabulación)

tag_table -i tables/cluster_stats -t tables/tracker -s

Output

Pasar más de un archivo separado por comas al flag -t

Si le pasamos varios archivos separados por comas, leerá y utilizará cada uno de ellos para añadir los tags

Input

Tablas usadas en el flag -t con los tags a añadir a la tabla de entrada (1 fila con los valores separados por tabulación)

tag_table -i tables/cluster_stats -t tables/tracker,tables/tracker -s

Output

Se utiliza para transponer una tabla

Ejemplo básico

Se transpone la tabla que se da con el flag -i

Input

transpose_table -i tables/cluster_genes_dis_desagg_3cols

Output