Update docs #60
Update docs #60
Conversation
…m in our notebook
its unclear to me what the sphinx action is doing and why its not picking up the notebook
Caroline, Will, and Tri's tutorials have all been merged into one with appropriate headings for navigation. Everything else has been moved into a "depricated" folder since I am not sure whether they run or not.
for more information, see https://pre-commit.ci
it hangs forever
There was a problem hiding this comment.
I think we are close, but integration of the two parts is still not great. I recommend putting the shorter examples with less explanation at the beginning as a Quick Start, and the in-depth tutorial afterward, with a bit of change in the scaffolding text to make it flow. The dask comparison would make sense in between to transition from one to another.
|
|
||
| # %% [markdown] | ||
| # All the labels are now consistent! If you re-run the previous cell with `read_write_conflict=False`, you should see an inconsistent result again due to the race conditions, even though the process function still reads the neighboring output. | ||
|
|
||
| # %% [markdown] | ||
| # **IMPORTANT PERFORMANCE NOTE:** Be aware that `read_write_conflicts` is set to `True` by default and can lead to performance hits in cases where you don't need it, so be sure to turn it off if you want every block to be run in parallel! | ||
|
|
||
| # %% [markdown] |
There was a problem hiding this comment.
This still doesn't really make sense as one big tutorial. I think you should put this part that you wrote first as a "Quick start", and then have the part I wrote below as an "In-Depth Tutorial."
examples/tutorial.py
Outdated
| Path(tmpdir, f"{block.block_id[1]}").touch() | ||
| return block | ||
|
|
||
| def check_block(block: daisy.Block) -> bool: |
There was a problem hiding this comment.
If the quickstart is first, you can link to the in-depth tutorial locations. E.g. "For more information about the performance implications of the check function, look here (link to in depth section)"
| #  | ||
|
|
||
| # %% [markdown] | ||
| # # Map Reduce and Some simple benchmarks |
There was a problem hiding this comment.
I don't really understand what information this part is trying to impart - I'd probably remove it
There was a problem hiding this comment.
I think the main value seemed to be the timings. I figured it can't hurt to have a few more simple examples
examples/tutorial.py
Outdated
|
|
||
| # %% [markdown] | ||
| # Success! Notice that there is a fade to black at the border, due to the `fill_value=0` argument used when reading the data from the input Array. | ||
| # Smoothing is poorly defined at the border of the volume - if you want different behavior, you can expand the input array to include extended data of your choice at the border, or shrink the total output roi by the context to only include the section of the output that depends on existing data. | ||
|
|
||
| # %% [markdown] | ||
| # ## Conclusion: Dask and Daisy | ||
| # ###Conclusion: Dask and Daisy |
There was a problem hiding this comment.
I would move the section about dask vs daisy between the "quickstart" (your part at the bottom that I think should go first) and the "in depth tutorial". This makes the flow make sense - we have some simple examples, these simple example can also be done with dask. However, daisy is good at X situations. If you have one of X situations and want to learn how to use daisy's unique capabilities to optimize your workflow, read the in-depth tutorial.
There was a problem hiding this comment.
I tried this but it felt pretty awkward. There's a lot of info needed to build up to the smoothing task, to then compare dask and daisy. I moved the quickstart examples up to the top, but left the dask comparison in the body
examples/tutorial.py
Outdated
| # | ||
| # Here is an mp4 visualization of the above task | ||
| # | ||
| #  |
There was a problem hiding this comment.
Jan says the blue task is going too fast and overlaps with green in the corners, which is incorrect. But he also LOVES it! 😄
There was a problem hiding this comment.
Oh I see the confusion. The life cycle of processing a block is "move to location", "create block outline", "mark block done".
This means that the green/blue read/write rois still overlap with the block after it has been marked done. So the read roi of the blue task will overlap with the green write roi of the previous task, this is because the most recently completed block from the previous task will always be green.
I could add an extra step for the block processing animation "fade out" after completing a block, but I think that would be annoying to watch the block Rois fade in and out constantly.
Docs now build with the github actions.
API and Release docs have been updated.
Tutorial has been added. It now executes as part of the build action ensuring that the tutorial always remains up to date and executable.