[REVIEW]: pyhctsa: A Python package for highly comparative time-series analysis

[editorialbot]

Submitting author: @joshuabmoore (Joshua Moore)
Repository: https://github.com/DynamicsAndNeuralSystems/pyhctsa
Branch with paper.md (empty if default branch):
Version: v1.0.0
Editor: @boisgera
Reviewers: @robertmartin8, @mahajanhrishikesh
Archive: 10.5281/zenodo.20820138

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/98f474a523552a41749fe82e2ec04173"><img src="https://joss.theoj.org/papers/98f474a523552a41749fe82e2ec04173/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/98f474a523552a41749fe82e2ec04173/status.svg)](https://joss.theoj.org/papers/98f474a523552a41749fe82e2ec04173)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@robertmartin8 & @mahajanhrishikesh, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review.
First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @boisgera know.

✨ Please start on your review when you are able; the expectation is that it will take 2-4 weeks to complete. ✨

Checklists

📝 Checklist for @mahajanhrishikesh

📝 Checklist for @robertmartin8

[editorialbot]

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

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

@editorialbot commands

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

@editorialbot generate pdf

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.1016/j.cels.2017.10.001 is OK
- 10.1038/s43588-023-00519-x is OK
- 10.1098/rsif.2013.0048 is OK
- 10.6084/m9.figshare.5436136.v10 is OK
- 10.1016/j.softx.2020.100456 is OK
- 10.1016/j.sleep.2022.06.013 is OK
- 10.1093/mnras/stac1515 is OK
- 10.1016/j.neucom.2018.03.067 is OK
- 10.1111/1365-2478.13386 is OK
- 10.1016/j.addma.2023.103810 is OK
- 10.1371/journal.pcbi.1008820 is OK
- 10.1093/braincomms/fcad330 is OK
- 10.5281/zenodo.18529935 is OK
- 10.32614/RJ-2025-023 is OK
- 10.7554/eLife.86695 is OK
- 10.1098/rsif.2023.0399 is OK
- 10.3390/s20174818 is OK
- 10.1109/ACCESS.2021.3099459 is OK
- 10.1109/ACCESS.2021.3056441 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: Kats

❌ MISSING DOIs

- 10.32614/cran.package.theft may be a valid DOI for title: theft: Tools for Handling Extraction of Features f...
- 10.32614/cran.package.feasts may be a valid DOI for title: feasts: Feature Extraction and Statistics for Time...
- 10.1038/s42003-024-05819-0 may be a valid DOI for title: Macroscale intrinsic dynamics are associated with ...

❌ INVALID DOIs

- https://doi.org/10.1016/j.addma.2023.103810 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1016/j.accpm.2021.101015 is INVALID because of 'https://doi.org/' prefix

[mahajanhrishikesh]

Review checklist for @mahajanhrishikesh

AI usage

• I confirm that I have read the JOSS AI policy and understand that:
  • AI may only be used for non-substantive assistance (e.g., grammar checking my review text, contextualizing public materials)
  • All evaluative decisions—including scoring, accept/reject recommendations, and assessments of originality, correctness, significance, and ethics compliance—must be made exclusively by me, not AI
  • I bear full responsibility for all judgments, recommendations, and technical claims in my review
  • I will disclose any AI assistance at the conclusion of my review

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the https://github.com/DynamicsAndNeuralSystems/pyhctsa?
• License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@joshuabmoore) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Scope and significance: Does this submission demonstrate clear research impact or credible scholarly significance as described in the JOSS guidelines?
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Development history and open-source practice

• Development timeline: Does the project show evidence of sustained development over time (preferably months or years) rather than rapid, recent code generation?
• Open development: Was the software developed openly from early stages? For projects with recent public repositories, is there at least six months of public development history with evidence of releases, public issues/pull requests, and ideally external engagement?
• Collaborative effort: Does the project show evidence of community engagement — such as contributions from multiple developers, issues/discussions from external users, or community influence on development — in the repo or as described in the paper?
• Good practices: Does the project look like a reusable, non-throwaway research software project that follows good open-source practices (license, documentation, tests and/or verification processes, releases, and clear contribution/support pathways).

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1. Contribute to the software 2. Report issues or problems with the software 3. Seek support

