# OpenMindat: A Python Package for Geomaterial Data Analysis and Retrieval from Mindat API
The OpenMindat Python package is designed to facilitate querying and retrieving data on minerals and geomaterials from the Mindat API. It provides classes for detailed queries based on various attributes like IMA status, keywords, and specific geomaterial properties.
GitHub Repository: [OpenMindat Python Package](https://github.com/ChuBL/OpenMindat)
## Table of Contents
- [Get Started](#get-started)
- [Endpoint Descriptions](#endpoint-descriptions)
- [Use Cases](#use-cases)
- [0. Setup](#0-setup)
- [1. Perform Detailed Queries on Geomaterials](#1-perform-detailed-queries-on-geomaterials)
- [2. Retrieve IMA-Approved Minerals](#2-retrieve-ima-approved-minerals)
- [3. Search Geomaterials Using Keywords](#3-search-geomaterials-using-keywords)
- [4. Retrieve Localities](#4-retrieve-localities)
- [5. Retrieve Type Localities for IMA-Approved Mineral Species](#5-retrieve-type-localities-for-ima-approved-mineral-species)
- [6. Retrieve Locality Occurrences for Single Mineral Species](#6-retrieve-locality-occurrences-for-single-mineral-species)
- [Documentation and Relevant Links](#documentation-and-relevant-links)
- [Contact Us](#contact-us)
- [License](#license)
- [Authors](#authors)
- [Citations](#citations)
- [Acknowledgments](#acknowledgments)
- [Upgrade Logs](#upgrade-logs)
## Get Started
### Install via Pip
```console
foo@bar:~$ pip install openmindat
```
### Import the Package in Python
```python
import openmindat
```
<p float="left">
<img src="https://raw.githubusercontent.com/ChuBL/OpenMindat/main/figures/OpenMindat_Flowchart.png" width="100%">
</p>
## Endpoint Descriptions
| Endpoint | Classes | Description |
|:------------------:|------------|----------|
| Dana8 | - [DanaRetriever()](https://github.com/ChuBL/OpenMindat/wiki/DanaRetriever) | Search query to return information about the Dana-8 classification standard. |
| Geomaterials | - [GeomaterialRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialRetriever)<br>- [GeomaterialIdRetreiver()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialIdRetriever)<br>- [GeomaterialDictRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialDictRetriever) | Search query to return information about mindat database items such as id, name, group id etc. |
| Geomaterial_search | - [GeomaterialSearchRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialSearchRetriever) | Query to search for mindat database entries based on search keywords.|
| Localities | - [LocalitiesRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesRetriever)<br>- [LocalitiesIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesIdRetriever) | Search query to return information about different localities, for examples the main elements present in the Jegdalek ruby deposit in Afghanistan |
| Localities_Age | - [LocalitiesAgeRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesAgeRetriever)<br>- [LocalitiesAgeIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesAgeIdRetriever) |Search query to return locality age details. |
| Localities_Statues | - [LocalitiesStatusRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesStatusRetriever)<br>- [LocalitiesStatusIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesStatusIdRetriever) | Search query to return information about the status type of localities. For example, abandoned is a status type. |
| Localities_Type | - [LocalitiesTypeRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesTypeRetriever)<br>- [LocalitiesTypeIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesTypeIdRetriever)| Search query to return information about the type of localities. For example, a Mining Field is a locality type.|
| LocGeoregion2 | - [GeoRegionRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeoRegionRetriever) | Gives information about GeoRegion boundaries |
| LocObject | - [LocobjectRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocobjectRetriever) | N/A |
| Minerals-IMA | - [MineralsIMARetriever()](https://github.com/ChuBL/OpenMindat/wiki/MineralsIMARetriever)<br>- [MineralsIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/MineralsIdRetriever) | Search query to return IMA details for a mineral. For example the year it's IMA status was approved. |
| Nickel_Strunz | - [StrunzRetriever()](https://github.com/ChuBL/OpenMindat/wiki/StrunzRetriever) | Search query to return information about the Nickel-Strunz-10 classification standard. |
| Photo_Count | - [PhotoCountRetriever()](https://github.com/ChuBL/OpenMindat/wiki/PhotoCountRetriever) | N/A|
## Use Cases
### 0. Setup
#### Setting API Key in Alternative Ways
```python
import os
os.environ["MINDAT_API_KEY"] = 'Your_Mindat_API_Key'
```
> If you do not have a Mindat API key, please refer to [How to Get My Mindat API Key or Token?](https://www.mindat.org/a/how_to_get_my_mindat_api_key)
You can also set the API key by following the general queries.
#### Checking Available Methods
```python
from openmindat import GeomaterialRetriever
gr = GeomaterialRetriever()
# Print out the available functions for a class
gr.available_methods()
```
```python
from openmindat import GeomaterialRetriever
gr = GeomaterialRetriever()
# Typo check
gr.elements_in('Cu')
'''>>> AttributeError: 'GeomaterialRetriever' object has no attribute 'elements_in',
Available methods: ['_init_params', 'available_methods', 'bi_max', 'bi_min', 'cleavagetype', 'color',
'colour', 'crystal_system', 'density_max', 'density_min', 'diaphaneity', 'elements_exc', 'elements_inc',
'entrytype', 'expand', 'fields', 'fracturetype', 'get_dict', 'groupid', 'hardness_max', 'hardness_min',
'id__in', 'ima', 'ima_notes', 'ima_status', 'lustretype', 'meteoritical_code',
'meteoritical_code_exists', 'name', 'non_utf', 'omit', 'optical2v_max', 'optical2v_min', 'opticalsign',
'opticaltype', 'ordering', 'page', 'page_size', 'polytypeof', 'q', 'ri_max', 'ri_min', 'save', 'saveto',
'streak', 'synid', 'tenacity', 'updated_at', 'varietyof']. Did you mean: 'elements_inc'?'''
```
### 1. Perform Detailed Queries on Geomaterials
```python
from openmindat import GeomaterialRetriever
gr = GeomaterialRetriever()
gr.density_min(2.0).density_max(5.0).crystal_system("Hexagonal")
gr.elements_exc("Au,Ag")
gr.save()
```
### 2. Retrieve IMA-Approved Minerals
```python
from openmindat import MineralsIMARetriever
mir = MineralsIMARetriever()
mir.fields("id,name,ima_formula,ima_year")
mir.saveto("./mindat_data", 'my_filename')
```
### 3. Search Geomaterials Using Keywords
```python
from openmindat import GeomaterialSearchRetriever
gsr = GeomaterialSearchRetriever()
gsr.geomaterials_search("quartz, green, hexagonal")
gsr.save("filename")
# Alternatively, you can get the list object directly:
gsr = GeomaterialSearchRetriever()
gsr.geomaterials_search("ruby, red, hexagonal")
print(gsr.get_dict())
```
### 4. Retrieve Localities
```python
from openmindat import LocalitiesRetriever
# Download Localities for certain state
lr = LocalitiesRetriever()
lr.country("USA").txt("Idaho")
lr.save()
# Alternatively, you can get the list object directly:
lr = LocalitiesRetriever()
lr.country("Canada").description("mine")
print(lr.get_dict())
```
### 5. Retrieve Type Localities for IMA-Approved Mineral Species
```python
from openmindat import GeomaterialRetriever
gr = GeomaterialRetriever()
gr.ima(True).expand("type_localities")
gr.saveto("./mindat_data")
```
### 6. Retrieve Locality Occurrences for Single Mineral Species
Please consider using only one mineral species ID for querying localities occurrences since this query might result in many records and exceed the server limitation.
```python
from openmindat import GeomaterialRetriever
gr = GeomaterialRetriever()
gr.expand("locality").id__in(str(id_value))
gr.saveto("./mindat_data")
```
## Documentation and Links
- [Get your Mindat API Key](https://www.mindat.org/a/how_to_get_my_mindat_api_key)
- [GitHub Wiki](https://github.com/ChuBL/OpenMindat/wiki)
- [API Documentation](https://api.mindat.org/schema/redoc)
- [Geomaterial Fields Definition](https://github.com/smrgeoinfo/How-to-Use-Mindat-API/blob/main/geomaterialfields.csv)
- [R package for OpenMindat](https://github.com/quexiang/OpenMindat)
- **Built-in Help**:
To explore detailed class and method documentation within the OpenMindat package, use Python's built-in `help()` function. This provides direct access to docstrings, showcasing usage examples and parameter details. Example:
```python
from openmindat import GeomaterialRetriever
help(GeomaterialRetriever)
```
The help() is also available for the specific functions:
```python
from openmindat import MineralsIMARetriever
help(MineralsIMARetriever.fields)
```
Press `q` to exit the help interface.
## Contact Us
For further assistance or feedback, feel free to contact the development team at [jiyinz@uidaho.edu](mailto:jiyinz@uidaho.edu).
## License
**Project Licence:** [Apache](LICENSE)
**Mindat Data License:** [CC BY-NC-SA 4.0 DEED](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en)
The Mindat API is currently in beta test, and while access is free for all, please note that the data provided are not yet licensed for redistribution and are for private, non-commercial use only. Once launched, data will be available under an open-access license, but please always check the terms of use of the license before reusing these data.
## Authors
Jiyin Zhang, Cory Clairmont, Xiaogang Ma
## Citations
If you use the data or code from this repository, please cite it as indicated below.
```
@misc{OpenMindat,
author = {Jiyin Zhang and Cory Clairmont and Xiaogang Ma},
title = {OpenMindat: A Python Package for Geomaterial Data Analysis and Retrieval from Mindat API},
year = {2024},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/ChuBL/OpenMindat}},
note = {Version 0.0.8}
}
```
Additionally, you should also reference the following paper:
Ma, X., Ralph, J., Zhang, J., Que, X., Prabhu, A., Morrison, S.M., Hazen, R.M., Wyborn, L. and Lehnert, K., 2024. *OpenMindat: Open and FAIR mineralogy data from the Mindat database*. *Geoscience Data Journal*, 11(1), pp.94-104. [https://doi.org/10.1002/gdj3.204](https://doi.org/10.1002/gdj3.204).
## Acknowledgments
<p float="left">
<img src="https://raw.githubusercontent.com/ChuBL/OpenMindat/main/figures/mindat2017.png" width="25%">
<img src="https://raw.githubusercontent.com/ChuBL/OpenMindat/main/figures/NSF_Official_logo_Low_Res.png" width="10%">
</p>
- This work is supported by NSF, Award #2126315.
## Upgrade Logs
### 0.0.9
**Release Date:** Jun 17, 2024
- Introduced a `verbose` function to control the display of save notifications and the progress bar.
> **Usage:** `.verbose(FLAG)` where `FLAG` can be:
>
> - `0`: Silent mode (no notifications)
>
> - `1`: Show save notifications only
>
> - `2` (default): Show progress bar and notifications
- Enhanced the download logic for handling large content with oversized page sizes.
### 0.0.8
**Released:** Jun 09, 2024
- Added misspelling checks and messages for the functions in the endpoint classes. Typos in the function names will get error messages of a valid function list.
- Revised downloading logic with retries and improved stability.
### 0.0.7
**Released:** Apr 26, 2024
- The Locality country filter is fixed. The endpoint can download the data for specific countries, e.g., 'UK', 'USA', etc.
### 0.0.6
**Released:** Apr 26, 2024
- Revised a neglected get function for country endpoints.
### 0.0.5
**Released:** Apr 26, 2024
- The `Internal Server Error` issue in v0.0.4 is fixed from the server side.
- The get functions are now changed to `get_dict`.
- Added progress bars for multiple-page queries.
- Some other minor updates.
### 0.0.4
**Released:** Apr 14, 2024
- Tentative issue: Data queries involving multiple pages might return an `Internal Server Error` due to server-end issues. [Related GitHub issue](https://github.com/ChuBL/OpenMindat/issues/12)
- Added support to getting list objects of obtained data in addition to saving it to local directories.
### 0.0.3
**Released:** Apr 11, 2024
- Tentative issue: Data queries involving multiple pages might return an `Internal Server Error` due to server-end issues.
- Now supporting more Mindat endpoints. Not fully tested. Feedback is welcome.
- Revised API key obtaining workflow.
### 0.0.1
**Released:** Dec 14, 2023
- Initial release of the package.
Raw data
{
"_id": null,
"home_page": "https://github.com/ChuBL/OpenMindat",
"name": "openmindat",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "mindat openmindat mineral data python api",
"author": "Jiyin Zhang",
"author_email": "jiyinz@uidaho.edu",
"download_url": "https://files.pythonhosted.org/packages/ac/1b/035afd058d084c740418c9a7c1644b5561dd5c9988d2db4ba4c8137c80e6/openmindat-0.0.9.tar.gz",
"platform": null,
"description": "# OpenMindat: A Python Package for Geomaterial Data Analysis and Retrieval from Mindat API\n\nThe OpenMindat Python package is designed to facilitate querying and retrieving data on minerals and geomaterials from the Mindat API. It provides classes for detailed queries based on various attributes like IMA status, keywords, and specific geomaterial properties.\n\nGitHub Repository: [OpenMindat Python Package](https://github.com/ChuBL/OpenMindat)\n\n## Table of Contents\n - [Get Started](#get-started)\n - [Endpoint Descriptions](#endpoint-descriptions)\n - [Use Cases](#use-cases)\n - [0. Setup](#0-setup)\n - [1. Perform Detailed Queries on Geomaterials](#1-perform-detailed-queries-on-geomaterials)\n - [2. Retrieve IMA-Approved Minerals](#2-retrieve-ima-approved-minerals)\n - [3. Search Geomaterials Using Keywords](#3-search-geomaterials-using-keywords)\n - [4. Retrieve Localities](#4-retrieve-localities)\n - [5. Retrieve Type Localities for IMA-Approved Mineral Species](#5-retrieve-type-localities-for-ima-approved-mineral-species)\n - [6. Retrieve Locality Occurrences for Single Mineral Species](#6-retrieve-locality-occurrences-for-single-mineral-species)\n - [Documentation and Relevant Links](#documentation-and-relevant-links)\n - [Contact Us](#contact-us)\n - [License](#license)\n - [Authors](#authors)\n - [Citations](#citations)\n - [Acknowledgments](#acknowledgments)\n - [Upgrade Logs](#upgrade-logs)\n\n## Get Started\n\n### Install via Pip\n\n```console\nfoo@bar:~$ pip install openmindat\n```\n\n### Import the Package in Python\n\n```python\nimport openmindat\n```\n\n<p float=\"left\">\n <img src=\"https://raw.githubusercontent.com/ChuBL/OpenMindat/main/figures/OpenMindat_Flowchart.png\" width=\"100%\">\n</p>\n\n## Endpoint Descriptions \n\n| Endpoint | Classes | Description |\n|:------------------:|------------|----------|\n| Dana8 | - [DanaRetriever()](https://github.com/ChuBL/OpenMindat/wiki/DanaRetriever) | Search query to return information about the Dana-8 classification standard. |\n| Geomaterials | - [GeomaterialRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialRetriever)<br>- [GeomaterialIdRetreiver()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialIdRetriever)<br>- [GeomaterialDictRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialDictRetriever) | Search query to return information about mindat database items such as id, name, group id etc. |\n| Geomaterial_search | - [GeomaterialSearchRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeomaterialSearchRetriever) | Query to search for mindat database entries based on search keywords.|\n| Localities | - [LocalitiesRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesRetriever)<br>- [LocalitiesIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesIdRetriever) | Search query to return information about different localities, for examples the main elements present in the Jegdalek ruby deposit in Afghanistan |\n| Localities_Age | - [LocalitiesAgeRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesAgeRetriever)<br>- [LocalitiesAgeIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesAgeIdRetriever) |Search query to return locality age details. |\n| Localities_Statues | - [LocalitiesStatusRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesStatusRetriever)<br>- [LocalitiesStatusIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesStatusIdRetriever) | Search query to return information about the status type of localities. For example, abandoned is a status type. |\n| Localities_Type | - [LocalitiesTypeRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesTypeRetriever)<br>- [LocalitiesTypeIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocalitiesTypeIdRetriever)| Search query to return information about the type of localities. For example, a Mining Field is a locality type.|\n| LocGeoregion2 | - [GeoRegionRetriever()](https://github.com/ChuBL/OpenMindat/wiki/GeoRegionRetriever) | Gives information about GeoRegion boundaries |\n| LocObject | - [LocobjectRetriever()](https://github.com/ChuBL/OpenMindat/wiki/LocobjectRetriever) | N/A |\n| Minerals-IMA | - [MineralsIMARetriever()](https://github.com/ChuBL/OpenMindat/wiki/MineralsIMARetriever)<br>- [MineralsIdRetriever()](https://github.com/ChuBL/OpenMindat/wiki/MineralsIdRetriever) | Search query to return IMA details for a mineral. For example the year it's IMA status was approved. |\n| Nickel_Strunz | - [StrunzRetriever()](https://github.com/ChuBL/OpenMindat/wiki/StrunzRetriever) | Search query to return information about the Nickel-Strunz-10 classification standard. |\n| Photo_Count | - [PhotoCountRetriever()](https://github.com/ChuBL/OpenMindat/wiki/PhotoCountRetriever) | N/A|\n\n## Use Cases\n\n### 0. Setup\n\n#### Setting API Key in Alternative Ways\n\n```python\nimport os\n\nos.environ[\"MINDAT_API_KEY\"] = 'Your_Mindat_API_Key'\n```\n\n> If you do not have a Mindat API key, please refer to [How to Get My Mindat API Key or Token?](https://www.mindat.org/a/how_to_get_my_mindat_api_key)\n\nYou can also set the API key by following the general queries.\n\n#### Checking Available Methods\n\n```python\nfrom openmindat import GeomaterialRetriever\n\ngr = GeomaterialRetriever()\n# Print out the available functions for a class\ngr.available_methods()\n```\n```python\nfrom openmindat import GeomaterialRetriever\n\ngr = GeomaterialRetriever()\n# Typo check\ngr.elements_in('Cu')\n'''>>> AttributeError: 'GeomaterialRetriever' object has no attribute 'elements_in', \nAvailable methods: ['_init_params', 'available_methods', 'bi_max', 'bi_min', 'cleavagetype', 'color', \n'colour', 'crystal_system', 'density_max', 'density_min', 'diaphaneity', 'elements_exc', 'elements_inc', \n'entrytype', 'expand', 'fields', 'fracturetype', 'get_dict', 'groupid', 'hardness_max', 'hardness_min', \n'id__in', 'ima', 'ima_notes', 'ima_status', 'lustretype', 'meteoritical_code', \n'meteoritical_code_exists', 'name', 'non_utf', 'omit', 'optical2v_max', 'optical2v_min', 'opticalsign', \n'opticaltype', 'ordering', 'page', 'page_size', 'polytypeof', 'q', 'ri_max', 'ri_min', 'save', 'saveto', \n'streak', 'synid', 'tenacity', 'updated_at', 'varietyof']. Did you mean: 'elements_inc'?'''\n```\n\n### 1. Perform Detailed Queries on Geomaterials\n\n```python\nfrom openmindat import GeomaterialRetriever\n\ngr = GeomaterialRetriever()\ngr.density_min(2.0).density_max(5.0).crystal_system(\"Hexagonal\")\ngr.elements_exc(\"Au,Ag\")\ngr.save()\n```\n\n### 2. Retrieve IMA-Approved Minerals\n\n```python\nfrom openmindat import MineralsIMARetriever\n\nmir = MineralsIMARetriever()\nmir.fields(\"id,name,ima_formula,ima_year\")\nmir.saveto(\"./mindat_data\", 'my_filename')\n```\n\n### 3. Search Geomaterials Using Keywords\n\n```python\nfrom openmindat import GeomaterialSearchRetriever\n\ngsr = GeomaterialSearchRetriever()\ngsr.geomaterials_search(\"quartz, green, hexagonal\")\ngsr.save(\"filename\")\n\n# Alternatively, you can get the list object directly:\ngsr = GeomaterialSearchRetriever()\ngsr.geomaterials_search(\"ruby, red, hexagonal\")\nprint(gsr.get_dict())\n```\n\n### 4. Retrieve Localities\n\n```python\nfrom openmindat import LocalitiesRetriever\n\n# Download Localities for certain state\nlr = LocalitiesRetriever()\nlr.country(\"USA\").txt(\"Idaho\")\nlr.save()\n\n# Alternatively, you can get the list object directly:\nlr = LocalitiesRetriever()\nlr.country(\"Canada\").description(\"mine\")\nprint(lr.get_dict())\n```\n\n### 5. Retrieve Type Localities for IMA-Approved Mineral Species\n\n```python\nfrom openmindat import GeomaterialRetriever\n\ngr = GeomaterialRetriever()\ngr.ima(True).expand(\"type_localities\")\ngr.saveto(\"./mindat_data\")\n```\n\n### 6. Retrieve Locality Occurrences for Single Mineral Species\nPlease consider using only one mineral species ID for querying localities occurrences since this query might result in many records and exceed the server limitation.\n\n```python\nfrom openmindat import GeomaterialRetriever\n\ngr = GeomaterialRetriever()\ngr.expand(\"locality\").id__in(str(id_value))\ngr.saveto(\"./mindat_data\")\n```\n\n## Documentation and Links\n\n- [Get your Mindat API Key](https://www.mindat.org/a/how_to_get_my_mindat_api_key)\n- [GitHub Wiki](https://github.com/ChuBL/OpenMindat/wiki)\n- [API Documentation](https://api.mindat.org/schema/redoc)\n- [Geomaterial Fields Definition](https://github.com/smrgeoinfo/How-to-Use-Mindat-API/blob/main/geomaterialfields.csv)\n- [R package for OpenMindat](https://github.com/quexiang/OpenMindat)\n\n- **Built-in Help**:\n\nTo explore detailed class and method documentation within the OpenMindat package, use Python's built-in `help()` function. This provides direct access to docstrings, showcasing usage examples and parameter details. Example:\n\n```python\nfrom openmindat import GeomaterialRetriever\n\nhelp(GeomaterialRetriever)\n```\n\nThe help() is also available for the specific functions:\n\n```python\nfrom openmindat import MineralsIMARetriever\n\nhelp(MineralsIMARetriever.fields)\n```\n\nPress `q` to exit the help interface.\n\n\n## Contact Us\n\nFor further assistance or feedback, feel free to contact the development team at [jiyinz@uidaho.edu](mailto:jiyinz@uidaho.edu).\n\n\n## License\n\n**Project Licence:** [Apache](LICENSE)\n\n**Mindat Data License:** [CC BY-NC-SA 4.0 DEED](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en)\n\nThe Mindat API is currently in beta test, and while access is free for all, please note that the data provided are not yet licensed for redistribution and are for private, non-commercial use only. Once launched, data will be available under an open-access license, but please always check the terms of use of the license before reusing these data.\n\n## Authors\n\nJiyin Zhang, Cory Clairmont, Xiaogang Ma\n\n## Citations\n\nIf you use the data or code from this repository, please cite it as indicated below.\n\n```\n@misc{OpenMindat,\n author = {Jiyin Zhang and Cory Clairmont and Xiaogang Ma},\n title = {OpenMindat: A Python Package for Geomaterial Data Analysis and Retrieval from Mindat API},\n year = {2024},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/ChuBL/OpenMindat}},\n note = {Version 0.0.8}\n}\n```\n\nAdditionally, you should also reference the following paper:\n\nMa, X., Ralph, J., Zhang, J., Que, X., Prabhu, A., Morrison, S.M., Hazen, R.M., Wyborn, L. and Lehnert, K., 2024. *OpenMindat: Open and FAIR mineralogy data from the Mindat database*. *Geoscience Data Journal*, 11(1), pp.94-104. [https://doi.org/10.1002/gdj3.204](https://doi.org/10.1002/gdj3.204).\n\n\n\n## Acknowledgments\n\n<p float=\"left\">\n <img src=\"https://raw.githubusercontent.com/ChuBL/OpenMindat/main/figures/mindat2017.png\" width=\"25%\">\n <img src=\"https://raw.githubusercontent.com/ChuBL/OpenMindat/main/figures/NSF_Official_logo_Low_Res.png\" width=\"10%\">\n</p>\n\n- This work is supported by NSF, Award #2126315.\n\n## Upgrade Logs\n\n### 0.0.9\n\n**Release Date:** Jun 17, 2024\n\n- Introduced a `verbose` function to control the display of save notifications and the progress bar.\n\n> **Usage:** `.verbose(FLAG)` where `FLAG` can be:\n> \n> - `0`: Silent mode (no notifications)\n>\n> - `1`: Show save notifications only\n> \n> - `2` (default): Show progress bar and notifications\n\n- Enhanced the download logic for handling large content with oversized page sizes.\n\n### 0.0.8\n**Released:** Jun 09, 2024\n\n- Added misspelling checks and messages for the functions in the endpoint classes. Typos in the function names will get error messages of a valid function list.\n- Revised downloading logic with retries and improved stability.\n\n### 0.0.7\n**Released:** Apr 26, 2024\n\n- The Locality country filter is fixed. The endpoint can download the data for specific countries, e.g., 'UK', 'USA', etc.\n\n### 0.0.6\n**Released:** Apr 26, 2024\n\n- Revised a neglected get function for country endpoints.\n\n### 0.0.5\n**Released:** Apr 26, 2024\n\n- The `Internal Server Error` issue in v0.0.4 is fixed from the server side.\n- The get functions are now changed to `get_dict`.\n- Added progress bars for multiple-page queries.\n- Some other minor updates.\n\n\n### 0.0.4\n**Released:** Apr 14, 2024\n\n- Tentative issue: Data queries involving multiple pages might return an `Internal Server Error` due to server-end issues. [Related GitHub issue](https://github.com/ChuBL/OpenMindat/issues/12)\n- Added support to getting list objects of obtained data in addition to saving it to local directories.\n\n### 0.0.3\n**Released:** Apr 11, 2024\n\n- Tentative issue: Data queries involving multiple pages might return an `Internal Server Error` due to server-end issues. \n- Now supporting more Mindat endpoints. Not fully tested. Feedback is welcome.\n- Revised API key obtaining workflow.\n\n### 0.0.1\n**Released:** Dec 14, 2023\n\n- Initial release of the package.\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "An alpha version for OpenMindat package",
"version": "0.0.9",
"project_urls": {
"Homepage": "https://github.com/ChuBL/OpenMindat"
},
"split_keywords": [
"mindat",
"openmindat",
"mineral",
"data",
"python",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0b9bd42be9aa51bcb19852b13e9f8c6b8cddef4a792153dbdf6ad556468b970d",
"md5": "d3188d1205e8a380d55585e0e357cd74",
"sha256": "0d16aa6906e9c2304804f150b0b57a7cf58bb394565ab6e92a92cd0579426ef6"
},
"downloads": -1,
"filename": "openmindat-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3188d1205e8a380d55585e0e357cd74",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 53024,
"upload_time": "2024-10-07T01:54:31",
"upload_time_iso_8601": "2024-10-07T01:54:31.859143Z",
"url": "https://files.pythonhosted.org/packages/0b/9b/d42be9aa51bcb19852b13e9f8c6b8cddef4a792153dbdf6ad556468b970d/openmindat-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac1b035afd058d084c740418c9a7c1644b5561dd5c9988d2db4ba4c8137c80e6",
"md5": "08ae6f6156e9ba2bee76455d3bdd333c",
"sha256": "3a15baae598fc95fc9c518769c05abdbb9e98152ee42923cc769d0cbf7ca1f6a"
},
"downloads": -1,
"filename": "openmindat-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "08ae6f6156e9ba2bee76455d3bdd333c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40004,
"upload_time": "2024-10-07T01:54:35",
"upload_time_iso_8601": "2024-10-07T01:54:35.198928Z",
"url": "https://files.pythonhosted.org/packages/ac/1b/035afd058d084c740418c9a7c1644b5561dd5c9988d2db4ba4c8137c80e6/openmindat-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 01:54:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ChuBL",
"github_project": "OpenMindat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openmindat"
}
JSON
