.. _comments: 

v0.1.6-alpha (February 22, 2023) 
---------------------------------

These are minor changes performed from ``v0.1.5`` after the review :ref:`comments <comments>` from Editors and Reviewers 
from the `softwareX <https://www.sciencedirect.com/journal/softwarex>`__ journal to improve the paper and software. 
The manuscript faced two review tours of **minor revisions**. The first from reviewers (February 20th) and second from Editors(March 06th ). 
Here are the comments/replies sections of Editors/reviewers that includes some bug fixes and improvements. 
The Editors/reviewers comments are in *italic* whereas the replies are in normal text. 
   

First review 
~~~~~~~~~~~~~~~

The first reply from Editors/reviewers occurs in February 20th, 2022. Here are the comments: 


.. _reviewer1: 
  
Reviewer #1 
^^^^^^^^^^^^

*I have read the paper* ``"machine-learning research in hydro-geophysics"``. *It is an interesting paper about the 
application of* :term:`machine learning` *in* :term:`hydrogeophysics` *and the open-source code is also useful for hydrogeophysics 
society. After I tested the codes, I found parts of the codes may be improved. The paper is generally 
well-written and I recommend it to be published after a minor revision. Here are my comments:*

* **1)** *It seems useful to consider the ``openpyxl`` package as a hard dependency. Some modules in the "Geology "
  sub-package are called public API which uses "openpyxl" (see watex.__init__.py file). When 
  running watex for the first time, the missing "openpyxl" is required. To avoid this annoyed behavior and fix 
  the bug, try to set "openpyxl" as the required dependency or move the geology 
  module (Structures and Structural) from the public API.*
..

* *Reply:* ``openpyxl`` is now part of the hard dependency at the initiliation of the package. This is visible  
  in code lines 66–67 of ``watex.__init__.py``. 
..

* **2)** *To make the software more attractive at the glance for the non-dedicated reader in the* :term:`geophysical` *and* 
  :term:`hydrogeology` *domains, the term "hydro-geophysics" can be modified to "water exploration "for short 
  as the aim goal and name of the software. I suggest* `"Machine learning in water exploration"`` *or* ``"machine learning 
  research in water exploration"``. *The first one is short and global while the second gives a new perspective 
  since the term research in the title makes the software dynamic and new methods can be added and 
  included many geosciences fields that imply water exploration.*
..

* *Reply:* We have selected the second choice and modified the title in the revised version of the paper. 
  The title becomes ``“machine learning research in water exploration”``. We also modified the abstract 
  a bit more for consistency.    
..

* **3)** *In the module* :mod:`watex.methods.em`, *the authors computed the skew* ( :meth:`watex.methods.Processing.skew`) *from the Processing module As the 
  mathematical concept is explained, it should be better to write the code for skew visualization 
  from Bahr or Swift. This could help users to easily determine the type of structures (1D, 2D, 3D or 
  distorted, …) without the necessary output of the two-dimensional matrices. (See the references guide in 
  the docstrings ).* 
..

* *Reply:* A new code plot plotting skew is henceforth written. The phase-sensitive skew can be visualized 
  using the :func:`watex.utils.plot_skew` function.  In addition, we also give a consistent 
  plot for skew visualization in  :meth:`watex.view.TPlot.plotSkew` method where the user can 
  easily customize the plot accordingly. Furthermore, the :meth:`watex.view.TPlot.plot_phase_tensors` 
  plot also gives an alternative way for skew visualization in pseudo-section format by specifying 
  the `tensor` parameter to `skew`. Here are two examples of skew plots.

  - *Plot skew* from (:func:`watex.utils.plot_skew`)::  

  >>> import watex as wx 
  >>> from watex.utils.plotutils import plot_skew 
  >>> edi_sk = wx.fetch_data ("edis", return_data =True , samples = 20 ) # fetch 20 samples of EDI objets
  >>> plot_skew (edi_sk) 
  >>> plot_skew (edi_sk, threshold_line= True)

  - *Plot skew from phase tensor plot* ( :meth:`watex.view.TPlot.plot_phase_tensors`)::

  >>> tplot = wx.TPlot ().fit(edi_sk ) 
  >>> tplot.plot_phase_tensors (tensor ='skew')
  
  See also the examples :ref:`sphx_glr_glr_examples_utils_plot_skew.py` and :ref:`sphx_glr_glr_examples_methods_plot_phase_tensors.py`.  
  
..

* **4)** *I suggest writing a complete application example as you did for predicting* :term:`k` *"in the step-by-step" 
  guide in the software documentation that involves the missing tensor and recovery of 2D tensors. 
  It seems you used the preprocessed data* (from :func:`watex.datasets.load_edis`) *for illustration where no 
  missing data is available. This is not meaningful.*
..

* *Reply:*  To solve this issue, we used a real dataset collected from Huayuan area, Hunan province, China,  
  which is composed of missing tensors. We implement in this new version, the data set function 
  as `load_huayuan` (:func:`watex.datasets.load_huayuan`). The parameter `raw` can allow to retrieval of noised 
  data for the sake of user to better comprehend the trick behind the recovery tensors. 
  For demonstration and a real guidance,  we fetched 27 sations and the result 
  are displayed and missing tensors can be vsualized as well as the way to handle them. 
  Here is quick implementation, however in  the :doc:`gallery example <https://watex.readthedocs.io/en/latest/glr_examples/index.html#>`, 
  the step-by-step guide gives further explanations:
 
  .. code-block:: python 
  
      >>> data = wx.fetch_data('huayuan', return_data =True, samples =27 ,
                           key ='raw', clear_cache=True) # clear watex cache data to save new EDI
      >>> tro = wx.EMProcessing().fit(data)
      >>> wx.view.plot2d(tro.make2d(out= 'resxy' ) , y = tro.freqs_,to_log10= True) 

  The results shows blank spaces in resistivity tensor in TE mode (``xy``). After applying the recovery 
  trick, all complete tensors has be recovered at all frequencies as::  

  >>> tro.component ='yx'  
  >>> wx.view.plot2d(tro.zrestore ( tensor ='res'), y = tro.freqs_,to_log10= True) 

  After recovery, the data is full-strength amplitudes for processing. More examples in :ref:`sphx_glr_glr_examples_applications_plot_tensor_restoring.py`
  and :ref:`sphx_glr_glr_examples_methods_plot_phase_tensors.py`. 
   
