We’ll use this in a table that contains a reference column with repeated values (i.e., an ID) to aggregate values from another column or columns based on that reference. In all instances, we will use the --aggregate flag.

Basic example with a 2-column table, one with the ID and another one with values

In this case, values from the second column will be aggregated based on the values from the first column. To do that, the -i flag references the input table, the --agg_ref_col_index flag is the column we want to use as reference (base 1) and the --agg_col flag is the column we want to aggregate (base 1). Moreover, with the --agg_sep flag, we can choose the separator we want in our aggregated column.

Example with a 3-column table, one being the ID and the other two corresponding to values.

In this case, values from the second and third columns will be aggregated based on the first one.

Having 2 columns as reference.

If we have two columns as reference and we don't want to aggregate them but we also don't want to lose them, we can use the --agg_ref_col_index flag to select more than one column as reference (as well as selecting more than one aggregation column).

Example with a 3-column table, one being the ID and the other two corresponding to value, and another aggregation function.

Besides concatenating values in our column(s) of interest (default mode), we can also use different methods of aggregation using the --agg_mode flag, such as calculating the average ("mean"), median ("median"), maximum ("max") and minimum values ("min"), sum ("sum"), standard deviation ("std"), variance ("var"), interquartile range ("IQR"), 25th percentile ("P25"), 75th percentile ("P75") as well as counts ("count").

Let's see and example with the average of values from columns 2 and 3 based on column 1.

Example of aggregation of counts.

Useful to obtain a table with the ID in one column and the number of times said ID appears in the table when it was desaggregated in the other column.

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)

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'

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".

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)).

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")

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

Y para quedarnos con los MONDO:0017999 de clusteres random

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:

Pasa una tabla del formato long al formato wide

En ocasiones, al trabajar con flujos como el de autoflow, lanzamos tareas paralelizadas con distintas conmbinaciones de trabajo, por ejemplo: red (ORPHA y MONDO) y tipo de clustering (CPM y HLC) y volcamos distintas métricas en un archivo común, del estilo:

ORPHA	CPM	N_CLUSTERS	500
ORPHA	CPM	CLUSTER_SIZE	10
ORPHA	HLC	N_CLUSTERS	600
ORPHA	HLC	CLUSTER_SIZE	12
MONDO	CPM	N_CLUSTERS	550
MONDO	CPM	CLUSTER_SIZE	11
MONDO	HLC	N_CLUSTERS	650
MONDO	HLC	CLUSTER_SIZE	13

En lo que vemos que las dos primeras columnas son factores (red y tipo de clustering), la tercera es la métrica medida y la cuarta es el valor que toma la misma. Que es lo que se llamaría el formato "long" de una tabla (ejemplo de casos long y wide) Sin embargo, para poder utilizar algunos métodos de graficado de CanvasXpress o para ver la tabla de métricas de una forma más sencilla, necesitamos transformar esta tabla a un formato "wide". Es en este caso cuando se utiliza el método create_metric_table.

Ejemplo básico

Este método es un tanto especial en cuanto a la mayoría de sus parámetros son posicionales. Por orden, los argumentos son:

1. tabla de entrada
2. nombres para las columnas de los factores en la tabla de salida (separados por comas)
3. nombre para la tabla de salida

Siendo los tres obligatorios.

Imaginando que tenemos una tabla de entrada con las columnas que representan "nombre de la red, tipo de clustering, tipo de red, métrica, valor" , el comando sería algo como:

Definir otra tabla para volcar los registros corruptos

Opcionalmente, se puede pasar un flag -c para devolver otra tabla con los valores corruptos, es decir, aquellos que no se han podido transformar a formato wide porque falta algún valor de los factores.

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.

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).

Convert table from excel to plain format (CSV, TSV and similar).

Basic example

This example shows how to convert a table from excel to plain format (CSV, TSV and similar). The two-sheet excel file is as follows:

Let's extract the first three columns from the first sheet of the file special_files/scRNAseq.xlsx and convert it to plain tabular format. We will use the -i flag to specify input file, -c to select columns to extract and -s for the sheet to retrieve data from.

Extracting the first two and last two columns from the second sheet

In this case, we extract the first two and last two columns from the second sheet in the same file

Extract all columns from the first sheet

If we wish to extract all columns without specifying all of them we can just leave the --excel_cols argument empty, which signals for the extraction of every column.

Extracting select rows

In addition to columns, the user can also choose which rows to extract from the table. By default, every row is extracted, but we can extract a selection.

