Skip to content

MineralsIMARetriever

CorylC edited this page May 2, 2024 · 5 revisions

MineralsIMARetriever Class Documentation

Overview

MineralsIMARetriever is a class designed to query mineral data from the Mindat API. It allows for setting various query parameters like mineral IDs, IMA status, specific fields, and pagination. This class is built to support method chaining, enabling the construction of complex queries. Additionally, it offers functionalities to save the queried data to either a specified directory or the current directory.

Methods

1. __init__()

Initializes a new instance of the MineralsIMARetriever class.

  • Usage:
    mir = MineralsIMARetriever()

2. _init_params()

Initializes the query parameters with default values.

  • Internal Method

3. expand(EXPAND_FIELDS)

Expands the query to include additional related fields.

  • Parameters:
    • EXPAND_FIELDS (list[str] or str): Fields to expand.
  • Valid Options:
    • "description"
    • "type_localities"
    • "locality"
    • "relations"
    • "minstats"
    • "~all"
    • "*"
  • Example:
    mir.expand(["description", "type_localities"])

4. fields(FIELDS)

Specifies the fields to be retrieved in the query.

  • Parameters:
    • FIELDS (str): Comma-separated field names.
  • Example:
    mir.fields("id,name,ima_formula")

5. id__in(ID_IN_LIST)

Filters the query based on specific IDs.

  • Parameters:
    • ID_IN_LIST (str): Comma-separated list of IDs.
  • Example:
    mir.id__in("123,456,789")

6. ima(IS_IMA)

Filters minerals based on IMA approval status.

  • Parameters:
    • IS_IMA (int): IMA status (1 for approved, 0 for pending).
  • Example:
    mir.ima(1)

7. omit(OMIT_FIELDS)

Excludes specific fields from the query results.

  • Parameters:
    • OMIT_FIELDS (str): Fields to omit, separated by commas.
  • Example:
    mir.omit("id,name")

8. page(PAGE)

Sets the page number for pagination in query results.

  • Parameters:
    • PAGE (int): The page number.
  • Example:
    mir.page(2)

9. page_size(PAGE_SIZE)

Determines the number of results per page.

  • Parameters:
    • PAGE_SIZE (int): Number of results per page.
  • Example:
    mir.page_size(50)

10. q(SEARCHING_KEYWORDS)

Sets the keywords for the query.

  • Parameters:
    • SEARCHING_KEYWORDS (str): Keywords for searching.
  • Example:
    mir.q("quartz")

11. updated_at(DATE_STR)

Sets the filter for the last updated date and time of the geomaterials.

  • Parameters:
    • DATE_STR (str): Date and time in the format YYYY-MM-DD HH:MM:SS.
  • Example:
    mir.updated_at('2022-01-01 12:00:00')

12. saveto(OUTDIR, FILE_NAME) / save(FILE_NAME)

Executes the query and saves the results to the specified directory or current directory.

  • Parameters:
    • OUTDIR (str): Optional. Directory path for saving results.
    • FILE_NAME (str): Optional. Name of the file where the results will be saved.
  • Example:
    mir.saveto("/path/to/directory", "example_file")
    mir.save()

13. get_dict()

Executes the query and saves the results to an object.

  • Returns: Dictionary

Examples

Below are some examples to demonstrate the usage of the MineralsIMARetriever class in various scenarios.

# Example 1: Retrieve and save IMA-approved minerals
mir = MineralsIMARetriever()
mir.ima(1).fields("id,name,ima_formula").saveto("/path/to/minerals_data")

# Example 2: Search for minerals by name and save the results
mir = MineralsIMARetriever()
mir.q("quartz").save("quartz_results")

Additional Information

For more details, please refer to the Mindat API documentation.

Back to Top

Clone this wiki locally