General comments

The paper is an interesting and innovative application of methods to extract meaningful quantified standardised information from highly heterogeneous drill log data that are typical of legacy mineral exploration. Even within company-imposed data structures, the logging geologists have historically recorded subjective data inconsistently and this hinders bulk aggregation of these data.  The classification methods in this paper using open source scripts and libraries show potential to efficiently find similarities between logged lithological terms, codes and descriptive comments using hierarchical semantic relationships.

The paper is too long and dense in terminology and nuanced meaning. The authors have endeavoured to symbolise some of the different and complicated database terminology although possibly more is needed. The flow is logical and the writing is generally understandable although laboured in places. The figures and tables are appropriate and informative in most places; some minor improvements have been suggested. I have not checked references or URL links exhaustively.

Specific comments

Introduction, section 1: replace first 2 sentences with 'Drilling is a process of penetrating through the ground that is capable of extracting information about rocks from various depths below the surface. This is useful for establishing the geology beneath. Drill core or cuttings can be collected thus providing samples for description, interpretation and analysis.'

Introduction, section 3: The legacy data described seem to be hardcopy forms subsequently digitised.  Legacy digital data also suffer from lack of standardisation, inconsistency.

Introduction, line 78: These data are not 'unstructured' but they may not conform to standards or be consistently applied/described.

Material and Methods, Conventions: workflows need their own distinct convention (font). Later they are confusingly rendered as combinations of database table fields.

Thesauri: Some of the so-called 'synonyms' actually have distinct meanings from each other, even the listed example elevation vs relative (reduced) level. Maybe qualify 'synonym' as meaning 'nearly the same' or a 'close match' for their general intent is similar e.g the elevation terms all are recording a vertical height.

Thesauri, line 245:  Rather than 'The opposite is true as well' suggest you explain specifically that more than one code may refer to the same lithology. Basically there is a many-to-many relationship between code and lithology.

Thesauri, line 252: The CGI vocabularies support the GeoSciML and EarthResourceML (note singular) geology data models but potentially other applications. Suggest you rephrase as '...the CGI-IUGS geoscience vocabularies accessible at http://geosciml.org/resource/def/voc/'.

Thesauri, Lithology Hierarchical Thesaurus: The 3-level hierarchy is highly simplified compared to CGI's Simple Lithology. Many of the 'Lithology_Subgroups' listed have parent-child relationships e.g. 'mafic_fine_grained_crystalline' is a child of 'mafic'. This should be mentioned, presumably some simplification and pragmatism is needed for your analysis.

Data Extraction, Collar Extraction: I wondered why this section needs to be here at all. The collar extraction isn't central to your paper focus on lithology. You don't utilise collar location in a spatial analysis or context - its only function in this paper seems to be a pre-filter for data quality. The method itself is good and useful, and ultimately important for data mining where spatial understanding is needed, just not essential for the lithology-driven analysis presented here.

Data Extraction, Survey Extraction: Ditto, I wondered why this section needs to be here at all. If it is retained then suggest the 4^th field should be ‘Inclination’ not ‘Dip’. Dip is a measurement of the slope of a planar surface feature whereas inclination refers to the plunge of a linear feature. Additionally, how consistent are WAMEX records around positive inclinations meaning upwards-directed drill holes?

Data Extraction, Survey Extraction: The ‘Calculated X, Y, Z values’ are not particularly helpful or necessary in this Survey table i.e. only recording collar and the end of hole locations. Survey tables more typically describe changing azimuths and inclinations with ‘depth’ (i.e. account for curved drill holes) – does WAMEX not do this?

Data Extraction, Lithology Extraction: The fuzzywuzzy algorithm appears to be repeating pre-processing already mentioned in the previous paragraph (line 419-424).

Data Extraction, Line 432-433: What does ‘Since the sorted intersection component of token_set(), will result in an exact match…’ mean? Elaborate or explain more clearly.

Data Extraction, Line 439: What is an ‘intersection token’?

Data Extraction, Table 1: The column of ticks and crosses is unexplained. In two cases the lower score is ticked implying it is the preferred result?

Data Extraction, Line 453: ‘Andesitic basalt’ is an unfortunate example since ‘basaltic andesite’ is an established volcanic rock name. Would basaltic andesite wrongly revert to andesite in this classification process?

Data Extraction, Figure 8: I struggled to understand this graph. How can data with 100% Exact Match score only 80%?

Data Extraction Results, Unique Lithology Code Results: Database table field names seem to be inconsistent e.g. Company_LithoCode vs Company_Lithology vs Lithology_Code. Suggest careful check to ensure consistency of use otherwise confusing for the reader.