..

* **5)** *The motivation illustrates the importance of hydrology but lacks an illustration of the importance of 
  hydrogeophysics. I suggest adding a part to introduce the development of hydrogeophysics and how it helps 
  hydrology studies* (e.g., Binley et al., 2015 [1]_ ; Parsekian et al., 2015 [2]_; Chen, 2022 [3]_)
..

* *Reply*: Fixed it in the manuscript new version (Fixed it in new MS) 

.. _reviewer2: 

Reviewer #2 
^^^^^^^^^^^^^^^

* **1)** *(Lines 137-142) the parameters are computed from the selected conductive zone; the loss or weak frequency 
  signal are recovered and new tensors are updated. Please provide more details about the computation process, 
  and how to recover and update the related dataset.*
..

* *Reply:* The explanation of this section has been enforced in the revised MS and clearly explained 
  with the different options the user can use for selecting and recover\update the tensors.
  The example :ref:`sphx_glr_glr_examples_applications_plot_tensor_restoring.py` gives more details.  

..

* **2)** *(Lines 146-148) What is the meaning of the 'features manipulation got from the previous step'?*
..

* *Reply*: Fixed it in new MS and reformulate the sentence as follow: - [The next step (`Params space`)  consists to 
  aggregate the different prediction parameters computed from the previous step to build the 
  predictor :math:`[X,y ]`  or export for :term:`EM` modeling in the case of :term:`NSAMT` to external software ...]
..

* **3)** *(Lines 149-154) In 'learning space' step, what are the algorithms applied for the training and 
  testing models? Is the algorithm freely selected by the user or automatically 
  selected according to the previous datasets? How to determine the 'appropriate modules' ?*
..

* *Reply:* Fixed it in the MS. We replied to this section in the replied MS by giving the step and some 
  appropriate algorithms for feature transformations whereas the training and testing models 
  are handled by the “models”(:mod:`watex.models`) module. See the software functionnalities 
  section of the paper in `Learning space`. Below is an example for what we explain the manuscript. 

  When the user objective is to predicting :term:`FR` , user can select some pretrained 
  models of :mod:`watex.models`. To get the available of pretrained models, user can do this:

  .. code-block:: python 
  
      >>> from watex.models.premodels import p 
      >>> p.keys
      ('SVM', 'SVM_', 'LogisticRegression', 'KNeighbors', 'DecisionTree',
         'Voting', 'RandomForest', 'RandomForest_', 'ExtraTrees', 
         'ExtraTrees_', 'Bagging', 'AdaBoost', 'XGB', 'Stacking'
      ) 
  
  For instance to fetch the pretrained :class:`watex.exlib.LogisticRegression` best parameters, just call: 

  .. code-block:: python 
  
      >>> p.LogisticRegression.best_params_ 
      {'penalty': 'l2',
      'dual': False,
      'tol': 0.0001,
      'C': 1.0,
      'fit_intercept': True,
      'intercept_scaling': 1,
      'class_weight': None,
      'random_state': None,
      'solver': 'lbfgs',
      'max_iter': 100,
      'multi_class': 'auto',
      'verbose': 0,
      'warm_start': False,
      'n_jobs': None,
      'l1_ratio': None
      }

  However some models with :term:`geology` structures collected in a particular area could obviously not correspond 
  to the pretrained geological survey area. In that case, user can retrain its data to fine-tune 
  models :term:`hyperparameters` into a single line of codes by feeding to the algorithms many models and save 
  the :term:`training` phase results into a disk. Here is an example:
  
  .. code-block:: python 

    >>> from watex.models import GridSearchMultiple , displayFineTunedResults
    >>> from watex.exlib import LinearSVC, SGDClassifier, SVC, LogisticRegression
    >>> X, y  = wx.fetch_data ('bagoue prepared') 
    >>> X
    ... <344x18 sparse matrix of type '<class 'numpy.float64'>'
    ... with 2752 stored elements in Compressed Sparse Row format>

  As example, we can build four estimators and provide their grid :term:`parameters` range for fine-tuning as:

  .. code-block:: python 
  
      >>> random_state=42
      >>> logreg_clf = LogisticRegression(random_state =random_state)
      >>> linear_svc_clf = LinearSVC(random_state =random_state)
      >>> sgd_clf = SGDClassifier(random_state = random_state)
      >>> svc_clf = SVC(random_state =random_state) 
      >>> estimators =(svc_clf,linear_svc_clf, logreg_clf, sgd_clf )
      >>> grid_params= ([dict(C=[1e-2, 1e-1, 1, 10, 100], gamma=[5, 2, 1, 1e-1, 1e-2, 1e-3],kernel=['rbf']), 
                dict(kernel=['poly'],degree=[1, 3,5, 7], coef0=[1, 2, 3], C= [1e-2, 1e-1, 1, 10, 100])],
                [dict(C=[1e-2, 1e-1, 1, 10, 100], loss=['hinge'])], 
                dict()], # we just no provided parameter for logreg_clf to let user try by himseft)
                [dict()] # idem for sgd_clf
                )

  Now  we can call :class:`watex.models.GridSearchMultiple` for training and self-validating as:
  
  .. warning::
  
    Note that if you decide to run the script below , it will take a while depending of your processor 
    performance. However, we recommend to try as you can and alternatively, you can also provide 
    the parameter range of :class:`watex.exlib.LogisticRegression` & :class:`watex.exlib.SGDClassifier` for 
    for fine-tuning. Moreover, you can also do the same task by setting the :class:`watex.models.GridSearchMultiple` 
    parameter `kind` to ``RandomizedSearchCV`` for exercice. 
  
    .. code-block:: python 
  
        >>> gobj = GridSearchMultiple(estimators = estimators, 
                           grid_params = grid_params ,
                           cv =4, 
                           scoring ='accuracy', 
                           verbose =1,   # set minimum verbosity ; > 7 outputs more messages 
                           savejob=False ,  # set true to save your job into a binary disk file.
                           kind='GridSearchCV').fit(X, y)
   
  Once the parameters are fined-tuned, we can display the fined tuning results using 
  :func:`watex.models.displayFineTunedResults` functions or other similar functions 
  in the module: :mod:`watex.models.validation` like : :func:`watex.models.displayModelMaxDetails` 
  or :func:`watex.models.displayCVTables` or else as: 

  .. code-block:: python 
  
      >>> displayFineTunedResults (gobj.models.values_)
      MODEL NAME = SVC
      BEST PARAM = {'C': 100, 'gamma': 0.01, 'kernel': 'rbf'}
      BEST ESTIMATOR = SVC(C=100, gamma=0.01, random_state=42)
      MODEL NAME = LinearSVC
      BEST PARAM = {'C': 100, 'loss': 'hinge'}
      BEST ESTIMATOR = LinearSVC(C=100, loss='hinge', random_state=42)
      MODEL NAME = LogisticRegression
      BEST PARAM = {}
      BEST ESTIMATOR = LogisticRegression(random_state=42)
      MODEL NAME = SGDClassifier
      BEST PARAM = {}
      BEST ESTIMATOR = SGDClassifier(random_state=42)

