Manual v1.1.0 for Geochemistry π - Beta

# Manual v1.1.0 for Geochemistry π - Beta **Note:** This manual is for temporal use, we'll upload a more formal one soon. Note: Words in red colour means the jargon will change in the release of beta version v.0.2.0-beta. ### Table of Contents 1. [Installation](#installation) 2. [Example](#example) 3. [Data Format](#data) 4. [Bug Report](#bug) 5. [Advice](#advice) ### 1. Installation <a name="installation"> </a> Requirements: Python 3.8, Python 3.9 #### 1.1 Quick Install One instruction to download our software on command line, such as Terminal on macOS, CMD on Windows. ``` $ pip install geochemistrypi ``` **Note**: **\$** refers to the command line interface. Don't copy **\$**. The beta version runs on MacOS, Windows or Linux. Make sure that your network is stable while downloading. #### 1.2 Advanced Install It is highly recommended downloading in an isolated virtual python environment, which prevents messing up your system python packages. **Step 1:** Create an virtual environment ``` $ python -m venv my_virtual_environment_name ``` Note: The only element to change is ***my_virtual_environment_name***. If ***python*** fails, try with ***python3***. The instruction above will create an virtual environment on the current directory. **Step 2:** Activate the virtual environment (1) Operating System: macOS or Linux In the same directory, run this instruction: ``` $ source my_virtual_environment_name/bin/activate ``` (2) Operating System: Windows In the same directory, run this instruction: ``` $ my_virtual_environment_name\Scripts\activate.bat ``` **Step 3:** Download our software ``` $ python -m pip install geochemistrypi ``` Make sure that your network is stable while downloading. After testing two methods, if you still fail to download, please refer to part 4 \<bug report\> . ### 2. Example<a name="example"> </a> **Beta version:** It only supports the command to apply data mining techniques to deal with your own data. More algorithms and their related functions will be appended to our software in the following released versions. **How to run:** After successfully downloading, run this instruction on command line whatever directory it is. It will takes some time to load the software into your CPU and memory when the first time to run the software. Just be patient! If it still fails, press ***control+c*** to stop and try again. **Case 1:** Run with built-in data set for testing ``` $ geochemistrypi data-mining ``` **Note**: There are four built-in data sets corresponding to four kinds of model pattern, regression, classification, clustering, decomposition. **Case 2:** Run with your own data set ``` $ geochemistrypi data-mining --data your_own_data_set.xlsx ``` **Note**: Currently, only `.xlsx` file is supported. Please specify the path your data file exists. The only element to change is ***your_own_data_set.xlsx***. If you run the command above, it means the command is executed under the directory your data file exists. Related processed results will be in the same directory. **Other Commands:** ``` $ geochemistrypi --help ``` It shows the related information of our software, including brief introduction and commands. ``` $ geochemistrypi --install-completion zsh ``` It allows to configure auto-completion function for users' computer. The only element to change is ***zsh***. After relaunching the shell (Terminal on macOS, CMD on Windows). You can use *tab* on your keyboard to implement auto-completion. ``` $ geochemistrypi --show-completion zsh ``` It shows the codes of configuration of auto-completion on your computer. The only element to change is ***zsh***. ``` $ geochemistrypi data-mining --help ``` It shows the infomation of *data-mining* command. ### 3. Data Format<a name="data"> </a> In order to utilize the functions provided by our software, your own data set should satisfy: + be with the suffix ***.xlsx***, which is supported by Microsoft Excel. + be comprise of location information ***LATITUDE*** and ***LONGITUDE***, two columns respectively. When you run into the step ***Data Selected*** ( -> Data Selection), you should ensure that the chosen sub data set needs to be numerical type in all columns. Because: + Currently, our software are not perfect enough to have the function to detect the column's data type in your data set. + The following steps is based on the assumption that your chosen columns should all be numerical type. It allows the user to have missing values in their chosen columns but one column full of null values without any useful data point would fail the program too. If you want to run classification algorithm, only supporting binary classification currently, you data set should satisfy: + Tag column ***LABEL*** to differentiate the data The following are four built-in data set in our software stored on Google Drive, have a look on them. + [Data_Regression.xlsx (International - Google drive)](https://docs.google.com/spreadsheets/d/13MB4t_2PiZ90tTMJKw7HcBUi2sb3tXej/edit?usp=sharing&ouid=110717816678586054594&rtpof=true&sd=true) + [Data_Regression.xlsx (China - Tencent Docs)](https://docs.qq.com/document/DQ3VmdWZCTGV3bmpM?&u=6868f96d4a384b309036e04e637e367a) + [Data_Classification.xlsx (International - Google drive)](https://docs.google.com/spreadsheets/d/1xFBCYVmtZfuEAbeBljUlzqBjxVuLAt8x/edit?usp=sharing&ouid=110717816678586054594&rtpof=true&sd=true) + [Data_Classification.xlsx (China - Tencent Docs)](https://docs.qq.com/document/DQ0JUaUFsZnRaZkNG?&u=6868f96d4a384b309036e04e637e367a) + [Data_Clustering.xlsx (International - Google drive)](https://docs.google.com/spreadsheets/d/1sbuJdOzGNQ2Pk-bVURfPYg1rltyBbn5J/edit?usp=sharing&ouid=110717816678586054594&rtpof=true&sd=true) + [Data_Clustering.xlsx (China - Tencent Docs)](https://docs.qq.com/document/DQ3dKdGtlWkhZS2xR?&u=6868f96d4a384b309036e04e637e367a) + [Data_Decomposition.xlsx (International - Google drive)](https://docs.google.com/spreadsheets/d/1kix82qj5--vhnm8-KhuUBH9dqYH6zcY8/edit?usp=sharing&ouid=110717816678586054594&rtpof=true&sd=true) + [Data_Decomposition.xlsx (China - Tencent Docs)](https://docs.qq.com/document/DQ29oZ0lhUGtZUmdN?&u=6868f96d4a384b309036e04e637e367a) ### 4. Bug Report<a name="bug"> </a> Due to the problems of dependency management in Python and specific computers configuration, you might encounter some unpredictable issues when downloading our software. **Issue 1:** Http problem. It is caused when your network is unstable. Solved: a) Make sure the network works well; b) Try *pip* install instruction shown above several times until it downloads all denpendencies. **Issue 2:** Dependecy version. It is caused when not to use virutal environment. Solved: Download our software in an isolated virtual environment, try with ***advanced install*** above. **Issue 3:** Fail to run with the command ***geochemistrypi data-mining***. Solved: Press ***control+c*** on the keyboard to stop and try several times. **Issue 4:** Python version. When Python > 3.9, such Python 3.10, Python 3.11, pip install will fail. Solved: Lower your Python version to Python 3.8 or Python 3.9. Please google it. **Issue 5:** Fail to run other steps after the step ***Data Selected*** ( -> Data Selection). Solved: Make sure in the chosen sub data set should be all numerical types. Refer the the third part **Data Format**. **Ways to report other bugs** (downloading or running the software): 1. Contact Sany (Email: sanyhew1097618435@163.com) with the title as "Bug: Geochemistry Pi". 2. Open a GitHub issue and follow the [template](https://github.com/ZJUEarthData/geochemistrypi/issues/26) to detail the problem. We promise to get you in contact as soon as possible. ### 5. Advice<a name="advice"> </a> The software is in beta version currently. There are too many shortcomings which we need to improve in the future. It would be highly appreciated if you can share your opinions on how to make it better. However, considering the tradeoff of time and cost, it is likely that we are unable to perfect parts of the functions in time. Here, we would like to exten our warm invitation to you to join in this open-source software project to make your own contribution to the whole community. You will learn the whole framwork through our specialized training procedure and be able to make customization on your own. For more Information, check our GitHub page (International) or Gitee page (China). + [Github - geochemistrypi](https://github.com/ZJUEarthData/geochemistrypi) + [Gitee - geochemistrypi](https://gitee.com/zju-earth-data/geochemistrypi) **Ways to Contact:** + Can He (Email: sanyhew1097618435@163.com) with the title as "Advice: Geochemistry Pi". + ZJU Earth Data: zhangzhou333@zju.edu.cn