Installing & Quickstart#

Why Python ?#

watex is designed using the Python programming language because of its easy accessibility, clear syntax, and interactive shell environment. Secondly, Python is freely distributed and the powerful numerical libraries (NumPy , SciPy , Pandas , SQLite ), to handle a large data sets and scikit-learn for prediction purposes.

Installing#

watex has been tested on the virtual machine Pop_OS Linux env and runs successfully. Please follow the different steps below to properly install the software. The system requires preferably Python >=3.9 at the time of writing. Python can be downloaded from anaconda . Miniforge3 also provides a conda-based distribution of Python and the most popular scientific libraries.

python 3.9

It is possible to install watex from source, using anaconda prompt or GUI .

From PyPI#

watex can be obtained from PyPI platform distribution as:

pip install watex

Use pip install -U watex for window users instead. Furthermore, to get the latest development of the code, it is recommended to install it from source.

From conda-forge#

Installing watex from the conda-forge channel can be achieved by adding conda-forge to your channels with:

    conda config --add channels conda-forge
conda config --set channel_priority strict

Once the conda-forge channel has been enabled, watex can be installed with:

conda install watex

It is possible to list all of the versions of watex available on your platform with:

conda search watex --channel conda-forge

From source#

To install from the source, clone the project with git and download the latest version from the project webpage: WEgeophysics/watex :

git clone https://github.com/WEgeophysics/watex.git  # add --depth 1

Moreover, if you plan on submitting a pull-request, you should clone from your fork instead.

Using Prompt#

Option 1: Recommended

If you installed Python with conda, we recommend to create a dedicated conda environment with all the hard dependencies of watex. For instance, you can globally set up a virtual environment <venv> and install dependencies( see example below). Note the <venv> can be any environment name. For instance <py39> for Python 3.9 as:

conda create -n venv python=3.9
conda activate venv
pip install scikit-learn xgboost seaborn pyyaml pyproj joblib openpyxl

Some dependencies come with others and we dont need to install the full hard-dependencies to take advantage of the basic implementation. However for consistency, you can install the full hard-dependencies like

pip install scikit-learn numpy scipy pandas matplotlib tables h5py xgboost seaborn openpyxl pyyaml h5py joblib

Check the list of optional dependencies to take advantage of additional functionalities.

Note

If you use conda install <package name>, some dependencies are not available in conda-forge you may use pip instead.

Option 2: creating virtualenv under the root of project (Optional)

If you want to create your virtual environment under the root folder named watex, the steps below can guide you to check whether the installation is well done. The advantage of creating the virtualenv under the project root is that you do not need to set up the jupyter notebook environment variable.

python -m  venv venv`  #(on Window )
python -m venv ./venv` #(on Linux)

You can check your new environment and list the tree packages using:

ls venv/
tree venv/

then you can activate the environment using:

venv\Scripts\activate   # (on Window )
source ./venv/bin/activate      # (on Linux )

You may update and upgrade pip, setuptools and wheel as :

python -m pip install --upgrade pip
pip install setuptools --upgrade
pip install wheel --upgrade

Finally, you can install the software full dependencies dependencies using conda or pip. The command should be:

conda install scikit-learn=1.1.2  xgboost seaborn pyyaml pyproj joblib openpyxl h5py tables numpy scipy pandas matplotlib missingno pandas_profiling pyjanitor yellowbrick mlxtend

For a rapid execution of the script, you can also install scikit-learn-intelex.

conda install scikit-learn-intelex

Using GUI#

This installation is also optional. After installing Anaconda, you can download the watex zip codes here . Then, unzip the project, open spyder, pycharm or any other IDEs and set the root to your environment name. Follow the steps below for clarity.

open the Anaconda Navigator app
In the left sidebar, select Environments, then at the bottom of the window select Create
Give your new environment a suitable name and select Python 3.9 as the package, then press the green Create button to confirm.
Select the environment you have created from the list of available environments and in the package window to the right,
Select Not installed from the drop-down and enter gdal and ` libgdal , then click the `Apply button in the lower right corner and a window will display confirming dependencies to install,
Repeat the process for all dependencies.

Dependencies#

The following packages are the dependencies of the watex divided into the hard-dependencies and the optional dependencies. The hard-dependencies are all needed for the software to run properly.

Hard dependencies	Minimum version	Come with
scikit-learn	>=1.1.2
xgboost	>=1.5.0
seaborn	>=0.12.0
pyyaml	>=5.0.0
pyproj	>=3.3.0
joblib	>=1.2.0
openpyxl	>=3.0.3
h5py	>=3.2.0	pandas
tables	>=3.6.0	pandas
numpy	>=1.23.0	scikit-learn
scipy	>=1.9.0	scikit-learn
pandas	>=1.4.0	seaborn
matplotlib	>=3.3.0	seaborn

In principles the dependencies first six dependencies are the required. For instance , scikit-learn dependency comes with numpy and scipy, and don’t need to install again. The following table shows the optional dependencies

Optional dependencies	Minimum version
missingno	>=0.4.2
pandas_profiling	>=0.1.7
pyjanitor	>=0.1.7
yellowbrick	>=1.5.0
mlxtend	>=0.21
tqdm	>=4.64.1

conda or pip can both use to install the dependencies as:

conda install <package-name>

If the dependencies does not exist in conda-forge (e.g. pyproj), use pip instead as:

pip install <package-name>

Getting started#

For quickstart with watex, the following import strategy is suggested:

>>> import watex as wx

There are two ways to import modules, classes, or functions from ~watex, the shorthand, and the complete import strategies. For instance, to get the list of seven geological structures and structural pieces of information, we can use:

shorthand import strategy: wx

>>> # for geological structures
>>> #
>>> import watex as wx
>>> geo_structures= wx.Structures().fit()
>>> geo_structures.names_ [:7]
('argillite',
 'alluvium',
 'amphibolite',
 'anorthosite',
 'andesite',
 'aplite',
 'arkose')
>>> #
>>> # for structural infos
>>> #
>>> structurals= wx.Structural().fit()
>>> structurals.names_ [:7]
('boudin_axis',
 'fold_axial_plane',
 'banding_gneissosity',
 's_fabric',
 'fault_plane',
 'fracture___joint_set',
 'undifferentiated_plane')
>>> structurals.boudin_axis.code_
'lsb'
>>> structurals.boudin_axis.name_
'Boudin Axis'

complete-import strategy: from watex.~

>>> from watex.geology import Structures
>>> geo_structure = Structures().fit()
>>> geo_structure.names_[:7]
('argillite',
 'alluvium',
 'amphibolite',
 'anorthosite',
 'andesite',
 'aplite',
 'arkose')
>>> from watex.geology import Structural
>>> structurals=Structural().fit()
>>> structurals.names_ [:7]
('boudin_axis',
 'fold_axial_plane',
 'banding_gneissosity',
 's_fabric',
 'fault_plane',
 'fracture___joint_set',
 'undifferentiated_plane')
>>> structurals.boudin_axis.code_
'lsb'
>>> structurals.boudin_axis.name_
'Boudin Axis'

In the example above, both codes yield the same results, however the shorthand is limited to the public API which is determined based on the documentation. The class, functions, and modules presumed to be the most used for solving an immediate specific task, are displayed as public API. To more-in depth implementation, used the complete-import strategy instead.

For more about the core and the data structure, visit the structure page. However, for any issue or contributing to the software development, please check the development guide.