Data Extraction Results, Unique Lithology Code Results: Workflows such as ‘Lithology_Code Detailed_Lithology’ need to be distinctly symbolised. At the moment they look like co-joined database table names without an obvious algorithm progression between them. Suggest also where these are mentioned you mention ‘workflow’ or ‘workflows’

Data Extraction Results, Table 2: Struggling to understand why row 3 is a Close Match when the almost identical row 5 is a Broad Match? If anything the ‘basic volcanic rock’, not being a recognised Lithology_SubGroup member, is broader rather than closer than ‘mafic fine grained crystalline’.

Data Extraction Results, Fuzzy String Matching Results: Mentions of ‘comments’ should be ‘Comments’ in most cases, possibly with special font.

Data Extraction Results, lines 611, 622: These results are suboptimal. You discuss this later but it seems your method is sometimes picking a subordinate lithology rather than the dominant lithology.

Data Extraction Results, line 653: I wasn’t clear what ‘the limitation’ is – processing?

Discussion, Assessment of String Matching Results (line 844): Need to qualify that the ‘classification of structures and textures and metamorphic rocks’ has higher confidence in the study area dataset, not necessarily in others. I’m sure there will metamorphic-dominated terranes where the subordinate igneous rocks will be classified with higher confidence.

Technical corrections

line 44: delete ‘, particularly as it is likely to have been conducted by tens to hundreds of geologists...’  with something like ‘as all logging geologists have their own personal biases.

Line 49-50: delete ‘even detection of’

line 57: The semi-automatic methods also are poor at describing textural characteristics (foliation, banding, grainsize variation)

line 70” Delete ‘Elizabeth’?

line 105: limitations -> limitation

line 198: replace ‘that occurred’ with ‘were emplaced’

line 199: replace ‘ultramafic mafic’ with ‘ultramafic to mafic’ and ‘local centres’ with ‘local eruptive centres’.

line 201: replace ‘volcanoclastic’ with volcaniclastic’

line 203: delete ‘profiles’ and delete ‘both’. Break sentence after ‘bedrock’ and start next with ‘Regolith...’

line 209: suggest replacing ‘complexity’ with ‘diversity’

Figure 3 needs a unit to describe dill hole density e.g. per square kilometre

line 254: Insert after ‘Added records’ ‘with examples’

line 270: Replace ‘GeoSciML’ with ‘the CGI-IUGS Simple Lithology vocabulary http://resource.geosciml.org/classifier/cgi/lithology’

line 276: Suggest deleting second half of sentence i.e. after ‘dictionary’

line 294: Delete orphan ‘And’

Figure 4: Lighten purple shade (or whiten text within)

line 358: Replace ‘Dip: it is the inclination angle perpendicular to the azimuth…’ with ‘Inclination: the plunge angle of the drill hole relative to horizontal…’.

line 358-360: Replace sentence ‘A positive value indicates an upward-directed drill hole and a negative value indicates a drill hole directed downwards.’

line 411: Replace ‘The string followed by key phrases such as…’ with ‘The string preceded by key phrases such as…’

line 415: Does ‘tokens with less than three characters’ mean or include short words?

Line 434: Insert ‘method’ after ‘ratio()’.

Line 511: Font change in ‘Company_Lithology’.

Line 570: Where is the ‘brown text’ in Table 2?

Figure 10: Lighten purple shade (or whiten text within).

Line 598: replace ‘take a look’ with ‘looked’

Line 663: replace ‘couple of’ with ‘four’

Line 671: replace ‘trumps’ with ‘trump’

Line 833: What ‘information being fed itself’ mean?

Line 887: delete ‘a couple of’

In general, the article is well written and presents some valuable results. I’m not totally sure how it is related to the topic of the journal (modeling), but that’s a problem for the editor. There are several parts in the manuscript where results were presented including some methodological descriptions. Therefore, I suggest the authors a minor revision of the article, and to move some of the methodological parts in the results section to the materials and methods.

Here are some minor details:

Abstract:

Line 23: what is an extraction rate of 865? What units? Or is it a typo and should be 86.5%?

Introduction:

Line 43: I’m not sure if lithological drill core logging is “inevitably” subjective. In my impression, a lack of standardization in the lithological descriptions makes it subjective, but the subjectivity might be reduced through a standard procedure of description. However, it is not clear that such standardization is what we want.

Materials and methods

Line 146: ”The module was re-written into python to be make it more compact”... The grammar there sounds funny.

Line 195: Figure 2 seems to be wrongly enumerated in the text. The study area is referring to Fig 2, but it corresponds to Fig 3.

