Repository navigation
[Feature Request] NaN safety, we probably need something more than doc strings. #311
Description
In context of machine learning, many of the optimization algorithms rightfully preclude the presence of NaN values.
The documentation of the function may sometime mention, or not mention if a function can return NaN, and also, how it process NaN as input.
Alas, this is not systematically described, and also, people will just try functions left and right, when they are doing exploratory feature engineering.
The first focus would be to make sure the library offers some batteries included for those that don't want to find out "too late" in the pipeline (as they are long to setup, adjust, run, troubleshoot, etc.).
Without going too far in terms of how to make things perfect, and most sophisticated for long term maintenance, in all places, there is a plan that could bring some safety and long term maintainability:
- Offering an FSharp.Stats.NumericallySafe module (people open it after FSharp.Stats and it shadows the unchecked variants), there could also be a module with assertions that would defensively throw
- the module would call the existing APIs but wrap the values in a type that enforce the inspection via pattern matching or helper functions, borrowing idioms from F# core around
optionorresult - the existing API should have CLR attributes on the functions / methods signalling "emits NaN", "accepts NaN"
- there would be property based tests, possibly guided with code coverage, that would validate against presence of those attributes
- there would be a page in the documentation pages that list all the functions, with filters about those "emits NaN" and other attributes
One can dream :)
In the meantime:
- I wanted to point out that
meanGeometriccan emitNaNbut the documentation says nothing about this, and it is not exposed underFSharp.Stats.NumericallySafe. - In the documentation pages, we'd want to display warning sections after describing the formula, logic, sample code, with a styling that will catch the attention.
related: #280
Activity
smoothdeveloper commentedon Nov 15, 2023
I think we can ensure consistency based on presence of this, which seems to be in place (but it is not really discoverable in code, nor in the documentation pages.
We can also define F# analyzer that looks for functions like
sqrt, that are bound to produceNaN.If someone who groks maths (not me) could list here the F# and BCL functions that produce
NaNthat are used in this library, it would help with the implementation of such analyzer.smoothdeveloper commentedon Nov 15, 2023
One issue with
open FSharp.Stats.NumericallySafeapproach, is you can only switch in your code using#ifprecompiler directives, or otherwise, you need to pass references to functions, rebind them in your own module based on some context.There are scenarios where I'd want this to be done without recompiling nor forcing to rebind each function of interest.
github-actions commentedon Mar 23, 2026
🤖 This is an automated response from Repo Assist.
This is a well-thought-out issue. A few observations that might help narrow scope:
What's already in place:
(remarks)XML doc tags likeReturns NaN if data is empty or if any entry is NaNexist in parts of the codebase (as noted in@smoothdeveloper's comment). The gap is systematic coverage and discoverability.FSharp.Stats.Precisionmodule providesalmostEqual*helpers that indirectly address some NaN edge cases in convergence checks.A pragmatic first step (lower effort, high value):
Rather than a full
NumericallySafemodule, a documentation-driven approach could work well:(remarks)documenting NaN behaviour.The
FSharp.Stats.NumericallySafeshadowing module idea is elegant long-term, but the biggest near-term win is ensuring users can discover the NaN contracts of functions they're already using.If anyone wants to tackle this incrementally, starting with
Seq/List/Arraystatistics functions and theFittingmodule would cover the most common ML-pipeline use cases.Note
🔒 Integrity filtering filtered 1 item
Integrity filtering activated and filtered the following item during workflow execution.
This happens when a tool call accesses a resource that does not meet the required integrity or secrecy level of the workflow.
search_issues: has secrecy requirements that agent doesn't meet. The agent is not authorized to access private-scoped data.)