In this case we are extracting rows 1,3 and columns 1,3,4 from the first sheet

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

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:

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

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.

Extract a selection of columns from the original table

Basic example using numeric indices to select columns

Input table is provided with flag -i. Columns to extract are selected with flag -c (comma-separated 1-based numeric indices), using a hyphen (-) so select a column range.

In this case, we will extract columns 1, 3, 4 and 5. We will do so by selecting column 1 and the 3-5 interval.

Using column names if header flag is present

If flag -H is active, it means the table has a header. If that is the case we can select columns by specifying their name, again selecting multiple by separating them by commas. (NOTE: even if the table has a header, columns may be selected by numerical index without activating the -H flag, exactly as in the previous example)

In this case, we will select columns col-1, col-3, col-4 and col-5, the same as in the previous example, but this time selecting them by column name. In this case it is also possible to select a range of columns, but in this case by using the "%-%" sequence of characters (as the hyphen may also be a part of the column name, as was chosen for this example)

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.

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

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)

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

Se utiliza para realizar un merge de N cantidad de tablas en base a su primera columna con identificadores compartidos.

Ejemplo básico

En este script, el argumento para las tablas de entrada es posicional (pudiendo unir N cantidad de tablas), con los paths a las tablas a unir separadas por espacios. Tiene un argumento, --fill_character, que se utiliza para rellenar los campos vacíos (aquellos registros que en una tabla tienen datos pero en otra no), que por defecto está a "-"

En este caso, se unen las tablas tables/disease_cluster, tables/disease_gene y tables/mondo_to_orpha, y se rellenan los campos vacíos con "NA".

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'

We'll use this when we have a table that contains a column with IDs (i.e., ensemblIDs and associated GO terms) and another table that we want to use as a dictionary to translate certain values for different ones (i.e., a table with ensemblIDs and their corresponding gene symbol).

Basic example

We have a table with MONDO IDs and the cluster(s) where that MONDO disease has been found. We also have a file that correlates each MONDO ID with its corresponding ORPHA ID. We'll use the latter to translate all MONDO IDs to ORPHA IDs in the first table.

We'll use the -i flag to specify the input table (the first table in our case) and the -I flag for the dictionary (second table). We will then use the -c flag to select the column we want to translate, the --from flag to indicate which column from the dictionary table we want to use as the search key and the --to flag to select the column in the dictionary that contains the terms we want to use for replacing in the first table.

Removing untranslated entries

As we can observe in the previous example, if an ID term from the input file is not present in the dictionary, that ID remains untranslated. If we want to remove any untranslated entries, we can add the -u flag to the command.

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.

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)

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

Se utiliza para realizar un merge de dos tablas en base a una columna con identificadores compartidos.

Ejemplo básico

Se utiliza como tabla base la que se da con el flag -i, y la que se va a mergear con el flag -l, la co. Esto sería equivalente a un left join. Para obtener un right join, tan solo tendríamos que alternar los flags que damos a cada tabla (hacer un left join pero con la linker como input)

Por defecto, se espera que el identificador en la tabla input esté en la primera columna, y todo el resto de columnas de esta tabla se mantendrán. Con respecto a la tabla linker, podemos indicar la columna que contiene el identificador con el flag --id_linker (por defecto a 0), y las columnas que queremos mantener en el merge, separadas por comas, con el flag --columns2linker (por defecto a 1)

Tambien tenemos el flag -s para indicar que separador queremos para la tabla resultante (por defecto tabulación)

Ejemplo utilizando los flags --id_linker y --columns2linker

Utilizamos el flag --columns2linker para indicar que queremos las dos columnas de la tabla linker, no solo la primera. Usamos también el flag --id_linker para indicar qué columna contiene los identificadores para el merge en la tabla linker, aunque en este caso coincida con el valor por defecto

Manteniendo solo registros comunes

Para mantener solo los registros comunes a ambas tablas podemos usar el flag --drop. Esto sería equivalente a un inner join

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

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

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

Se utiliza para convertir una tabla en formato TSV,CSV, etc en una tabla con la sintaxis necesaria para ser añadida a LaTeX

Ejemplo básico

Se da la tabla con el flag -i

Añadiendo el backbone

Si se quiere obtener un backbone algo más detallado con el que luego rellenar los campos restantes, se puede utilizar el parámetro --whole o -w

Se utiliza para transponer una tabla

Ejemplo básico

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