Figure 4: Regarding volcaniclastic rocks, they are classified as igneous and sedimentary. Is it ok to have the same subgroup in two lithological groups?

Line 325: it should be EPSG:4326 for WGS84

Line 326: Relative level with respect to the sea level? Does the relative level refers to any reference level or is it a standard level? Because if it refers to any reference level, there is no way to know the real location unless it is corrected using a DEM and assuming the collar at the surface of the terrain.

Results:

Line 498: you specified 820,612 entries for lithology, and 273,684 matched records with the thesaurus. What happened with the remaining 546,819 entries (66.6% of the total entries)?

Can you give a simple example of entries not matched?

Line 507: Does it mean that in about 40,000 records you had a ratio() score from the fuzzy string matching) lower than 80? Maybe you could be more explicit in this? Additionally, you defined the score threshold based on the exact match. But, might it be a kind of balance between the number of matched records and the exact match percentage? I’m just wondering because it seems that by defining that threshold you lose a lot of entries to be matched (83.5%).  Could you give a simple example of records not matched?

Lines 542 - 560: These are more materials and methods than results. 

Line 549: Couldn’t you get the rest of the hierarchical categories based on the lower hierarchy defined? 

Table 2. It gives an example of unmatched cases, so disregard that part of previous comments.

Lines 663 - 678. Accuracy metrics should be included in the materials and methods section and not in the results.

Discussion

Lines 812: Did you tried to replace the “same as above” with the descriptions?

Lines 824: Is there any way to automatise the building of a thesaurus given new advances in NLP and machine learning?

Line 831: “extraction rate of 16% from the Comments is not bad at all” This sounds too subjective, how do you define what is a good or a bad extraction rate?

Lines 852-853: “For sedimentary rocks, the lack of a standard syntax as to how comments are recorded impacts the classification. “ You see, imagine if such standardization is achieved, wouldn’t it reduce the subjectivity

Line 863: grammar error “ Soils are technically are not rocks”

Thank you for the opportunity to review this paper. It's good to see a case study applying open source tools to a common problem in subsurface — the extraction and regularization of data from open data stores. And it's fantastic to see reproducible research being produced and documented for the community. I wish more research in our field followed your excellent example.

I am recommending 'major' revision, but most of the revision that I believe the manuscript could benefit from is simply reducing the amount of content. That is, I don't think there's new work to do, or that the content needs many changes per se. (Though there are a couple of issues in the code that need to be sorted out.)

I have read the other reviews and agree with their comments. I don't think what I have to say is substantially different. In particular, I think we all agree that there is a useful and interesting contribution here.

General remarks

The paper seems long. The length, and difficulty of feeling out the structure of a long paper, probably led to a feeling of confusion about whether I was reading a geological case study, a paper on a new approach to ingesting data, or the documentation for a software package. Perhaps the manuscript is trying to do too much? I wonder if you could split it into pieces? For example, move the more prosaic stuff (lists of tables, etc) to the docs; describe the more technical language modeling piece in a short nerdy paper about that; and present the case study as a short geological success story?

If the authors and editors feel a long paper is justified, then my suggestion is to be extra careful about the outline of the paper, so that a person knows what aspect each chunk of the paper is addressing.

Compounding the length is that there's quite a bit of redundancy between text, figures and captions. Figure 9 is an archetypal example of this. I think the caption (which I cannot parse) essentially spells out the diagram (which I cannot read very well), and virtually all of the data is also written out in sections 3.1 to 3.3. My advice is to frame the ideas with the text and put all the details of table names and data in the figure, which should barely need a caption.

Some pieces seem better suited to the tool's documentation. Appendices B and C probably don't need to be part of a paper. Similarly, I think detailed descriptions of tables are clogging up the text and getting in the way of the reader. Standard measures like precision and recall, or string matching statistics, probably don't need to be described in detail. 

Detailed remarks