Software paper

• Summary (required section): Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need (required section): Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• State of the field (required section): Do the authors describe how this software compares to other commonly-used packages? If related tools exist, do they provide a clear "build vs. contribute" justification explaining their unique scholarly contribution and why alternatives are insufficient?
• Software Design (required section): Does the paper include a "Software Design" section that explains the trade-offs weighed, the design/architecture chosen, and why it matters? Is the content compelling and does it demonstrate meaningful design thinking?
• Research Impact Statement (required section): Does the paper include a "Research Impact Statement" section providing evidence of realized impact (publications, external use, integrations) or credible near-term significance (benchmarks, reproducible materials, community-readiness signals)? Is the evidence presented compelling?
• AI usage disclosure (required section): Does the paper include an "AI usage disclosure" section that transparently discloses any use of generative AI in the software creation, documentation, or paper authoring?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[editorialbot]

Repository Analysis Report

Code breakdown

github.com/AlDanial/cloc v 1.98  T=0.40 s (1324.0 files/s, 229343.2 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
HTML                           203            480             95          18644
C                               89           2373           2204          16423
Fortran 77                     110            756           5480           8147
Python                          32           2069           4371           6318
SVG                             12             10             10           4605
YAML                            26            457            117           3124
Text                             8            196              0           2817
Bourne Shell                     3            225            214           1508
CSV                              2              0              0           1108
C++                              4             85             12            810
C/C++ Header                    15             36             71            342
Markdown                         5            129             30            338
Jupyter Notebook                 3              0           5648            314
reStructuredText                12            422           1095            314
TeX                              2             28              0            263
Ant                              1             32             52            240
TOML                             1              7              0             58
DOS Batch                        1              8              1             26
CSS                              2              2              0             17
make                             1              4              7              9
-------------------------------------------------------------------------------
SUM:                           532           7319          19407          65425
-------------------------------------------------------------------------------

Commit Count by Author

372	jmoo2880
    14	Joshua Moore
     5	brendanjohnharris
     2	Sébastien Boisgérault
     1	Brendan Harris

Repository History

Repository age: First commit on June 27, 2025

Code distribution (top 3 48-hour windows):

Period	Insertions	% of Total	Signal	View Changes
Jun 28, 2025 - Jun 30, 2025	150020	35.9%	🟡	View diff
Jan 31, 2026 - Feb 02, 2026	95047	22.8%	🟢	View diff
Jan 24, 2026 - Jan 26, 2026	93893	22.5%	🟢	View diff

GitHub Activity Metrics

Metric	Count
GitHub stars	18
Forks	2
GitHub contributors	3
Releases	2
Total issues	5
Total pull requests	38
Unique commenters/reviewers (excluding authors)	2

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 1452

✅ The paper includes a Statement of need section

✅ The paper includes a State of the field section

✅ The paper includes a Software design section

✅ The paper includes a Research impact statement section

✅ The paper includes an AI usage disclosure section

[editorialbot]

License info:

🟡 License found: GNU General Public License v3.0 (Check here for OSI approval)

[robertmartin8]

Review checklist for @robertmartin8

AI usage

• I confirm that I have read the JOSS AI policy and understand that:
  • AI may only be used for non-substantive assistance (e.g., grammar checking my review text, contextualizing public materials)
  • All evaluative decisions—including scoring, accept/reject recommendations, and assessments of originality, correctness, significance, and ethics compliance—must be made exclusively by me, not AI
  • I bear full responsibility for all judgments, recommendations, and technical claims in my review
  • I will disclose any AI assistance at the conclusion of my review

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the https://github.com/DynamicsAndNeuralSystems/pyhctsa?
• License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@joshuabmoore) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Scope and significance: Does this submission demonstrate clear research impact or credible scholarly significance as described in the JOSS guidelines?
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Development history and open-source practice

