First draft for JOSS paper #70

JanJereczek · 2024-02-13T17:47:01Z

This PR proposes a first draft for the JOSS paper describing the package. The JOSS guideline states that the paper should be between 250-1000 words. Authors submitting papers significantly longer than 1000 words may be asked to reduce the length of their paper. We are at about 1,500 words, which might not be a big issue but needs to be discussed.

The code used to generate the two figures of the paper are provided in paper/code/ and the figures in paper/figures. The first figure requires a .csv file, which is not included in the PR since we should include it in the genral repo of JuliaDynamics. The second figure is a comparison to the run time of ewstools, as assessed in paper/code/ewstools-tuto-1.py.

@Datseris, I suggest we have a call to talk about the draft :) Also, at some point you will need to put your affiliation and your funding.

codecov-commenter · 2024-02-13T17:56:02Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (b1d3387) 36.42% compared to head (32ad0fe) 81.36%.
Report is 2 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main      #70       +/-   ##
===========================================
+ Coverage   36.42%   81.36%   +44.94%     
===========================================
  Files          18       16        -2     
  Lines         442      365       -77     
===========================================
+ Hits          161      297      +136     
+ Misses        281       68      -213

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Datseris

Thanks for your work! First round of review is done. Overall good but can still be improved!

.github/workflows/draft-pdf.yml

paper/code/Project.toml

paper/figures/figure2.png

paper/paper.md

Co-authored-by: George Datseris <[email protected]>

Datseris

We are almost there. address these and we can merge this!!!

Datseris · 2024-02-17T13:34:51Z

paper/paper.md

+and the recent price collapse of many cryptocurrencies [@ismail_detecting_2020]. The systems
+displaying such transitions are therefore usually monitored by measuring state variables
+that are believed to be representative of the underlying process. Researchers analyze the
+resulting time series with various methods to detect past transitions and predict


Suggested change

resulting time series with various methods to detect past transitions and predict

resulting timeseries with various methods to detect past transitions and predict

I've taken it my personal crusade to replace the words "time series" with "timeseries" in the NLD literature.

Datseris · 2024-02-17T13:35:07Z

paper/paper.md

+and society. Examples of this are ubiquitous and include the onset of cardiac arrhythmia
+[@tse_mechanisms_2016], the deglaciation of Earth about 20,000 years ago [@wolff_changes_2010]
+and the recent price collapse of many cryptocurrencies [@ismail_detecting_2020]. The systems
+displaying such transitions are therefore usually monitored by measuring state variables


Suggested change

displaying such transitions are therefore usually monitored by measuring state variables

displaying such transitions are usually monitored by measuring state variables

Datseris · 2024-02-17T13:37:45Z

paper/paper.md

+work predicting a collapse of the Atlantic Meridional Overturning Circulation between 2025
+and 2095 has led to no less than 870 news outlets and 4100 tweets [@ditlevsen_warning_2023],
+largely because of the substantial implications of such a collapse for human societies.
+However, some published work is not reproducible despite their strong policy implications.


Sure, but the problem is that we are making a definitive statement: "some published work is not reproducible despite ..." . How do we substantiate this in the scientific sense?

We can argue instead: "A common concern in the scientific community is that published work on the topic is difficult to reproduce, despite the impact it implies for humanity." which doesn't assert a definitive statement, but would still be acceptable by pretty much everyone.

Datseris · 2024-02-17T13:38:37Z

paper/paper.md

+largely because of the substantial implications of such a collapse for human societies.
+However, some published work is not reproducible despite their strong policy implications.
+This can be largely addressed by a unifying software that is accessible, performant,
+reproducible, reliable and extensible, and we therefore propose TransitionsInTimeseries.jl.


Suggested change

reproducible, reliable and extensible, and we therefore propose TransitionsInTimeseries.jl.

reproducible, reliable and extensible. Such a software does not exist yet, but here

we propose TransitionsInTimeseries.jl to fill this gap.

Datseris · 2024-02-17T13:38:51Z

paper/paper.md

+This can be largely addressed by a unifying software that is accessible, performant,
+reproducible, reliable and extensible, and we therefore propose TransitionsInTimeseries.jl.
+We believe this is a major step towards establishing a software as standard, widely used
+by academics working on transitions in time series.


Suggested change

by academics working on transitions in time series.

by academics working on transitions in timeseries.

Datseris · 2024-02-17T13:41:44Z

paper/paper.md

+
+## Reliability
+
+In high-impact context mentioned above, errors are to be avoided with particular care.


Suggested change

In high-impact context mentioned above, errors are to be avoided with particular care.

In high-impact context mentioned in the introduction, it is crucial to avoid errors.

Datseris · 2024-02-17T13:44:44Z

paper/paper.md

+with the structure of taking a vector as input and returning a scalar as output. Finally,
+users can modify the fully-open source code, written in native Julia and thus offering a good
+legibility compared to other high-performance languages.


Suggested change

with the structure of taking a vector as input and returning a scalar as output. Finally,

users can modify the fully-open source code, written in native Julia and thus offering a good

legibility compared to other high-performance languages.

with the structure of taking a vector as input and returning a scalar as output.

I don't think that's important to mention, it is obvious and not of high impact. We can save some words here.

