Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @ali-ramadhan, @ashwinvis it looks like you're currently assigned to review this paper 🎉.

⭐️ Important ⭐️

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

Attempting PDF compilation. Reticulating splines etc...

👉 Check article proof 📄 👈

👋@ali-ramadhan @ashwinvis Thank you again for volunteering to review. The review instructions are listed above. Please let me know if you have any questions!

I like the idea of having a simple and intuitive open-source Python package offering numerous DFA algorithms and the examples look great, but I think fathon needs some work to make it more accessible to potential users.

My major comments are:

1. fathon is difficult to install. I was actually not able to install it. It could greatly benefit from an automated package management solution.
2. Currently documentation is provided via a single pdf file. I think generating documentation using a package like Sphinx would provide potential users with searchable documentation that gets updated alongside the code and integrates in the great docstrings that are already in the source code.
3. Right now the burden is on the user to run manual tests to verify that fathon works, but I think this approach cannot scale as improvements are made and other people decide to contribute. I think an automated testing solution would greatly improve the situation here.

Maybe @mbobra can confirm whether these three points are necessary for publication in JOSS. I do think they would improve fathon and make the package much more accessible to potential users.

A more detailed review follows below.

I plan to come back and finish this review once I can install fathon.

Functionality

Installation

• Option 1 (git clone stfbnc/fathon.git) does not work. It should be git clone https://github.com/stfbnc/fathon.git.
• The second option is to "Go to the repository and download the code" however I couldn't figure out where to download the code. Usually on GitHub tagged releases are downloadable as zip files or tarballs, but fathon has no tagged releases. Unless the README is referring to the green "Clone or download" button which would be good to mention.

I wonder if providing a Python package installable via pip or conda would make fathon more accessible and easier to install. I'm not super familiar with either but because of the C libraries, presumably conda is the better option?

GSL seems to be a pre-requisite which is available through most Linux package managers. Installing fathon on Windows might prove difficult and it looks like you might need to install all of Cygwin just to get GSL to install fathon. I might mention this as most Windows users have no idea what Cygwin is.

I was not able to install fathon myself. I opened an issue about this: stfbnc/fathon#1

I believe the installation instructions are unfriendly. fathon seems much harder to install for me than the vast majority of Python packages, many of them which depend on C libraries too.

Besides having to manually install or compile GSL, you also need to know where include and library files are placed on your operating system, and you need to know the "standard location of Python packages" for your particular OS and Python environment combination.

I think this is a huge barrier to usability and most Python users won't be able to install fathon.

I opened an issue to ask whether providing a pip or conda package is an option: stfbnc/fathon#2

Functionality

I was not able to install fathon but when I do I will try to confirm this.

I'm not sure if whether four tests on Gaussian white noise are sufficient to claim that fathon fully works. That seems to be the easiest test case. I would like to explore testing other cases.

Performance

No performance claims I could find except for "It is mostly written in Cython and C in order to speed up computations" which seems reasonable.

Documentation

A statement of need

Some motivation is provided in the JOSS paper and documentation.

Installation instructions