• Development timeline: Does the project show evidence of sustained development over time (preferably months or years) rather than rapid, recent code generation?
• Open development: Was the software developed openly from early stages? For projects with recent public repositories, is there at least six months of public development history with evidence of releases, public issues/pull requests, and ideally external engagement?
• Collaborative effort: Does the project show evidence of community engagement — such as contributions from multiple developers, issues/discussions from external users, or community influence on development — in the repo or as described in the paper?
• Good practices: Does the project look like a reusable, non-throwaway research software project that follows good open-source practices (license, documentation, tests and/or verification processes, releases, and clear contribution/support pathways).

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1. Contribute to the software 2. Report issues or problems with the software 3. Seek support

Software paper

• Summary (required section): Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need (required section): Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• State of the field (required section): Do the authors describe how this software compares to other commonly-used packages? If related tools exist, do they provide a clear "build vs. contribute" justification explaining their unique scholarly contribution and why alternatives are insufficient?
• Software Design (required section): Does the paper include a "Software Design" section that explains the trade-offs weighed, the design/architecture chosen, and why it matters? Is the content compelling and does it demonstrate meaningful design thinking?
• Research Impact Statement (required section): Does the paper include a "Research Impact Statement" section providing evidence of realized impact (publications, external use, integrations) or credible near-term significance (benchmarks, reproducible materials, community-readiness signals)? Is the evidence presented compelling?
• AI usage disclosure (required section): Does the paper include an "AI usage disclosure" section that transparently discloses any use of generative AI in the software creation, documentation, or paper authoring?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[robertmartin8]

@joshuabmoore I have completed my initial review: I've worked through the paper and run the package end-to-end (macOS, Python 3.12). The paper is generally well written and the software is substantial and clearly useful. I have a few points of clarification and some minor fixes that would help me check off the remaining items.

Functionality / docs

1. calc.summary() is documented but not implemented. The README shows a calc.summary() call, but this raises AttributeError on the released version.
2. Java is described as a Windows-only concern, but it affects all platforms. Running without Java on macOS, the information module fails silently (only returning about half the features). Probably best addressed as a documentation note, or throw a warning if Java is missing
3. Some features return error strings rather than NaN on failure. In the default configuration, (e.g. first_min_ac, the sliding_window_AC1_* family, autocorr_shape_posDrown → "Unknown ACF decay criterion"). It should return NaN, or Raise.

Reproducibility

4. Validation harness. The paper describes the Pearson r ≥ 0.9 benchmark against MATLAB hctsa as the inclusion criterion, but I couldn't find the benchmark code/data in the repo. Suggested fix: point to (or include) the script and reference series so the validation claim is reproducible.

Authorship

6. Just to satisfy the JOSS authorship check: could you confirm Ben Fulcher's contributions to this package?

Minor (paper text)

7. A few typos: "accomodate" → "accommodate", "anlaysis" → "analysis", "flexibilty" → "flexibility" (Statement of need), and "Analsyis" → "Analysis" in the docs index page.

[mahajanhrishikesh]

Hey folks, the software is great and I find it to be very flexible and easy to use adding to Robert's comments just a few small concerns to address. The CONTRIBUTING.md has a few open TODOs still and a missing email in case of security issues

Line 83: sensitive bugs must be sent by email to <>. (Missing contact address)
Line 128: Setup of environment/IDE typical instructions are marked as a TODO.
Line 134: Documentation update instructions are marked as a TODO.
Line 140: Commit message guidelines are marked as a TODO.
Line 145: "Join the Project Team" instructions are marked as a TODO.

Additionally the version in the .toml and the version in the CITATION.cff does not match... something to align I believe.