[Re] Periodic forcing of a limit-cycle oscillator: fixed points, Arnold tongues, and the global organization of bifurcations

[kiristern]

Original article:
Glass L, Sun J. Periodic forcing of a limit-cycle oscillator: Fixed points, Arnold tongues, and the global organization of bifurcations. Phys Rev E Stat Phys Plasmas Fluids Relat Interdiscip Topics. 1994 Dec;50(6):5077-5084. doi: 10.1103/physreve.50.5077. PMID: 9962593.

PDF URL:
https://github.com/jkharv/poincare_oscillator/blob/main/Manuscript/Manuscript.pdf

Metadata URL:
https://github.com/jkharv/poincare_oscillator/blob/main/Manuscript/metadata.yaml

Code URL:
https://github.com/jkharv/poincare_oscillator

Scientific domain:
Non-linear dynamics

Programming language:
Julia

Suggested editor:
@ChrisRackauckas (?)

Co-authors
@jkharv, @lucasphilipp1

[rougier]

Thanks for your submission. We'll assign an editor soon.

[rougier]

@pdebuyl Can you edit this submission?

[lucasphilipp1]

Hello Dr. de Buyl and Dr. Rougier.

I was wondering if you could provide some sort of official receipt for our submission. I require it for grant application purposes.

Thank you very much.
Sincerely,
Lucas Philipp

[pdebuyl]

@rougier yes
@lucasphilipp1 ReScience C 's submission is public, wouldn't a link to this page suffice?

[lucasphilipp1]

That's what I have used for now. But if you have a more official looking submission receipt that would be appreciated. No worries if not.

[kiristern]

Hey @lucasphilipp1 , I think including a link to this submission issue would suffice. I’m not sure if ReScience has submission receipt templates, so to minimize @pdebuyl ’s workload, if you require a more official document do you think you could come up with one and send off for them to sign?

[rougier]

Yes, we do not have submission receipt but I'll happily sign any document you may need.

[pdebuyl]

Hello @kiristern , we have two reviewers for your submission: @MA-Ramirez and @Datseris

[pdebuyl]

@MA-Ramirez and @Datseris , the reviewing guidelines are here: https://rescience.github.io/edit/

[MA-Ramirez]

Review: Harvey, Philipp & Stern. [Re] Periodic forcing of a limit-cycle oscillator: Fixed points, Arnold tongues, and the global organization of bifurcations

Review of the replication done by @jkharv, @lucasphilipp1 and @kiristern of the paper Glass, L. & Sun, J. (1994). Periodic forcing of a limit-cycle oscillator: Fixed points, Arnold tongues, and the global organization of bifurcations

The review is based on the commit jkharv/poincare_oscillator @2592e2e.

Overview

Overall, the authors successfully replicate the main results of an important model that describes the periodic stimulation of biological oscillators by providing elegant and illustrative visualisations (I highlight the GIFs in the repository). The article is well-written. The replication code outputs the results stated in the article. However, the code could be better structured and more readable. The authors should improve the clarity of the code before publication.
In addition, the authors should address some questions about the replication for it to be a complete replication of the original paper.

Replication of the research

The authors successfully replicated the main results of the paper Glass, L. & Sun, J. (1994). In particular, they reproduced numerically the geometry of the phase-locking regions for varying stimulus intensities ($b$), time interval between stimulations ($\tau$), and rate of return to the limit cycle ($k$) - Figs. 2 and 5 of the original paper. Additionally, they calculated analytically the period-1 instability boundary for the infinite relaxation limit ($k \rightarrow \infty$) - Section V. C. of the original paper.

Given that in the original paper, the numerical studies focus on analysing the phase-locking zones for finite relaxation rate values ($k$). I want to highlight that the replication code is able to generate the phase-locking zones for any given relaxation rate value ($k$). These results are nicely shown through GIFs available in the repository.
As this is one of the most valuable achievements of the replication, I recommend referring to it in the accompanying article.

Moreover, figures 2.b and e are good additions that provide a more complete information about the behaviour of the zones around the $b=1$ boundary.

Major Comments and Questions:

1. In Section VI of the original paper, the authors explain that one of the numerical difficulties in the computations is the effect of initial conditions. I would be curious to know if these difficulties are also encountered in the replication.

2. Figures 2 and 5 of the original paper explore the interval $b \in [0, 2.5]$. On the other hand, the replication analyses the interval $b \in [0, 2]$, as shown in Figs. 2.a, b and c and in the GIFs of the repository. I would like to know why the same interval of the original paper was not explored.

3. Given that the main results were successfully replicated, I was wondering why Fig. 6 and Fig. 8 of the original paper were not replicated. In particular, Fig. 6 seems to be a figure that could be readily obtainable from the results already replicated.

Minor Comments:

4. In Section V. C. of the original paper, the authors state that for $0 < b < 1$ the stability is lost by a tangent bifurcation. In the replication, it was concluded that for $b < 1$ the type of bifurcation for the period-1 instability boundary is a tangent bifurcation. In the case for $1 < b < 2$, the stability is lost by a period-doubling bifurcation. However, in the replication, there is no comment about the type of bifurcation arising for this parameter range. For completeness of the replication, I suggest commenting about the bifurcation appearing in this range.

Reproducibility

The proposed implementation for the replication is easy to run and outputs the same results as the ones stated in the article.
The results are easy to reproduce, given that the instructions in the README file are clear.
It is helpful that the authors warned about the time it takes for the script to run. (When I ran the script, just as it is stated in the repository, it took around x3 longer to run. In particular, the second GIF takes a long time to run.)

Major Comments:

1. It is recommended for a Manifest.toml file to be included in scientific projects, in order to avoid ambiguity in the versions of the packages that were used. For example, it states the Julia version that was used.
   To this end, it is helpful to use DrWatson. This Julia package helps manage scientific projects. In particular, it sets a scientific project also as a Julia project environment. (To use this package is, of course, optional.)

2. Figures 2.d and e are generated in the code by setting $k=500$. I would have expected for $k=50$, given that $k=50$ was used to analyse the infinite relaxation limit in the previous figures and in the article.

Minor Comments:

3. The scripts do not generate Fig. 2a., as they directly generate Fig. 4. It would be helpful if the code also generates Fig. 2a separately.

Clarity of the code

In general, the code is functional and successfully replicates the original paper's results. However, the code needs more clarity. The organization and clarity of the code should be improved.

Major Comments:

1. Project organisation: the project needs to be organised more clearly.
   The project should have an intuitive folder structure. Ideally, the src folder should contain only scripts that define functions, structures, and modules that are used throughout the project. The scripts folder should contain the scripts that will actually be run, which means that they use the src folder for their base code (e.g. running simulations, plotting, ...)

2. Documentation: the code is not so easy to follow. Even though some functions are documented with an initial comment, the convention in Julia projects is to use docstrings. They provide a more detailed description of each function.

   2.2 To improve clarity, starting each script with a description of what the file contains or intends to do is recommended.

Minor Comments:

3. The naming of the outputs should be more straightforward. For example, instead of naming the figure zoom_zoom_plot.png, it could be called Figure_2e.png, such that there is consistency with the accompanying article.

4. Code duplication: to avoid this issue, the code of periodicity_plots.jl could be structured around functions.

5. It is unclear why the function make_frame_lyapunov in oscillator_simulation.jl has been added to the replication code. It seems like it is only defined but not used later on.

Clarity and completeness of the accompanying article

The article is well-written. It clearly describes the mathematical model of the original paper and how the main results were replicated.
Particularly, I would like to highlight the clarity of the introduction.

Additionally, in terms of the replication, I highlight that the authors explained the nature and the reason for the coordinate transformation performed for the numerical calculations.

Major Comments:

1. The last paragraphs of Section 3 state: "we numerically simulate the period-1 instability boundary and overlay it with the phase-locking zones" and "Figure 4 compares the analytically calculated period-1 instability boundaries with numerical simulations results from Section 2." It is unclear how the black line, representing the period-1 instability boundaries, in Fig. 4 is calculated.

2. I recommend rewriting the last paragraph of Section 2: "Figure 2 shows ...". The paragraph could be more precise and detailed regarding the considerations taken for $\tau$.

Minor Comments:

3. The article's abstract states: "Here we successfully replicate a mathematical model ...".
   I would say that the model's behavior is replicated, not the model itself.

4. In Section 2 of the article, the authors state that Julia (version 1.7.2) was used. However, the README states that the version 1.8.0 has been used. This ambiguity could also be avoided via the Manifest.toml file.

5. The descriptions of Fig. 2.d and 2.e seem to be inverted.

Others

The colormap chosen to plot the phase-locking zones contains little contrast. I suggest using colorblind-friendly palettes like viridis, inferno, magma, or plasma.

[Datseris]

Hello @pdebuyl , apologies, but I will not have the time to review this in time in the end. I am totally overwhelmed with very important deadlines, so I have to retract myself from here. I just saw that the review above is incredibly thorough, so perhaps this one review will suffice? If not, I wish you best of luck in finding another reviewer. If you use the Julia Slack, you can post on the #dynamics-bridge channel for a request to review.

Apologies once again.

[kiristern]

Thank you very much for your thorough review @MA-Ramirez ! Our team will go over your comments sometime next week.

We completely understand how busy things can get, so no worries @Datseris, thanks for letting us know.

We'll start by implementing the suggestions from the first review, between finding a second reviewer.

[pdebuyl]

Hi all, thanks @MA-Ramirez for the review! @Datseris thanks for considering the review in the first place, I'll look for someone else. @kiristern you may suggest a reviewer if you think of someone fitting (and not having published with any of the authors in the past 5 years and not having been mentor/mentee, etc).

[rougier]

Any update ?

[jkharv]

Hi! Sorry for the late reply. I got most of the way through addressing comments from the first review when I got sidetracked by other work. I'm planning on wrapping that up in February.