Guideline rules on name and type conventions #9
Conversation
| @@ -43,6 +40,56 @@ We plan to include the following in future versions of the guidelines: | |||
|
|
|||
| - *Provider*: A callable step in a workflow writing with Sciline. | |||
|
|
|||
| ## C: Convention | |||
There was a problem hiding this comment.
Please either remove the empty Naming below if you prefer Convention, or move this.
| | --- **Run IDs** --- | | | | ||
| | SampleRun, BackgroundRun, ... | Any | Identifier for a run | | ||
| | RunType | TypeVar | Constrained to the run types used by the package, see above | | ||
| | RunTitle | str | Extracted from NeXus or provided by user, can be used to find files | | ||
| | --- **Monitors** --- | | | | ||
| | IncidentMonitor \| *Monitor | Any | Identifier for a monitor | | ||
| | MonitorType | TypeVar | Constrained to the monitor types used by the package, see above | |
There was a problem hiding this comment.
Here we assume that a workflow necessarily wants/needs to use generics for runs types and monitor types. Is that a good assumption? Or should we consider formulating it as "if using generics for X, use this convention"?
Should we maybe split C.1 to discuss naming for generics (and their typevars) separately?
There was a problem hiding this comment.
Here we assume that a workflow necessarily wants/needs to use generics for runs types and monitor types. Is that a good assumption? Or should we consider formulating it as "if using generics for X, use this convention"?
I don't understand what you are saying. When we don't use generics, the SampleRun, ... and RunType simply don't exist. This table doesn't mandate using all entries, it's supposed to tell us how to name them if and when we need them.
Should we maybe split C.1 to discuss naming for generics (and their typevars) separately?
Why? How would you structure that table?
There was a problem hiding this comment.
I don't understand what you are saying. When we don't use generics, the SampleRun, ... and RunType simply don't exist.
Say I want to write a workflow that process a sample run and a vanadium run, without use of generics. Which names do I use?
I am suggesting to make two guidelines (each with their own table), or have a separate guideline specifying conventions for naming typevars and identifiers.
There was a problem hiding this comment.
In principle, this is already part of it. Simply ignore the Run IDs section and use the '*Filename'-type patterns. Do you think we need to be more explicit and list {Sample,Vanadium}Filename, {Sample,Vanadium}RawData, etc?
There was a problem hiding this comment.
If the reader is not familiar with using generic providers in a workflow then the current table is quite unclear. Please make a separate guideline. We do not need to make an explicit list.
| - Gracefully promote dtypes for small parameters. | ||
| E.g., `sc.scalar(2, unit='m')` and `sc.scalar(2.0, unit='m')` should be usable interchangeably. |
There was a problem hiding this comment.
👍
Should we require the same, e.g., for params like bin-edges such that, e.g., passing arange works just like passing linspace?
There was a problem hiding this comment.
Doesn't it work the same way?
There was a problem hiding this comment.
Operations may raise when ints are passed instead of floats as coords (bin edges, for example). I am suggesting extending your suggestion for graceful handling.
| |-------------------------------------------|---------|-----------------------------------------------------------------| | ||
| | --- **Run IDs** --- | | | | ||
| | SampleRun, BackgroundRun, ... | Any | Identifier for a run, only used as a type tag | | ||
| | RunType | TypeVar | Constrained to the run types used by the package, see above | |
There was a problem hiding this comment.
So is the rule to end typevars with Type?
There was a problem hiding this comment.
Don't know in general. I've only seen those two in practice.
There was a problem hiding this comment.
@SimonHeybrock Do we need to do anything about this?
There was a problem hiding this comment.
Should we make this a rule? I think it is quite confusing to know what is a typevar and what is and ID otherwise?
| | Name | Type | Description | | ||
| |-----------------------------|-------------|---------------------------------------------------------------------------| | ||
| | --- **Files** --- | | | | ||
| | Filename \| *Filename | str | Simple name of a file, must be processed into FilePath | |
There was a problem hiding this comment.
Should Filename even exist? If the file is obtained from SciCat, we only have FilePath, I suppose. Otherwise, can we replace Filename by, e.g., and instrument identifier and a run number?
There was a problem hiding this comment.
SciCat datasets can contain any number of files. So we need a pair or (dataset id, file id). And the file id can only really be a file name.
Fixes #7
Please flag any and all names / types that you don't think are appropriate! And suggest any that I missed.