There is a clearly-stated list of depdencies (GSL) although Cython might be missing (see stfbnc/fathon#1). I strongly believe that fathon will benefit from having installation handled via an automated package managemnent solution such as pip or conda (see stfbnc/fathon#2).

Examples

The examples directory contains some nice-looking examples that I'm looking forward to running and playing around with. There are also some illustrative examples in the fathon_docs.pdf.

Functionality documentation

I could not find any documentation for the API. I also think having the documentation in PDF form is detrimental to being simple and user friendly as it becomes difficult to link to them and it seems that nobody can contribute to improving the docs as the LaTeX document is not part of the repository.

I believe with documentation packages like Sphinx, documenting the API becomes easy, and it's trivial to deploy the docs to a website like ReadTheDocs.

Looking through the code, there are really good docstrings so it's a shame that they're currently hidden from the user!

Automated tests

There are no automated tests, and no continuous integration.

There is a Jupyter notebook and four Python scripts provided where the burden is on the user to run the tests.

I think it would be easy to convert the four scripts to automated tests that run on a CI platform like Travis CI. I haven't set up Travis with Python but it was painless with other languages, so I assume it should be easy to set up.

Community guidelines

I could not find any community guidelines or a contributor's guide. There should be "clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support". This can all be included in the README I believe.

I find it kind of weird that the README states "For bugs or improvements, write to fathon.package@gmail.com" when the package is on GitHub. I think the README should strongly encourage the submission of GitHub issues so that bugs and improvements can be visible to all users and the discussion can be more transparent. This also allows other people to contribute as it's not dependent on one person checking an email inbox and having the time to reply. Keeping track of issues on GitHub also leaves behind a rich history of package development that allows other contributors to take over if the original package developer no longer has the time to develop the package.

Software paper

Summary

I think the first paragraph is not accessible to a "diverse, non-specialist audience". DFA itself isn't actually described. Terms such as "fluctuation function", "Hurst exponent", and "anti-persistent" would not be understood by non-specialists I think.

I also think the mass citation of ~10 different works without context on the second sentence is not helpful to readers, especially non-specialists. I would suggest picking 2-4 works and placing them in context so that a non-specialist reader can understand how DFA was used in that particular work and why it was useful.

Statements such as "found various applications in other fields, like geophysics or economy" seem vague and not very helpful. It can be argued that the entire field of mathematics and statistics has found found various applications in other fields, like geophysics or economy.

The rest of the paper looks good to me.

State of the field

A quick Google search yielded three results for open-source Python packages that provide DFA algorithms:

• https://github.com/dokato/dfa
• https://pypi.org/project/nolds/
• https://raphaelvallat.com/entropy/build/html/generated/entropy.detrended_fluctuation.html

It doesn't have to enter the README or JOSS paper but I'm curious how fathon is different. Do the others not provide the four algorithms provided by fathon? Are these packages worth mentioning?

A MATLAB package is mentioned in the JOSS paper which I assume is more comprehensive than these Python packages?

Quality of writing

In the first paragraph, I think you mean "economics" instead of "economy".

Otherwise I think it's fine.

References

These seem fine to me, but as mentioned above I think there may be too many.

I think "co_2" and "mauna loa" should be captialized to "CO_2" and "Mauna Loa" for the Varotsos et al. (2007) reference.

Also missing some captialization in the Janosi et al. (1999) reference. Should be "Also I think Statistical analysis of 5 s index data of the Budapest Stock Exchange".

"matlab" should be "Matlab" in the Ihlen (2012) reference.

👋 @ashwinvis Let me know if you have any questions or need any help completing your review!

@mbobra Working on it :)

My major comments are:

1. fathon is difficult to install. I was actually not able to install it. It could greatly benefit from an automated package management solution.

2. Currently documentation is provided via a single pdf file. I think generating documentation using a package like Sphinx would provide potential users with searchable documentation that gets updated alongside the code and integrates in the great docstrings that are already in the source code.

3. Right now the burden is on the user to run manual tests to verify that fathon works, but I think this approach cannot scale as improvements are made and other people decide to contribute. I think an automated testing solution would greatly improve the situation here.

Maybe @mbobra can confirm whether these three points are necessary for publication in JOSS. I do think they would improve fathon and make the package much more accessible to potential users.

Thanks for your detailed review, @ali-ramadhan. Here are my replies:

1. According to the JOSS review guidelines, instructions for installing the software should be clear. An automated package management solution is ideal, but not required. However, the authors must provide clear installation instructions that work as well as a clear list of dependencies.

2. According to the JOSS review guidelines, the documentation must to include four items: a statement of need, installation instructions, example usage, and API documentation. The first three are pretty clear; the fourth is a bit subjective (and up to the reviewer to decide), but the core API must be documented in a reasonable way.

3. According to JOSS' review guidelines, the reviewer must be able to check to see if the software actually works. An automated test suite is ideal, but documented manual steps are okay too. But there must be some way for the reviewer to objectively assess whether the software works.

Does this help, @ali-ramadhan?

Thank you @mbobra, that's helpful! Sorry it's my first review but I should have familiarized myself with the review guidelines more closely.

1. According to the JOSS review guidelines, instructions for installing the software should be clear. An automated package management solution is ideal, but not required. However, the authors must provide clear installation instructions that work as well as a clear list of dependencies.

I would be happy with clear installation instructions that can be followed by people without having to spend too much time figuring out where GSL include/library files are located and where Python packages are usually installed.

2. According to the JOSS review guidelines, the documentation must to include four items: a statement of need, installation instructions, example usage, and API documentation. The first three are pretty clear; the fourth is a bit subjective (and up to the reviewer to decide), but the core API must be documented in a reasonable way.

I think fathon satisfies the first three and does technically satisfy the fourth as functions in the source code are documented with good docstrings. I feel like it doesn't count as API documentation though unless the docstrings are compiled into documentation, but maybe having docstrings in the source code meets the JOSS requirements.

3. According to JOSS' review guidelines, the reviewer must be able to check to see if the software actually works. An automated test suite is ideal, but documented manual steps are okay too. But there must be some way for the reviewer to objectively assess whether the software works.

The manual steps in the README sound good then.

@ali-ramadhan Sounds good!
Re: The 1st point - Thanks for opening an issue about the installation instructions.
Re: The 2nd point - Feel free to open an issue about the core API documentation.
Re: The 3rd point - It seems like this is no longer an issue.

@stfbnc Let me know if you have any questions or need any help resolving these issues.

@ali-ramadhan Thanks for the comments, I'm now working on resolving the issues and on the documentation.

@mbobra Can I modify the paper as ali-ramadhan suggested, or should I wait for the second reviewer's comments?

@stfbnc Yes, feel free to modify the paper right away! Every time you modify, you can make a comment in this thread with the command @whedon generate pdf to ask the JOSS bot Whedon to compile a PDF (so that we can all see the latest draft). This is an iterative process, so there is absolutely no issue with modifying and re-generating the paper as many times as you like.

@whedon generate pdf

Attempting PDF compilation. Reticulating splines etc...

👉 Check article proof 📄 👈

@whedon generate pdf

Attempting PDF compilation. Reticulating splines etc...

👉 Check article proof 📄 👈

@ali-ramadhan I have corrected the paper as you suggested, there is now a theoretical introduction on the algorithms covered by fathon.

For the State of the field section:

• the three packages you mentioned only cover the DFA algorithm (and with not all the options provided by fathon), while they do not cover MFDFA, DCCA, and HT.
• the Matlab package is instead more comprehensive, and (besides not being written in Python) does not cover all the features offered by fathon. It does not cover DCCA, is less flexible, and some function's parameters are not considered, like the possibility to calculate the fluctuation function only forward or both forward and backward.

👋 @ashwinvis I'm trying to move this along for the authors. Let me know if you want any help in completing your review! I'm genuinely happy to help.

@ali-ramadhan @ashwinvis Sorry for the late reply. I have updated the repository. Requirements are now specified, along with the new installation guidelines. I have also added:

• automated tests on Travis CI
• readthedocs documentation
• contributing guidelines

Code coverage is by now 0%, but only because the package is written in cython and not python. I'm still trying to figure out how to make codecov consider also .pyx or .so files.

@mbobra Thanks for the nudge. I was coordinating with the author to improve the installation and packaging situation stfbnc/fathon#1 (comment) so that we have a version that can be reviewed.

@stfbnc Code coverage is not necessary for the paper, but if you are willing to go that extra mile, it can be fixed by following this document. You need to enable CYTHON_TRACE=1 and Cython.Coverage plugin when you run tests / CI. Do not enable linetrace by default, as it can degrade performance.

@stfbnc Let me know your timeline/plans for this paper. You should feel absolutely free to take as much time as you need, so there's no rush or anything. I only want to know the timeline because if it is long (>1 month or so) we can add a "paused" label to this review to indicate to the Editors in Chief that they don't need to watch over this thread in the interim.

/ooo December 16 until January 6

Reference check summary:

OK DOIs

- None

MISSING DOIs

- https://doi.org/10.1016/j.physa.2010.10.022 may be missing for title: DCCA cross-correlation coefficient: quantifying level of cross-correlation.
- https://doi.org/10.1103/physrevlett.100.084102 may be missing for title: Detrended cross-correlation analysis: a new method for analyzing two nonstationary time series.
- https://doi.org/10.3389/fphys.2012.00141 may be missing for title: Introduction to multifractal detrended fluctuation analysis in Matlab.
- https://doi.org/10.1103/physreve.60.1390 may be missing for title: Statistical properties of the volatility of price fluctuations.
- https://doi.org/10.1103/physrevlett.90.108501 may be missing for title: Scaling of atmosphere and ocean temperature correlations in observations and climate models.
- https://doi.org/10.1103/physreve.47.3730 may be missing for title: Finite-size effects on long-range correlations: Implications for analyzing DNA sequences

INVALID DOIs

- None

@whedon generate pdf

👉 Check article proof 📄 👈

@whedon check references

Reference check summary:

OK DOIs

- http://dx.doi.org/10.1016/j.physa.2010.10.022 is OK
- http://dx.doi.org/10.1103/PhysRevLett.100.084102 is OK
- http://dx.doi.org/10.3389/fphys.2012.00141 is OK
- http://dx.doi.org/10.1016/S0378-4371(02)01383-3 is OK
- http://dx.doi.org/10.1103/PhysRevE.69.056107 is OK
- http://dx.doi.org/10.1103/PhysRevE.60.1390 is OK
- http://dx.doi.org/10.1103/PhysRevLett.90.108501 is OK
- https://doi.org/10.5194/acp-7-629-2007 is OK
- http://dx.doi.org/10.1103/PhysRevE.47.3730 is OK

MISSING DOIs

- None

INVALID DOIs

- None

@mbobra DOIs added!

@whedon set 10.5281/zenodo.3601637 as archive

OK. 10.5281/zenodo.3601637 is the archive.

@whedon set v0.1.2 as version

OK. v0.1.2 is the version.

@openjournals/joss-eics This paper is accepted and ready for final processing! Nice work, @stfbnc 🎉

Thanks @mbobra - just as a minor correction, let's call it "ready-to-accept" until the final processing is done :)

@whedon accept

Attempting dry run of processing paper acceptance...

Reference check summary:

OK DOIs

- http://dx.doi.org/10.1016/j.physa.2010.10.022 is OK
- http://dx.doi.org/10.1103/PhysRevLett.100.084102 is OK
- http://dx.doi.org/10.3389/fphys.2012.00141 is OK
- http://dx.doi.org/10.1016/S0378-4371(02)01383-3 is OK
- http://dx.doi.org/10.1103/PhysRevE.69.056107 is OK
- http://dx.doi.org/10.1103/PhysRevE.60.1390 is OK
- http://dx.doi.org/10.1103/PhysRevLett.90.108501 is OK
- https://doi.org/10.5194/acp-7-629-2007 is OK
- http://dx.doi.org/10.1103/PhysRevE.47.3730 is OK

MISSING DOIs

- None

INVALID DOIs

- None

Check final proof 👉 openjournals/joss-papers#1209

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1209, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

👋 @stfbnc - please merge stfbnc/fathon#6 or let me know what parts you disagree with

@danielskatz Thanks for the corrections, I've merged your pull request.

@whedon accept

Attempting dry run of processing paper acceptance...

Reference check summary:

OK DOIs

- http://dx.doi.org/10.1016/j.physa.2010.10.022 is OK
- http://dx.doi.org/10.1103/PhysRevLett.100.084102 is OK
- http://dx.doi.org/10.3389/fphys.2012.00141 is OK
- http://dx.doi.org/10.1016/S0378-4371(02)01383-3 is OK
- http://dx.doi.org/10.1103/PhysRevE.69.056107 is OK
- http://dx.doi.org/10.1103/PhysRevE.60.1390 is OK
- http://dx.doi.org/10.1103/PhysRevLett.90.108501 is OK
- https://doi.org/10.5194/acp-7-629-2007 is OK
- http://dx.doi.org/10.1103/PhysRevE.47.3730 is OK

MISSING DOIs

- None

INVALID DOIs

- None

Check final proof 👉 openjournals/joss-papers#1210

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1210, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

@whedon accept deposit=true

Doing it live! Attempting automated processing of paper acceptance...

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 openjournals/joss-papers#1211
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.01828
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

Thanks to @ali-ramadhan & @ashwinvis for reviewing, and @mbobra for editing!
And congratulations to @stfbnc!!

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.01828/status.svg)](https://doi.org/10.21105/joss.01828)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.01828">
  <img src="https://joss.theoj.org/papers/10.21105/joss.01828/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.01828/status.svg
   :target: https://doi.org/10.21105/joss.01828

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss