Comments on Paper

[cwitkowitz]

General

• There is room for improvement with respect to the language and phrasing used throughout the paper. For instance, I had to read the second sentence of the paper a few times until I realized that the final part (split by comma) refers to "transient harmonic sounds". Some sentences read a bit clunky, e.g. sentences using "allows" or "allowing".
• Correct me if I'm wrong, but there is nothing inherently specific to guitar in this framework (besides maybe the assumption of strong and quick onsets), right? If so, it would be good to highlight that the framework can be used for any harmonic sounds.
• When referencing python packages, such as guitarsounds, matplotlib, or librosa, I think it would be better to treat these as code snippets, i.e. guitarsounds, matplotlib, or librosa. This will make them pop out in the paper more and will draw attention to the fact that they are packages. On a similar note, I'm not sure if guitarsounds should be capitalized, since the name of the package is not capitalized.
• I think some things in this paper may be confusing to a non-specialist audience, such as some mentioned features (e.g. envelope) or luthier terminology (e.g. soundboard).
• I don’t think the software paper does full justice to the package at this point. There are a lot of distinctions, i.e. signal features, sounds, and sound packs, as well as the corresponding visualizations of each, which are not really highlighted.

Here are some spelling considerations:

• "envelop" -> "envelope"
• "hemlotz" -> "Helmholtz"
• “a” and “an” are frequently mixed up
• “Bruant” or “Bruand” - is this a difference between the English and French title?
• Capitalization of "conditioning"
• "WAVE" vs. "wave" inconsistency
• "More over" -> "Moreover"
• Capitalize "Python"?
• "tailored for" -> "tailored to"

Summary

• I'm not sure if it’s appropriate to claim that guitarsounds implements the FFT. It just provides a wrapper around NumPy.
• Run-on sentence: "The guitarsounds package is divided ...". Add a comma or split.
• Are loading/saving/normalization really main features? They seem relatively trivial.
• I think it is more appropriate to refer to frequency "bands" rather than "bins". In my experience, a frequency bin corresponds to a single frequency, whereas a frequency band corresponds to a group of such adjacent bins.
• Redundant mention of Fourier transform peaks in the main features list.
• It seems a lot of the visualization capabilities are left out of the main features list. This may lead readers to missing the full picture with respect to what is available in the package.
• I don't understand the final item in the main features list.

Example

• The description of the example is quite vague and, at a surface level, does not appear to correspond to the code snippet provided. It could be improved by making the details of the conditioning more explicit and mentioning that this is happening under the hood in guitarsounds.SoundPack.__init__.
• See the relevant comments I made about this type of plot in issues #39 and #40. Also note that this plot, while generated from the same code, is different from what is displayed in README.md. Furthermore, in the paper, the difference between "peaks" and "diff peaks" goes unexplained.
• After the example it would be good to mention that there are other visualization function sets available as well, i.e. with the Sound and Plot classes.
• It may be better to stick with a single example throughout the paper for a more holistic motivation of the package. For instance, in the summary, you exemplify the log-time envelope of a sound. You could described what it is, why it is useful, and visualize that instead with guitarsounds here.

Statement of Need

• Can the previous works (i.e. innovative numerical prototyping method) be cited?
• How is guitarsounds used to modify sounds?
• Awkward wording: "slope of a linear regression".
• Awkward wording: "as such is the case".
• Plural of "phenomenon" is "phenomena".
• Awkward wording: "GUI acts as a different way".

References

• I think the Numpy and SciPy Python packages should probably be cited, since they are heavily utilized in the guitarsounds framework. The paper should also make note of this utilization.

[ebezzam]

To add this very exhaustive list (thanks @cwitkowitz):

• The sentence at Lines 12 - 16 could be broken up so that it's clearer what the two components are, e.g. (1) and (2) just before the components could make it clearer.
• API stands for Application Programming Interface (13-14)
• some wording that I think are missing "-": well-defined (10), object-oriented (13), time-dependent (28), easy-to-use (35)
• Finish each bullet with "." or ";" (until the last with ".").
• Line 42: "two or more sounds."

And to reiterate two of @cwitkowitz comments:

• I think you could broaden the scope and visibility by not renaming the package, as the techniques are not limited to guitar sounds.
• Citing NumPy and Matplotlib

[olivecha]

Thanks for the comments on the paper

I've done the following changes :

• Worked on general phrasing issues.
• Specified the possibility of using the package for any harmonic sound.
• Write package names as code snippets
• Further defined specific terminology
• Highlight how the different features are implemented in the package classes structures
• Added citation for numpy and scipy Python packages
• Some spelling fixes

[olivecha]

So, I've made all the changes suggested to the paper A compiled version is available at paper/paper.pdf Thanks again

[cwitkowitz]

Thank you for addressing all of my comments. In my opinion, the quality of the paper has improved significantly.

Here are a few more minor comments after reading the revisions:

• In the paragraph before the code snippet, break apart the sentence "... equal to 22050 Hz, this is important ..." into two sentences (at the comma)
• At least one instance of guitarsounds remains as text and not a code snippet (just double-check these)
• "manly" -> "mainly"
• "developped" -> "developed" (appears twice)
• "acess" -> "access"
• "two guitar designed" -> "two guitar designs"
• "Hemlotz" -> "Helmholtz"
• "machine learning application" -> "machine learning applications"

If you make these minor adjustments, I would be happy to close the issue (assuming @ebezzam is also satisfied with the revisions).

[olivecha]

I've made the minor adjustments and added an updated version of paper.pdf to the JOSS branch for convenience.

[ebezzam]

I agree the paper has significantly improved.

A few comments / suggestions:

• Line 38, you list 4 classes.
• (Suggestion) Lines 39 - 57 as a list to improve readability. E.g.
  • SoundPack: description...
  • Sound: description...
  • etc...
• Line 77 "guitar" -> "guitars"

Technical comment:

• Line 68-69: why not extend the shortest sound so that the two audio have the same length? I suppose it could be interesting to see how much longer the decay is for a specific instrument?

[olivecha]

@ebezzam Extending the sound could be added as an option in the future. It would be an interesting feature for time based analyses. Shortening was used because padding the array could add noise to the FFT and give the impression that it is more precise than it actually is.

I've made the suggested changes.

[ebezzam]

thanks @olivecha! @cwitkowitz for me it's ok to close