..

* **4)** *(Lines 155-158) 'enough plots for data exploration, feature analysis and discussion, tensor recovery, 
  and model inspection'. In View space part, in addition to the sounding curve plot and DC-parameters 
  discussing plot as shown in Figures 2 and 3, what kind of plots can be provided for the above exploration 
  and analysis?*
..

* *Reply:* Some examples of plots with their functionalities are enumerated in the revised MS  
  in software functionalities: - [in ExPlot (:class:`watex.view.ExPlot`) ...  :func:`watex.utils.plot_sbs_feature_selection` 
  plots Sequential Backward Selection (SBS) for feature selection and collects the scores of 
  the best feature subset at each stage...]

  Refer to :ref:`full user guide <user_guide>` and :ref:`view <view>` for further documentation. 
..

* **5)** *In this work, how to reduce the collection of k-parameter? Please provide some comparisons 
  or explanations to show the differences from the expensive k parameter detection in previous work.*

* *Reply:* We replied to this answer in the revised MS in the motivation and significance section and 
  about the k-parameter prediction, we have submitted a paper in 
  `Engineering Geology <https://www.sciencedirect.com/journal/engineering-geology>`__, 
  and is still under consideration (http://dx.doi.org/10.2139/ssrn.4326365). 
..

* **6)** *Comments for the Software/Code:*

* **6.1)** *(Line 1564 - 1780) Tensors recovery in the processing module
  The method "zrestore" is used to recover the weak and missing signals in the EDI data. I have run the method, 
  but it seems you used the preprocessed data (Impedance tensors are already recovered) for illustration. 
  This is visible in the documentation too. It looks not seem meaningful to practice this way. Even if the 
  data is not available, you can:* 

  - *generate a synthetic data where the tensor is missing and then apply the recovery technique to 
    recover the missing tensors, or*
  - *use a sample of real-world EDI data (if data is available) where data is noised and the signals are 
    missing , then use the recovery approach with the method "zrestore" to recover it.*
 
  *You may select one of these options. This is useful to show the readers and scientific community the 
  relevance of the technique and ascertain its trueness.*
  
..

* *Reply:* We selected option 2 and we provided a convenient application step-by-step guide with a 
  concrete example of a missing tensor in the Huayuan survey area for the user. This comment 
  seems addressed too closely to comment 4 of :ref:`reviewer #1 <reviewer1>` Our answer is explained in 
  supported by examples. Please, could refer to the reply section of comments N4 of :ref:`reviewer #1 <reviewer1>`.  
..

* **6.2)** *(Line 779 - 1021 ) Fix the bug in ResistivityProfiling class in module electrical
  Indeed, when the constraints are applied and the auto-detection indicates that there is no possibility of 
  making a drill on this ERP line. It is better to stop the running "fit" method rather than 
  let it continue since no DC parameters can be calculated. Formatting a warning message to the user is 
  very important in that case. This is not applied in your case. For instance, after running, the user 
  can think that parameters are correctly calculated and could try to fetch the table of prediction parameters. 
  While no parameters are calculated the summary method of ResistivityProfiling generates a "getattributeError". 
  You may try to fix it by formatting the warning message in the summary method 
  ( if applicable ) and stopping the running process of the "fit" method.*
..

* *Reply:* Thanks for this suggestion. We fixed it and stop running the program when no suitable area 
  for the drilling location is found when constraints are applied. Henceforth, an :class:`~watex.exceptions.ERPError` raises, 
  and a warning message is thrown that no suitable location was detected. Furthermore, there 
  is another exception emitted in summary methods to smartly warn users that :term:`DC` parameters cannot be 
  computed when the :term:`ERP` line is not suitable for the drilling location. (refer to code line 999 -1021 of  
  :meth:`~watex.methods.ResistivityProfiling.summary` method  ). 
..

* **6.3)** *(Structural class Line 335 ) Module geology. The verbose attribute is not set properly. 
  While Structural inherits from module Base, 'verbose' must be set in the Base module since "Super" 
  will call it straightforwardly.*
..

* *Reply:* We fixed by implementing `verbose` parameter as an attribute in :class:`watex.geology.core.Base` 
  module of ( Line 80  and 82) 

Second review 
~~~~~~~~~~~~~~~~

The second reply from Editors occurs in March 06th after the first requiered review completed. Here are the comments: 

* **1)** *Abstract: It needs to be an abstract for a multidisciplinary audience.  You do not define DC, EM or what is the meaning of the k parameter.  Can you make it more general?*
..

* *Reply*: We fixed it by defining the :term:`DC` (Direct-current), :term:`EM` ( Electromagnetic ), and :term:`k` for the permeability coefficient.  Also, we replaced especially for the abstract the word 
  ":term:`tensor`" with "missing data" in the following sentence: << Indeed, the recovery of EM *tensors* … >> by  << Indeed, the recovery of EM *missing data* … >> 
..

* **2)** *Intro: - I suggest splitting up the first paragraph (it is very long).  Maybe at lines 58 and 75?*
..

* *Reply*: We did it. The first paragraph is henceforth divided into two. 
..

* **3)** *Again note that the first paragraph should be written for a general audience whereas it gets very technical and I have a hard time understanding it.  Can you try to make the first paragraph for a general reader like me.?*
..

* *Reply*: Of course! We have tried our best to reconsider all the technical words and translated them into simplified terms and sentences.  As you can see in the 
  manuscript  first paragraph (henceforth divided into two), we have simplified some sentences by rewriting them expecting to be easily understood by public audience. 
..

* **3)** *Fig3.  might be better in 2x2 rather than 1x4 format*
..

* *Reply*: We fixed it by combining it with the first new figure and deleting the literature related to him in the illustration example (previous version). 
  The figure is henceforth moved to the software functionalities section when enumerating the different possible plots offered by the library in addition to the two new others plots. 
  To support the comment of :ref:`reviewer #2 <reviewer2>` about the additional plots that can be provided by the software, we also added two plots (:func:`watex.utils.plot_confidence_in` and :meth:`watex.view.TPlot.plot_phase_tensors`)
  for clarity since Figure speaks more than ten thousand words. The total figures are henceforth 4 rather in the new version rather than the 3 in the previous version. 
..


We are grateful to the anonymous reviewers for their contributions,  suggestions and comments to  improve the 
MS and fix bugs in the software for the :term:`GWE` research progress.

Best regards!

  
.. topic:: References 
  
  .. [1] Binley, A., Hubbard, S.S., Huisman, J.A., Revil, A., Robinson, D.A., Singha, K. and Slater, L.D., 2015. 
         The emergence of hydrogeophysics for improved understanding of subsurface processes over multiple 
         scales. Water resources research, 51(6), pp.3837-3866.
  .. [2] Parsekian, A.D., Singha, K., Minsley, B.J., Holbrook, W.S. and Slater, L., 2015. Multiscale geophysical 
         imaging of the critical zone. Reviews of Geophysics, 53(1), pp.1-26.
  .. [3] Chen, H., 2022. Exploring subsurface hydrology with electrical resistivity tomography. 
         Nature Reviews Earth & Environment, 3(12), pp.813-813.