diff --git a/markdown-docs/api/keywords.en.md b/markdown-docs/api/keywords.en.md index fb6d012..59fca31 100644 --- a/markdown-docs/api/keywords.en.md +++ b/markdown-docs/api/keywords.en.md @@ -186,7 +186,7 @@ Keywords are used to find the desired data. Use as many or as few keywords as ne - granule_list - Comma-separated list of specific scenes (granules). Large lists will need to utilize a [POST request](https://en.wikipedia.org/wiki/POST_(HTTP)). - - granule_list may not be used in conjuction with other keywords, however, it may be used with the output keyword. + - supports wildcard querying ("*" for greedy and "?" for single character match), but requires setting `maxresults` or asf-search directly for unbounded results. See [wildcard usage](/datasets/wildcard_usage/) for usage examples. - Example: - granule_list=ALPSRP111041130, S1B_IW_GRDH_1SDV_20161124T032008_20161124T032033_003095_005430_9906 diff --git a/markdown-docs/api/keywords.es.md b/markdown-docs/api/keywords.es.md index 0d1a2fd..261e158 100644 --- a/markdown-docs/api/keywords.es.md +++ b/markdown-docs/api/keywords.es.md @@ -186,6 +186,7 @@ Las palabras clave se usan para encontrar los datos deseados. Use tantas o tan p - granule_list - Lista separada por comas de escenas (gránulos) específicas. Las listas grandes deberán utilizar una [POST request](https://en.wikipedia.org/wiki/POST_(HTTP)). + - admite consultas con comodines (`*` para coincidir con cualquier número de caracteres y `?` para coincidencias de un solo carácter), pero requiere establecer `maxresults` o usar asf-search directamente para resultados no acotados. Consulte [uso de comodines](/datasets/wildcard_usage/) para ver ejemplos de uso. - granule_list no puede usarse junto con otras palabras clave; sin embargo, puede usarse con la palabra clave output. - Ejemplo: - granule_list=ALPSRP111041130, diff --git a/markdown-docs/datasets/wildcard_usage.en.md b/markdown-docs/datasets/wildcard_usage.en.md new file mode 100644 index 0000000..2b363fb --- /dev/null +++ b/markdown-docs/datasets/wildcard_usage.en.md @@ -0,0 +1,127 @@ +# Wildcard Queries + +The asf-search module and SearchAPI support querying scene names via wildcards ("*" for matching any number of characters and "?" for a single character) with the `granule_list` keyword and is also available on `dataset` search type in Vertex. This enables searching metadata embedded in scene names. Below are examples of useful queries with certain datasets. + +## Using Wildcards + +Below are some basic examples of searching for Sentinel-1D SLCs and/or NISAR PR RSLC using only wildcards. + +### asf-search python module + +In asf-search, wildcard queries are available with the existing `granule_list` keyword. + +``` python +import asf_search as asf + +response = asf.search( + granule_list=['NISAR_L1_PR_RSLC*', 'S1D_IW_SLC*'], + maxResults=250 +) + +response.geojson() +``` + +### SearchAPI + +Like asf-search, SearchAPI accepts wildcard queries with the `granule_list` keyword. + +`https://api.daac.asf.alaska.edu/services/search/param?granule_list=NISAR_L1_PR_RSLC*,S1D_IW_SLC*&maxResults=250&output=geojson` + +Note: `maxResults` is required when using SearchAPI. For unbounded results, use asf-search. + +### Vertex + +Wildcards are supported in the `Scene Name Patterns` field using `Geographic Search`, accessible via the filters panel. + +![Screenshot](/images/vertex_granule_wildcard.png){: style="height:450px;width:750px"} + +Note: cross-dataset results are not supported in Vertex. + +## NISAR + +NISAR data product names contain a few pieces of metadata that aren't directly searchable by additional attributes in CMR or aren't searchable params in asf-search. + +For a breakdown of NISAR data product naming conventions see ASF's [NISAR user manual](https://nisar-docs.asf.alaska.edu/naming-conventions/). + + +### CRID Version Number +The asf-search python module, SearchAPI, and Vertex don't explicitly provide a search parameter for +[CRID versions](https://nisar-docs.asf.alaska.edu/gcov/#term-crid), but wildcards offer a way to do search for them. + +- match all Level 2 NISAR products with CRID version X05010: + - `NISAR_L2_*X05010*` +- match all NISAR science products with CRID version X05010 and above: + - `NISAR_L?_*X0501?*` +- match all NISAR products with CRID version P05012 and above: + - `NISAR_*P05012*` + +### Freq A & B Polarizations +While asf-search provides searching on these `mainBandPolarization` and `sideBandPolarization` fields, you can't search exclusively on single band data without possibly getting both bands in results. Data products denote when a band isn't used with `NA`. + +- Data products that strictly contain frequency A HH data: + - `NISAR_L?_\*_SHNA\*` + +### Cycles +Cycles are represented by 3 characters near the beginning of the granule name, each increment indicating which 12 day repeat pass the scene was taken during. In the case of `NISAR_L2_PR_GUNW_003_136_D_081_008_4000_SH_20251026T153228_20251026T153231_20251225T153231_20251225T153234_X05010_N_P_J_001` +the `003` indicates this scene was taken during 3rd cycle. + +- For all products that were taken during the 3rd cycle: + - `NISAR_L?_PR_????_003_*` + +- For all products that were taken during cycles 1-9: + - `NISAR_L?_PR_????_00*` + +- For all products that were taken during cycles 9 and 10: + - `NISAR_L?_PR_????_009*`, `NISAR_L?_PR_????_010*` + +### Stack IDs + +Stack IDs are useful for building timeseries and are formatted as `RelativeOrbit_OrbitDirection_FrameNumber`. + +Example stack ID wildcard: + +- `NISAR_\*165_D_100\*` + * Relative Orbit: 165 + * Orbit Direction: D (Descending) + * Frame Number: 100 + +Here is how to use the above pattern with the asf-search python module to get adjacent NISAR timeseries results. +```python +import asf_search as asf + +# Two adjacent stacks +stack_ids = ['165_D_100', '165_D_101'] + +multi_stack_results = asf.search( + dataset=asf.DATASET.NISAR, + granule_list=[f'NISAR_*{stack_id}*' for stack_id in stack_ids] + ) + +multi_stack_results.geojson() +``` + +## OPERA-S1 + +OPERA-S1 has a few useful fields not directly covered in places like Vertex but are possible in SearchAPI and asf-search. + +Search for Level 2 OPERA products that use S1C as source acquisitions: + +- `OPERA_L2_*S1C_*` + +Vertex doesn't directly support searching on track number for OPERA-S1 data but users can use a pattern like `OPERA_L*-S1_T*` to limit to a specific track number. + +The below pattern would return OPERA-S1 level 2 products with track number `95`: + +- `OPERA_L2_*-S1_T095*` + +OPERA Project spec pages are available [here](https://www.jpl.nasa.gov/go/opera/products/). + + + diff --git a/markdown-docs/datasets/wildcard_usage.es.md b/markdown-docs/datasets/wildcard_usage.es.md new file mode 100644 index 0000000..bfafad6 --- /dev/null +++ b/markdown-docs/datasets/wildcard_usage.es.md @@ -0,0 +1,125 @@ +# Consultas con comodines + +El módulo asf-search y SearchAPI admiten consultas de nombres de escenas mediante comodines (`*` para coincidir con cualquier número de caracteres y `?` para un solo carácter) con la palabra clave `granule_list`, y también está disponible en el tipo de búsqueda `dataset` en Vertex. Esto permite buscar metadatos integrados en los nombres de las escenas. A continuación se muestran ejemplos de consultas útiles con ciertos conjuntos de datos. + +## Uso de comodines + +A continuación se muestran algunos ejemplos básicos de búsqueda de SLC de Sentinel-1D y/o NISAR PR RSLC usando solo comodines. + +### Módulo de Python asf-search + +En asf-search, las consultas con comodines están disponibles con la palabra clave existente `granule_list`. + +``` python +import asf_search as asf + +response = asf.search( + granule_list=['NISAR_L1_PR_RSLC*', 'S1D_IW_SLC*'], + maxResults=250 +) + +response.geojson() +``` + +### SearchAPI + +Al igual que asf-search, SearchAPI acepta consultas con comodines con la palabra clave `granule_list`. + +`https://api.daac.asf.alaska.edu/services/search/param?granule_list=NISAR_L1_PR_RSLC*,S1D_IW_SLC*&maxResults=250&output=geojson` + +Nota: `maxResults` es obligatorio al usar SearchAPI. Para resultados no acotados, use asf-search. + +### Vertex + +Los comodines se admiten en el campo `Scene Name Patterns` mediante `Geographic Search`, accesible desde el panel de filtros. + +![Screenshot](/images/vertex_granule_wildcard_es.png){: style="height:450px;width:750px"} + +Nota: Vertex no admite resultados entre conjuntos de datos distintos. + +## NISAR + +Los nombres de productos de datos de NISAR contienen algunas piezas de metadatos que no se pueden buscar directamente mediante atributos adicionales en CMR o no son parámetros de búsqueda en asf-search. + +Para ver un desglose de las convenciones de nomenclatura de productos de datos de NISAR, consulte el [manual de usuario de NISAR](https://nisar-docs.asf.alaska.edu/naming-conventions/). + + +### Número de versión CRID +El módulo de Python asf-search, SearchAPI y Vertex no proporcionan explícitamente un parámetro de búsqueda para las [versiones CRID](https://nisar-docs.asf.alaska.edu/gcov/#term-crid), pero los comodines ofrecen una forma de buscarlas. + +- coincidir con todos los productos NISAR de nivel 2 con la versión CRID X05010: + - `NISAR_L2_*X05010*` +- coincidir con todos los productos científicos de NISAR con la versión CRID X05010 y superiores: + - `NISAR_L?_*X0501?*` +- coincidir con todos los productos NISAR con la versión CRID P05012 y superiores: + - `NISAR_*P05012*` + +### Polarizaciones de frecuencia A y B +Aunque asf-search permite buscar en estos campos `mainBandPolarization` y `sideBandPolarization`, no puede buscar exclusivamente datos de una sola banda sin obtener posiblemente ambas bandas en los resultados. Los productos de datos indican cuando una banda no se utiliza con `NA`. + +- Productos que contienen exclusivamente datos HH de la frecuencia A: + - `NISAR_L?_\*_SHNA\*` + +### Ciclos +Los ciclos se representan mediante 3 caracteres cerca del inicio del nombre del granule; cada incremento indica en qué pasada de repetición de 12 días se tomó la escena. `003` indica que esta escena se tomó durante el 3er ciclo. + +- Para todos los productos que se tomaron durante el 3er ciclo: + - `NISAR_L?_PR_????_003_*` + +- Para todos los productos que se tomaron durante los ciclos 1-9: + - `NISAR_L?_PR_????_00*` + +- Para todos los productos que se tomaron durante los ciclos 9 y 10: + - `NISAR_L?_PR_????_009*`, `NISAR_L?_PR_????_010*` + +### IDs de stack + +Los IDs de stack son útiles para construir series temporales y se formatean como `RelativeOrbit_OrbitDirection_FrameNumber`. + +Ejemplo de comodín para un ID de stack: + +- `NISAR_\*165_D_100\*` + * Órbita relativa: 165 + * Dirección de la órbita: D (descendente) + * Número de marco: 100 + +A continuación se muestra cómo usar el patrón anterior con el módulo de Python asf-search para obtener resultados adyacentes de series temporales de NISAR. +```python +import asf_search as asf + +# Dos pilas adyacentes +stack_ids = ['165_D_100', '165_D_101'] + +multi_stack_results = asf.search( + dataset=asf.DATASET.NISAR, + granule_list=[f'NISAR_*{stack_id}*' for stack_id in stack_ids] + ) + +multi_stack_results.geojson() +``` + +## OPERA-S1 + +OPERA-S1 tiene algunos campos útiles que no están cubiertos directamente en lugares como Vertex, pero sí son posibles en SearchAPI y asf-search. + +Buscar productos OPERA de nivel 2 que usen S1C como adquisiciones de origen: + +- `OPERA_L2_*S1C_*` + +Vertex no admite directamente la búsqueda por número de pista para datos OPERA-S1, pero los usuarios pueden usar un patrón como `OPERA_L*-S1_T*` para limitar a un número de pista específico. + +El siguiente patrón devolvería productos OPERA-S1 de nivel 2 con el número de pista `95`: + +- `OPERA_L2_*-S1_T095*` + +Las especificaciones del proyecto OPERA están disponibles [aquí](https://www.jpl.nasa.gov/go/opera/products/). + + + diff --git a/markdown-docs/datasets/wildcard_usage.key b/markdown-docs/datasets/wildcard_usage.key new file mode 100644 index 0000000..a055bfb --- /dev/null +++ b/markdown-docs/datasets/wildcard_usage.key @@ -0,0 +1 @@ +{{ WILDCARD_USAGE_1 }} diff --git a/markdown-docs/images/vertex_granule_wildcard.png b/markdown-docs/images/vertex_granule_wildcard.png new file mode 100644 index 0000000..447d283 Binary files /dev/null and b/markdown-docs/images/vertex_granule_wildcard.png differ diff --git a/markdown-docs/images/vertex_granule_wildcard_es.png b/markdown-docs/images/vertex_granule_wildcard_es.png new file mode 100644 index 0000000..e950f76 Binary files /dev/null and b/markdown-docs/images/vertex_granule_wildcard_es.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 4d5a09f..1199996 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -101,6 +101,7 @@ nav: - Event: vertex/events.md - Derived Datasets: vertex/derived_datasets.md - What's New: vertex/changelog.md + - Wildcard Queries: datasets/wildcard_usage.md - Tutorial Videos: https://www.youtube.com/playlist?list=PLXluIEvp5ZzIWd0yNy-ANfdwWjCD1hInA - Source Code: https://github.com/asfadmin/Discovery-SearchUI - Custom Processing: https://hyp3-docs.asf.alaska.edu @@ -115,6 +116,7 @@ nav: - ASFSession: asf_search/ASFSession.md - Pair: asf_search/Pair.md - Best Practices: asf_search/BestPractices.md + - Wildcard Queries: datasets/wildcard_usage.md - Exceptions: asf_search/exceptions.md - What's New: https://github.com/asfadmin/Discovery-asf_search/blob/master/CHANGELOG.md - ASF Search API: @@ -123,6 +125,7 @@ nav: - Tools: api/tools.md - Troubleshooting: api/troubleshooting.md - Cookbook: api/cookbook.md + - Wildcard Queries: datasets/wildcard_usage.md - What's New: api/changelog.md # - About: about.md - Product Details: