Conversation
richjam
left a comment
richjam
left a comment
There was a problem hiding this comment.
Generally, good content, but it's made me think about the usability of all this for general users. I think we should implement a few of the things that have been in the backlog around making it all a bit more user friendly.
|
|
||
| .. rst-class:: lead | ||
|
|
||
| Define and apply flags to your data |
There was a problem hiding this comment.
This could be a bit more of an interesting tagline!
|
|
||
| Define your flags, link them to a column, and apply with a single call: | ||
|
|
||
| .. code-block:: python |
There was a problem hiding this comment.
I'd prefer if this followed other examples of writing code snippets within the src/examples folder. That way, the code snippets get included in the unit tests and we ensure the docs stay up-to-date with any breaking changes.
There was a problem hiding this comment.
(also applies to code blocks below)
| Why use Time-Stream? | ||
| ==================== | ||
|
|
||
| Flagging is a common task in environmental data processing, used to mark data that meet certain conditions |
There was a problem hiding this comment.
I think this intro bit might need a bit more on what flagging actually is.
| core_flags = { | ||
| "UNCHECKED": 1, | ||
| "MISSING": 2, | ||
| "SUSPECT": 4, | ||
| "CORRECTED": 8, | ||
| } |
There was a problem hiding this comment.
I'm wondering if now is a good time to implement the ticket that was about making it so a user didn't have to provide the bitwise values. I think that's confusing in this example (though I realise it goes on to talk about the bitwise stuff later)
| name="CORE_FLAGS", | ||
| flag_system=core_flags |
There was a problem hiding this comment.
Just a comment for myself really that might want to think about renaming these arguments (along with init_flag_column and add_flag)
| Because flags use `Bitwise values`_, a single data point can carry multiple flags simultaneously — for example, | ||
| we saw the value that had both ``SUSPECT`` and ``CORRECTED`` — without any information being lost. |
There was a problem hiding this comment.
I got a bit lost through this example, as it introduces the concept of the bitwise values without any prior explanation. I wonder if this could just show how multiple different flags can be applied to data.
Also, I think it might be sensible to start linking this to the QC checks. Either just showing how the output of the QC checks can feed directly into flagging, or actually change the QC functions to do the flagging as well.
| - **You stay in control** | ||
| Flag systems are defined by you. | ||
|
|
||
| - **Scalable** | ||
| Multiple flag systems can exist in the same TimeFrame. | ||
|
|
||
| - **Safe** | ||
| All flags use *bitwise values*, meaning multiple flags can be combined without losing information. | ||
|
|
||
| - **Reversible** | ||
| Flags can be removed as easily as they are added, using the same expression-based interface. |
There was a problem hiding this comment.
| - **You stay in control** | |
| Flag systems are defined by you. | |
| - **Scalable** | |
| Multiple flag systems can exist in the same TimeFrame. | |
| - **Safe** | |
| All flags use *bitwise values*, meaning multiple flags can be combined without losing information. | |
| - **Reversible** | |
| Flags can be removed as easily as they are added, using the same expression-based interface. | |
| - **You stay in control**: Flag systems are defined by you. | |
| - **Scalable**: Multiple flag systems can exist in the same TimeFrame. | |
| - **Safe**: All flags use *bitwise values*, meaning multiple flags can be combined without losing information. | |
| - **Reversible**: Flags can be removed as easily as they are added, using the same expression-based interface. |
| ============ ============ | ||
| Decimal Binary | ||
| ============ ============ | ||
| 1 1 | ||
| 2 10 | ||
| 4 100 | ||
| 8 1000 | ||
| 16 10000 | ||
| ============ ============ |
There was a problem hiding this comment.
This doesn't format as a nice table in the generated html file
|
|
||
|
|
||
| Combining multiple flags | ||
| ------------------------ |
There was a problem hiding this comment.
Perhaps now is a good time to think about the functionality for 'decoding' flag values - so going from the integer values back to the descriptive values. It's stark reading this documentation that we haven't added that, and I think people will be put off by all the percieved complexity in this doc.
| # ['temperature'] | ||
|
|
||
|
|
||
| API reference |
There was a problem hiding this comment.
This is a good idea, should add these to the other pages (like aggregation, infilling etc).
2 participants
No description provided.