Merge pull request #133 from pachterlab/dev

Dev -> main

dev-requirements.txt

@@ -2,3 +2,4 @@ coverage>=5.1
 pytest>=7.0.0
 openai<=0.28.1
 cellxgene-census
+parameterized==0.9.0

docs/src/SUMMARY.md

@@ -19,7 +19,8 @@
 * [gget enrichr](en/enrichr.md)  
 * [gget gpt](en/gpt.md)  
 * [gget info](en/info.md)  
-* [gget muscle](en/muscle.md)  
+* [gget muscle](en/muscle.md)
+* [gget mutate](en/mutate.md)  
 * [gget pdb](en/pdb.md)  
 * [gget ref](en/ref.md)  
 * [gget search](en/search.md)  
@@ -54,7 +55,8 @@
 * [gget enrichr](es/enrichr.md)  
 * [gget gpt](es/gpt.md)  
 * [gget info](es/info.md)  
-* [gget muscle](es/muscle.md)  
+* [gget muscle](es/muscle.md)
+* [gget mutate](es/mutate.md)  
 * [gget pdb](es/pdb.md)  
 * [gget ref](es/ref.md)  
 * [gget search](es/search.md)  

docs/src/en/blast.md

@@ -60,7 +60,7 @@ gget.blast("MKWMFKEDHSLEHRCVESAKIRAKYPDRVPVIVEKVSGSQIVDIDKRKYLVPSDITVAQFMWIIRKRI
 | PREDICTED: gamma-aminobutyric acid receptor-as...| Colobus angolensis palliatus	 | 	NaN | 336983 | 180	 | 180 | 100% | ... |
 | . . . | . . . | . . . | . . . | . . . | . . . | . . . | ... | 
 
-
+<br/><br/>
 **BLAST from .fa or .txt file:**  
 ```bash
 gget blast fasta.fa

docs/src/en/cosmic.md

@@ -1,28 +1,67 @@
 > Python arguments are equivalent to long-option arguments (`--arg`), unless otherwise specified. Flags are True/False arguments in Python.  The manual for any gget tool can be called from the command-line using the `-h` `--help` flag.  
 ## gget cosmic 🪐
 Search for genes, mutations, and other factors associated with cancer using the [COSMIC](https://cancer.sanger.ac.uk/cosmic) (Catalogue Of Somatic Mutations In Cancer) database.  
-Return format: JSON (command-line) or data frame/CSV (Python).  
-This module was written by [@AubakirovArman](https://github.com/AubakirovArman).
+Return format: JSON (command-line) or data frame/CSV (Python) when `download_cosmic=False`. When `download_cosmic=True`, downloads the requested database into the specified folder.    
+
+This module was written in part by [@AubakirovArman](https://github.com/AubakirovArman) (information querying) and [@josephrich98](https://github.com/josephrich98) (database download).  
 
 NOTE: License fees apply for the commercial use of COSMIC. You can read more about licensing COSMIC data [here](https://cancer.sanger.ac.uk/cosmic/license).
 
-**Positional argument**  
+**Positional argument (for querying information)**  
 `searchterm`   
-Search term, which can be a mutation, gene name (or Ensembl ID), cancer type, tumor site, study ID, PubMed ID, or sample ID, as defined using the `entity` argument. Example: 'EGFR'  
+Search term, which can be a mutation, or gene name (or Ensembl ID), or sample, etc.  
+Examples for the searchterm and entitity arguments:   
+
+| searchterm   | entitity    | |
+|--------------|-------------| ---|
+| EGFR         | mutations   | -> Find mutations in the EGFR gene that are associated with cancer |
+| v600e        | mutations   | -> Find genes for which a v600e mutation is associated with cancer |
+| COSV57014428 | mutations   | -> Find mutations associated with this COSMIC mutations ID |
+| EGFR         | genes       | -> Get the number of samples, coding/simple mutations, and fusions observed in COSMIC for EGFR |
+| prostate     | cancer      | -> Get number of tested samples and mutations for prostate cancer |
+| prostate     | tumour_site | -> Get number of tested samples, genes, mutations, fusions, etc. with 'prostate' as primary tissue site |
+| ICGC         | studies     | -> Get project code and descriptions for all studies from the ICGC (International Cancer Genome Consortium) |
+| EGFR         | pubmed      | -> Find PubMed publications on EGFR and cancer |
+| ICGC         | samples     | -> Get metadata on all samples from the ICGC (International Cancer Genome Consortium) |
+| COSS2907494  | samples     | -> Get metadata on this COSMIC sample ID (cancer type, tissue, # analyzed genes, # mutations, etc.) |
 
-**Optional arguments**  
+NOTE: (Python only) Set to `None` when downloading COSMIC databases with `download_cosmic=True`.
+
+**Optional arguments (for querying information)**  
 `-e` `--entity`  
 'mutations' (default), 'genes', 'cancer', 'tumour site', 'studies', 'pubmed', or 'samples'.  
-Defines the type of the supplied search term.  
+Defines the type of the results to return. 
 
 `-l` `--limit`  
 Limits number of hits to return. Default: 100.  
 
+**Flags (for downloading COSMIC databases)**  
+`-d` `--download_cosmic`  
+Switches into database download mode.  
+
+`-gm` `--gget_mutate`  
+TURNS OFF creation of a modified version of the database for use with gget mutate.  
+Python: `gget_mutate` is True by default. Set `gget_mutate=False` to disable.  
+
+**Optional arguments (for downloading COSMIC databases)**  
+`-mc` `--mutation_class`
+'cancer' (default), 'cell_line', 'census', 'resistance', 'screen', or 'cancer_example'  
+Type of COSMIC database to download.  
+
+`-cv` `--cosmic_version`  
+Version of the COSMIC database. Default: None -> Defaults to latest version.  
+
+`-gv` `--grch_version`  
+Version of the human GRCh reference genome the COSMIC database was based on (37 or 38). Default: 37  
+
+**Optional arguments (general)**  
 `-o` `--out`   
-Path to the file the results will be saved in, e.g. path/to/directory/results.csv (or .json). Default: Standard out.   
-Python: `save=True` will save the output in the current working directory.  
+Path to the file (or folder when downloading databases with the `download_cosmic` flag) the results will be saved in, e.g. 'path/to/results.json'.  
+Default: None  
+-> When download_cosmic=False: Results will be returned to standard out  
+-> When download_cosmic=True: Database will be downloaded into current working directory  
 
-**Flags**  
+**Flags (general)**  
 `-csv` `--csv`  
 Command-line only. Returns results in CSV format.  
 Python: Use `json=True` to return output in JSON format.
@@ -32,18 +71,31 @@ Command-line only. Prevents progress information from being displayed.
 Python: Use `verbose=False` to prevent progress information from being displayed.  
 
 
-### Example
+### Examples
+#### Query information
 ```bash
-gget cosmic -e genes EGFR
+gget cosmic EGFR
 ```
 ```python
 # Python
-gget.cosmic("EGFR", entity="genes")
+gget.cosmic("EGFR")
 ```
-→ Returns the COSMIC hits for gene 'EGFR' in the format:  
+→ Returns mutations in the EGFR gene that are associated with cancer in the format:
 
-| Gene     | Alternate IDs     | Tested samples     | Simple Mutations        | Fusions | Coding Mutations | ... |
-| -------------- |-------------------------| ------------------------| -------------- | ----------|-----|---|
-| EGFR| EGFR,ENST00000275493.6,... | 210280 | 31900 | 0 | 31900 | ... |
-| . . . | . . . | . . . | . . . | . . . | . . . | . . . | ... | 
+| Gene     | Syntax     | Alternate IDs                  | Canonical  |
+| -------- |------------| -------------------------------| ---------- |
+| EGFR     | c.*2446A>G | EGFR c.*2446A>G, EGFR p.?, ... | y          |
+| EGFR     | c.(2185_2283)ins(18) | EGFR c.(2185_2283)ins(18), EGFR p.?, ... | y          |
+| . . .    | . . .      | . . .                          | . . .      | 
+
+
+### Downloading COSMIC databases
+```bash
+gget cosmic --download_cosmic
+```
+```python
+# Python
+gget.cosmic(searchterm=None, download_cosmic=True)
+```
+→ Downloads the COSMIC cancer database of the latest COSMIC release into the current working directory.
 

docs/src/en/mutate.md

@@ -0,0 +1,104 @@
+> Python arguments are equivalent to long-option arguments (`--arg`), unless otherwise specified. Flags are True/False arguments in Python.  The manual for any gget tool can be called from the command-line using the `-h` `--help` flag.  
+## gget mutate 🧟
+Takes in nucleotide sequences and mutations (in [standard mutation annotation](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1867422/) and returns mutated versions of the input sequences according to the provided mutations.  
+Return format: Saves mutated sequences in FASTA format (or returns a list containing the mutated sequences if `out=None`).  
+
+**Positional argument**  
+`sequences`   
+Path to the FASTA file containing the sequences to be mutated, e.g., 'path/to/seqs.fa'.  
+Sequence identifiers following the '>' character must correspond to the identifiers in the seq_ID column of `mutations`.  
+NOTE: Only the string following the '>' until the first space or dot will be used as a sequence identifier. - Version numbers of Ensembl IDs will be ignored.  
+
+Example format of the FASTA file:  
+```
+>seq1 (or ENSG00000106443)  
+ACTGCGATAGACT  
+>seq2  
+AGATCGCTAG
+```
+
+Alternatively: Input sequence(s) as a string or list, e.g. 'AGCTAGCT'.
+
+**Required arguments**  
+`-m` `--mutations`  
+Path to the csv or tsv file (e.g., 'path/to/mutations.csv') or data frame (DataFrame object) containing information about the mutations in the following format:  
+
+| mutation         | mut_ID | seq_ID |
+|------------------|--------|--------|
+| c.2C>T           | mut1   | seq1   |
+| c.9_13inv        | mut2   | seq2   |
+| c.9_13inv        | mut2   | seq4   |
+| c.9_13delinsAAT  | mut3   | seq4   |
+| ...              | ...    | ...    |
+
+'mutation' = Column containing the mutations to be performed written in standard mutation annotation  
+'mut_ID' = Column containing the identifier for each mutation  
+'seq_ID' = Column containing the identifiers of the sequences to be mutated (must correspond to the string following the '>' character in the 'sequences' FASTA file; do NOT include spaces or dots)  
+
+Alternatively: Input mutation(s) as a string or list, e.g., 'c.2C>T'.  
+If a list is provided, the number of mutations must equal the number of input sequences.  
+For use from the terminal (bash): Enclose individual mutation annotations in quotation marks to prevent parsing errors.  
+
+**Optional arguments**  
+`-k` `--k`  
+Length of sequences flanking the mutation. Default: 31.  
+If k > total length of the sequence, the entire sequence will be kept.  
+
+`-mc` `--mut_column`  
+Name of the column containing the mutations to be performed in `mutations`. Default: 'mutation'.  
+
+`-mic` `--mut_id_column`  
+Name of the column containing the IDs of each mutation in `mutations`. Default: 'mut_ID'.  
+
+`-sic` `--seq_id_column`  
+Name of the column containing the IDs of the sequences to be mutated in `mutations`. Default: 'seq_ID'.  
+
+`-o` `--out`   
+Path to output FASTA file containing the mutated sequences, e.g., 'path/to/output_fasta.fa'.  
+Default: None -> returns a list of the mutated sequences to standard out.    
+The identifiers (following the '>') of the mutated sequences in the output FASTA will be '>[seq_ID]_[mut_ID]'.  
+
+**Flags**  
+`-q` `--quiet`   
+Command-line only. Prevents progress information from being displayed.  
+Python: Use `verbose=False` to prevent progress information from being displayed.  
+
+### Examples
+```bash
+gget mutate ATCGCTAAGCT -m 'c.4G>T'
+```
+```python
+# Python
+gget.mutate("ATCGCTAAGCT", "c.4G>T")
+```
+→ Returns ATCTCTAAGCT.  
+
+<br/><br/>
+
+**List of sequences with a mutation for each sequence provided in a list:**  
+```bash
+gget mutate ATCGCTAAGCT TAGCTA -m 'c.4G>T' 'c.1_3inv' -o mut_fasta.fa
+```
+```python
+# Python
+gget.mutate(["ATCGCTAAGCT", "TAGCTA"], ["c.4G>T", "c.1_3inv"], out="mut_fasta.fa")
+```
+&rarr; Saves 'mut_fasta.fa' file containing: 
+```
+>seq1_mut1  
+ATCTCTAAGCT  
+>seq2_mut2  
+GATCTA
+```
+
+<br/><br/>
+
+**One mutation applied to several sequences with adjusted `k`:**  
+```bash
+gget mutate ATCGCTAAGCT TAGCTA -m 'c.1_3inv' -k 3
+```
+```python
+# Python
+gget.mutate(["ATCGCTAAGCT", "TAGCTA"], "c.1_3inv", k=3)
+```
+&rarr; Returns ['CTAGCT', 'GATCTA'].  

docs/src/es/cosmic.md

@@ -1,28 +1,67 @@
 > Parámetros de Python són iguales a los parámetros largos (`--parámetro`) de Terminal, si no especificado de otra manera. Las banderas son parámetros de verdadero o falso (True/False) en Python. El manuál para cualquier modulo de gget se puede llamar desde la Terminal con la bandera `-h` `--help`.   
 ## gget cosmic 🪐
 Busque genes, mutaciones, etc. asociados con cánceres utilizando la base de datos [COSMIC](https://cancer.sanger.ac.uk/cosmic) (Catálogo de mutaciones somáticas en cáncer).  
-Produce: Resultados en formato JSON (Terminal) o Dataframe/CSV (Python).  
-`gget cosmic` fue escrito por [@AubakirovArman](https://github.com/AubakirovArman).
+Produce: JSON (línea de comandos) o marco de datos/CSV (Python) cuando `download_cosmic=False`. Cuando `download_cosmic=True`, descarga la base de datos solicitada en la carpeta especificada.  
 
-Se aplican tarifas de licencia para el uso comercial de COSMIC. Puede leer más sobre la concesión de licencias de datos COSMIC [aquí](https://cancer.sanger.ac.uk/cosmic/license).
+Este módulo fue escrito en parte por [@AubakirovArman](https://github.com/AubakirovArman) (consulta de información) y [@josephrich98](https://github.com/josephrich98) (descarga de base de datos).  
 
-**Parámetro posicional**  
+NOTA: Se aplican tarifas de licencia para el uso comercial de COSMIC. Puede leer más sobre la concesión de licencias de datos COSMIC [aquí](https://cancer.sanger.ac.uk/cosmic/license).  
+
+**Parámetro posicional (para consultar información)**  
 `searchterm`   
-Término de búsqueda. Puede ser una mutación, un nombre de gen (o ID de Ensembl), tipo de cáncer, sitio del tumor, ID de estudio, ID de PubMed o ID de muestra, tal como se define con el argumento `entity`. Ejemplo: 'EGFR'  
+Término de búsqueda, que puede ser una mutación, un nombre de gen (o ID de Ensembl), una muestra, etc.  
+Ejemplos para los argumentos de searchterm y entidad:   
+
+| searchterm   | entidad    | |
+|--------------|------------|-|
+| EGFR         | mutaciones | -> Encuentra mutaciones en el gen EGFR asociadas con el cáncer |
+| v600e        | mutaciones | -> Encuentra genes para los cuales una mutación v600e está asociada con el cáncer |
+| COSV57014428 | mutaciones | -> Encuentra mutaciones asociadas con esta ID de mutaciones COSMIC |
+| EGFR         | genes      | -> Obtiene el número de muestras, mutaciones simples/codificantes y fusiones observadas en COSMIC para EGFR |
+| prostate     | cáncer     | -> Obtiene el número de muestras probadas y mutaciones para el cáncer de próstata |
+| prostate     | sitio_tumoral | -> Obtiene el número de muestras probadas, genes, mutaciones, fusiones, etc. con 'próstata' como sitio de tejido primario |
+| ICGC         | estudios   | -> Obtiene el código de proyecto y descripciones de todos los estudios de ICGC (Consortio Internacional del Genoma del Cáncer) |
+| EGFR         | pubmed     | -> Encuentra publicaciones de PubMed sobre EGFR y cáncer |
+| ICGC         | muestras   | -> Obtiene metadatos sobre todas las muestras de ICGC (Consortio Internacional del Genoma del Cáncer) |
+| COSS2907494  | muestras   | -> Obtiene metadatos sobre esta ID de muestra COSMIC (tipo de cáncer, tejido, # genes analizados, # mutaciones, etc.) |
 
-**Parámetros optionales**  
+NOTA: (Solo Python) Establezca en `None` cuando se descarguen bases de datos COSMIC con `download_cosmic=True`.  
+
+**Parámetros opcionales (para consultar información)**  
 `-e` `--entity`  
-'mutations' (mutación), 'genes' (nombre de gen / ID de Ensembl), 'cancer' (tipo de cáncer), 'tumour site' (sitio del tumor), 'studies' (ID de estudio), 'pubmed' (ID de PubMed), o 'samples' (ID de muestra). Por defecto: 'mutations'.  
-Define el tipo de término de búsqueda (`searchterm`).  
+'mutations' (predeterminado), 'genes', 'cáncer', 'sitio_tumoral', 'estudios', 'pubmed' o 'muestras'.
+Define el tipo de resultados a devolver.
 
 `-l` `--limit`  
-Limita el número de resultados producidos. Por defecto: 100.  
+Limita el número de resultados a devolver. Predeterminado: 100.
+
+**Banderas (para descargar bases de datos COSMIC)**  
+`-d` `--download_cosmic`  
+Conmuta al modo de descarga de base de datos.
+
+`-gm` `--gget_mutate`  
+DESACTIVA la creación de una versión modificada de la base de datos para usar con gget mutate.
+Python: `gget_mutate` es Verdadero por defecto. Establezca `gget_mutate=False` para deshabilitar.
+
+**Parámetros opcionales (para descargar bases de datos COSMIC)**  
+`-mc` `--mutation_class`
+'cáncer' (predeterminado), 'línea_celular', 'censo', 'resistencia', 'pantalla' o 'ejemplo_cáncer'  
+Tipo de base de datos COSMIC para descargar.
+
+`-cv` `--cosmic_version`  
+Versión de la base de datos COSMIC. Predeterminado: Ninguno -> Se establece en la última versión por defecto.
 
+`-gv` `--grch_version`  
+Versión del genoma de referencia humano GRCh en el que se basó la base de datos COSMIC (37 o 38). Predeterminado: 37
+
+**Parámetros opcionales (generales)**  
 `-o` `--out`   
-Ruta al archivo en el que se guardarán los resultados, p. ej. ruta/al/directorio/resultados.csv (o .json). Por defecto: salida estándar (STDOUT).  
-Para Python, usa `save=True` para guardar los resultados en el directorio de trabajo actual.  
+Ruta al archivo (o carpeta cuando se descargan bases de datos con el flag `download_cosmic`) donde se guardarán los resultados, p. ej. 'ruta/a/resultados.json'.  
+Predeterminado: None  
+-> Cuando download_cosmic=False: Los resultados se devolverán a la salida estándar  
+-> Cuando download_cosmic=True: La base de datos se descargará en el directorio de trabajo actual  
 
-**Banderas**  
+**Banderas (generales)**  
 `-csv` `--csv`
 Solo para Terminal. Produce los resultados en formato CSV.  
 Para Python, usa json=True para producir los resultados en formato JSON.
@@ -33,16 +72,28 @@ Para Python, usa `verbose=False` para imipidir la informacion de progreso de ser
 
 
 ### Por ejemplo    
+#### Consultar información
 ```bash
 gget cosmic -e genes EGFR
 ```
 ```python
 # Python
 gget.cosmic("EGFR", entity="genes")
 ```
-→ Produce los resultados COSMIC para el gen 'EGFR':  
+→ Devuelve mutaciones en el gen EGFR asociadas con el cáncer en el formato:
+
+| Gene     | Syntax     | Alternate IDs                  | Canonical  |
+| -------- |------------| -------------------------------| ---------- |
+| EGFR     | c.*2446A>G | EGFR c.*2446A>G, EGFR p.?, ... | y          |
+| EGFR     | c.(2185_2283)ins(18) | EGFR c.(2185_2283)ins(18), EGFR p.?, ... | y          |
+| . . .    | . . .      | . . .                          | . . .      | 
 
-| Gene     | Alternate IDs     | Tested samples     | Simple Mutations        | Fusions | Coding Mutations | ... |
-| -------------- |-------------------------| ------------------------| -------------- | ----------|-----|---|
-| EGFR| EGFR,ENST00000275493.6,... | 210280 | 31900 | 0 | 31900 | ... |
-| . . . | . . . | . . . | . . . | . . . | . . . | . . . | ... | 
+### Descargar bases de datos COSMIC
+```bash
+gget cosmic --download_cosmic
+```
+```python
+# Python
+gget.cosmic(searchterm=None, download_cosmic=True)  
+```
+→ Descargue la base de datos sobre cáncer de COSMIC de la última versión de COSMIC.