Datseris · 2024-02-17T13:46:42Z

paper/paper.md

+relevant metrics. Finally, different ways of testing for significance can be interchangeably
+used, therefore expanding the versatility of the software beyond the surrogate analysis.
+
+## Extensibility


I am still unhappy about this section. Even though it is extensive, the most extensive subsection, it still does not discuss the biggest novelty of our software: that entirely new pipelines for estimating changes, or estimating their significance, can be added to the software.

You can save lots of space here by using only two sentences to mention that idicators and change metrics are arbitrary julia functions, which means that they could be defined by the user or imported form any other package.

This extra space can be used to highlight the novelty of new pipelines, like what I contributed in #73 .

Datseris · 2024-02-17T13:48:34Z

paper/paper.md

+## Integration
+
+TransitionsInTimeseries.jl is designed to be well integrated into the Julia ecosystem.
+Functions can be imported from other packages and subsequently passed as indicators or
+change metrics. For instance, the skewness implemented above can be loaded from another julia
+package instead of being programmed by the user:
+
+```julia
+using StatsBase
+indicators = (var, ar1_whitenoise, StatsBase.skewness)
+```
+
+TransitionsInTimeseries.jl therefore offers an extremely wide and
+potentially unlimited library of indicators. Furthermore, TimeseriesSurrogates.jl
+[@haaga_timeseriessurrogatesjl_2022] is used to create surrogates of the time series,
+thus offering optimized routines with numerous surrogate types. Finally,
+`plot_changes_significance` showcased in [Fig. 1](@figure1) relies on Makie.jl, which allows
+the user to customize the figures according to their needs.


I think all of this section is too large and should be significantly decreased in size. Above comment says how to mention impoting functions from other packages. And we definitely do not need a code example for using functions from other packages.

Makie.jl is not an integration. Iti s a dependency. Its not like the user can interface with the plotting code in any meaningful way.

You can mention the surrogate integration though.

p.s.: We can add the skewness example to the main tutorial to show defining user defined functions or importing new ones.

paper/paper.md

JanJereczek · 2024-02-19T15:20:19Z

Hi @Datseris, thanks a lot for your corrections :) I applied all of them (except for one I that answered to, see above). In particular, I reformulated the versatility section and moved it for a better flow of explanations. I hope you'll like it!

JanJereczek added 3 commits February 13, 2024 18:35

draft of paper v0.1

9e31294

figures of paper and code for it

d91fd08

correct path for paper.pdf

470cb25

JanJereczek added 2 commits February 14, 2024 11:00

minor modifications (mostly figures)

29482d9

change ylabel of fig 2

e83f75d

Datseris reviewed Feb 15, 2024

View reviewed changes

JanJereczek and others added 6 commits February 15, 2024 14:50

affiliation George

ebedc8d

Co-authored-by: George Datseris <[email protected]>

most changes from 1st review of George

84e0bdb

funding George

8e78d09

Co-authored-by: George Datseris <[email protected]>

draft of paper v0.2

b676bbb

add ref to timeseriessurro

cc1daf7

add TransitionsInTimeseries.jl

6246ad7

Datseris reviewed Feb 17, 2024

View reviewed changes

JanJereczek added 4 commits February 19, 2024 10:52

replace "time series" by "timeseries"

27674dd

shorten and correct minors

e91f9d1

reformulation of versatility section

b2813c6

typo

32ad0fe

Datseris approved these changes Feb 19, 2024

View reviewed changes

Datseris merged commit abde970 into main Feb 19, 2024
3 checks passed

Datseris deleted the joss-paper-viz branch February 19, 2024 19:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

First draft for JOSS paper #70

First draft for JOSS paper #70

JanJereczek commented Feb 13, 2024 •

edited

Loading

codecov-commenter commented Feb 13, 2024 •

edited

Loading

Datseris left a comment

Datseris left a comment

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

Datseris Feb 17, 2024

JanJereczek commented Feb 19, 2024

	resulting time series with various methods to detect past transitions and predict
	resulting timeseries with various methods to detect past transitions and predict

	displaying such transitions are therefore usually monitored by measuring state variables
	displaying such transitions are usually monitored by measuring state variables

	reproducible, reliable and extensible, and we therefore propose TransitionsInTimeseries.jl.
	reproducible, reliable and extensible. Such a software does not exist yet, but here
	we propose TransitionsInTimeseries.jl to fill this gap.

	by academics working on transitions in time series.
	by academics working on transitions in timeseries.


		## Reliability

		In high-impact context mentioned above, errors are to be avoided with particular care.

	In high-impact context mentioned above, errors are to be avoided with particular care.
	In high-impact context mentioned in the introduction, it is crucial to avoid errors.

First draft for JOSS paper #70

First draft for JOSS paper #70

Conversation

JanJereczek commented Feb 13, 2024 • edited Loading

codecov-commenter commented Feb 13, 2024 • edited Loading

Codecov Report

Datseris left a comment

Choose a reason for hiding this comment

Datseris left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JanJereczek commented Feb 19, 2024

JanJereczek commented Feb 13, 2024 •

edited

Loading

codecov-commenter commented Feb 13, 2024 •

edited

Loading