• Title: Python should be written with an uppercase P.
• Abstract: I'm not sure you need the first paragraph; it's introductory material. If you want to motivate the problem, I think you can do it in a sentence (the second sentence captures it for me).
• Line 12: surveys, textual (no 'r')
• Line 15: hundreds of
• Line 19: replace 'that provides the functionality to extract...' with 'for extracting...'
• Line 23: 86%
• Line 51: You want spaces after all your semi-colons.
• Section 2: I suggest sticking to sentence case for your subheadings; at least make them all the same.
• Section 2.1, Conventions: The font is called Lucida, not Lucinda. I like the idea of a font convention, but if you're going to use one it is important to be consistent... and being consistent pretty hard. E.g. line 174: collar should be a table name, I think? Line 217: are these tables? Line 225: dh2loop should be italic.
• Lines 166–184: This paragraph is really hard to parse. I think the reader may start wondering if they need to know this information. If the info is important, I think you can let Figure 2 do the work.
• Line 280–295: Similarly, I think you're just describing Figure 4.
• Sections 2.4.1, 2.4.2, 2.4.3: This feels like documentation.
• Lines 419–440: There is a lot of information here; I feel it is perhaps best suited to documentation.
• Table 1: Not sure what to make of this. What do the checks and x's mean? What is the score? Why is one row bold?
• Sections 3.1, 3.2, 3.3: See my earlier remarks about these paragraphs vs Figure 9 and its caption.
• Table 2 and Figure 10: I find these hard to get insight from.
• Confusion matrices: There are a great many data tables here but I am unsure what to do with this information. I see that there are a lot of under-represented labels (low support). The only reference I could find to this problem mentions normalizing the accuracy, but this doesn't really solve the problem, it just makes the confusion matrix colourbar fit better. So you're still unable to balance precision and recall (with small support, one of them is probably going to be bad). I'm not sure what you could do about it, other than get more data, but it might be worth mentioning.

Remarks about code

There are some problems with the licences on some of the code you are using.

QDriller (https://github.com/valheran/QDriller) is licenced under the GPL, which is a copyleft licence. This means that if you use it then your entire project must be licenced under the same (or a compatible) licence. You are not allowed to use GPL'd code under an MIT licence. So you have a few options:

1. If you keep that code as-is, you must licence your entire project under the GPL.
2. Ask the original author to grant you permission to re-use the classes you need under a more permissive licence. (Ideally, it would be, say, LGPL and a completely separate library that you could simply depend on, without copy/pasting the code across.)
3. Rewrite this functionality from scratch.

GeoVectoLitho (https://github.com/IFuentesSR/GeoVectoLitho) is not licenced, as far as I can tell. Normally that would mean that you cannot use it without written permission granting you some rights. So make sure you have written permission to place it under your MIT licence, or you could ask the authors if they will consider an open licence. At the very least, you need to make it clear that the mlp.py module is based on work that is  copyright of those authors and explain the terms under which you're using it. You should probably also exclude it from the MIT licence so that nobody comes along and picks ut up thinking it's FOSS.

In each of these cases, if you cannot find a way to 

The Where to start instructions on the repo need VTK, folium and ipyleaflet adding to the installs. You could just tell people to install everything in requirements.txt with pip install -r requirements.txt. After that the notebooks ran for me (though I didn't run them all right through).

In Notebook 0, the map did not appear; I didn't try to figure it out. Enabling the extension didn't help. (I'm on a Mac, Chrome browser.)

I'm not sure these comments should form part of a peer review. If you don't plan to maintain this library into the future, you can probably just ignore all this. But in case it's useful:

• I strongly recommend writing docstrings for all of your functions.
• You should write tests for your functions. "Untested code is broken code."
• You can remove components of the standard library — sys, math, re, time, itertools, etc — from requirements.txt. These are included in every Python installation.
• I advise against hard-coding the file encoding in your functions (with encoding = "ISO-8859-1") because this seems like something another person is quite likely to want to change, e.g. if they have a UTF-8 encoded file. You should expose it as an argument. The same goes for database connections and other things another user might want to change.
• You should delete unused code, rather than commenting it.
• I'm sure you know about geopandas already, but it seems like it would be useful in your project.
• Note that PyProj emits a warning in Python 3.8+ FutureWarning: '+init=:' syntax is deprecated.
• I don't know if psycopg2 connections or cursors are compatible with Python's context manager (in which case you should 'with' blocks for them), but even if they don't you should put them in try-finally blocks to ensure they get closed no matter what happens in the runtime. 
• I recommend using a linter like flake8 to find things like multiple or redundant imports (e.g. you import numpy three times in dh2l_db.py). It will also help you adhere more closely to the PEP8 standard, which will make your code more readable and reusable.

Overall, the code has a non-Python feel to it (I don't know Fortran, but I've read a lot of code from geophysicists and they often write code like this!). Patterns like functions mutating global variables are not common in Python. Typically, one would pass the variable in to the function, then return them to the user (these are so-called 'pure functions'). You will find this easier to maintain. It feels strange to me to run a function like dh2l.litho_dico(litho_dic_file) and not have something (like a new DataFrame) returned to me.

In summary I think dh2loop is an interesting and useful project that might help others pre-process data for machine learning and other kinds of modeling. I believe a shorter paper will have more impact. And there are some licensing questionmarks that need addressing.

I hope you are able to push this work forward and wish you the best of luck with the tool.