Use Case Documentation

[jadie1]

This PR makes the use case documentation uniform and removes a lot of repetition. All of the copy and pasted documentation that was the same for every use case is now only in "Getting Started with Use Cases" file (use-cases.md).
Addresses issues #1103 and #1347.

Each md file now contains the following sections:

• "What is the Use Case?" Describes what the use case demonstrates, what is different about it, and specifications on data
• "Grooming Steps" Describes grooming steps if any with visualization.
• "Supported Tags" Lists tags you can use with the use case
• "Optimization Parameters" Shows the dictionary of optimization parameters and specifies any choices unique to the use case.
• "Analyzing Shape Model" Displays and comments on expected output.

To review this PR you need to checkout the branch and run mkdocs serve. The videos on the sci server will not be visible via the github web interface.

[cchriste]

Can we please link all the related issues to the PR? (Button at bottom of right hand column, "linked issues".) In particular #1103 is linked to lots of other issues. Are these all taken care of with this PR?

[cchriste]

I have compiled and am reviewing the documentation. It might help to update this section in order for reviewing to be inline with the instructions for doing so: http://sciinstitute.github.io/ShapeWorks/dev/docs.html.

[jadie1]

Issue #1103 is linked to all of the use case issues but this PR just addresses the documentation, the use case issues will not be closed with this PR. I believe the two issues I linked are the only relevant ones.

…

On Mon, Sep 20, 2021 at 1:19 PM Cameron Christensen < ***@***.***> wrote: Can we please link all the related issues to the PR? In particular #1103 <#1103> is linked to lots of other issues. Are these all taken care of with this PR? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1472 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AM65AFOJII35AN2AFWYNQZTUC6CKNANCNFSM5EFE6HYA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[cchriste]

There are some missing resources, including simple gifs found on the SCI server (see #1470 (comment)). Other resource found on the sci server are found just fine.

[cchriste]

Here are lots of details and suggestions, starting with...

• ideas to improve the general overview of use cases, then...
• comments on improving specific use cases (including ways to improve them all as well as notes on some of the specific cases), and finally...
• notes about partitioning use cases into their specific categories. This could be related to the type of dataset and/or the category.

[] better organization of general overview page

1. use cases are...
2. the following sections include detailed descriptions of each case
3. use cases demonstrate processing of datasets that are typically downloaded from Girder
   - you'll need to create a free account [using this link], and
   - only required to enter your credentials the first time (if that's true; I can't remember)
4. each use caes consists of grooming, ..., optimization, and exploration of resuts
   - these topics in this page should be under headers that are linked here

• i. grooming is... (explanation of why, including a couple pics and links to python api)
  • describe grooming as in ellipsoid page, then specific pages can simply link to descriptions
• ii. explain general arguments for all use cases
  • (change tags -> arguments)
  • example calls:
    • shorten [insert name of use case here] to [use case name]
  • don't embolden use case name, and do embolden parameter name
    • ex: python RunUseCase.py [use case name] **--skip_grooming**
• iv. (more sections describing use case composition)
• v. optimization
  • what is optimization? what do the paramaters mean? where are they set?
• vi. ... (the rest of the sections of use case steps)
• xi. Running Subsequent Analysis:
  • Analysis -> Analyses

[] specific pages...

• good explanation that downloaded data is pre-groomed

• good pictures!

• starts out good notes about why this use case is worth including (similarities and dissimilarities to others)

  • then gets a little too brief into the teens...

• comprises -> "dataset is comprised of" (for lots of them, just use search in docs)

• grooming steps should link to general page, with additional details as needed

• arguments (not tags)

  • better to use a column
  • each argument should be a link to its description in the general page
  • change "supported" to "pertinent" or "relevant"

• image links are sometimes not working. See comments above.

• fixed domain ssm: put a link to the general page for the one grooming step that's used

• more detailed intro overview for femur, which adds so much to what has been shown before

  • add pictures
    • showing an image since nothing has been shown before that
    • showing single-scale vs multi-scale

• describe segmentation

• ditsance transforms -> distance

  • also, these are segmentation

• femur with cutting planes too cut-and-pasted

  • it's an opportunity to build on the previous example
  • not sure why a NOTE is used to describe difference

...getting overwhelmed with too much of the same; need to break up organization of cases

[] overall organization of specific pages

• maybe reorder use cases or subsections for given types
• Meshes
  • "directly from" sections too much cut and paste, just link to other (or vice versa)
• Particles
• Shape statistics
• Domains
  • mutiple domains
• other?
• maybe constructed datasets vs. real

[cchriste]

See comment on issue.

[sheryjoe]

Steps moving forward:

• Group use cases based on functionality/features demonstrated, e.g., meshes, segmentations, constraints, deep-learning, statistical-tests. This should happen at the docs level (creating subfolders for the use cases).
• Update examples.md to include this categorization and the new use cases. For each use case, we should highlight the feature(s) that are showcased in the use case (what makes it different).
• Add an introduction subsection to the use-case.md to introduce what is a use case in general, what is the workflow, add links to other documentations whenever applicable.

[sheryjoe]

Use Cases:

intro paragraph (refer to the typical workflow with links to groom, optimize, analyze, link to common worflow for meshes and segmentation), 
including link to create girder account

Running
…
Analyses
… that is almost common for all use cases

done!

[jadie1]

@sheryjoe @cchriste This should be ready to be reviewed again

[cchriste]

Wow! This is so much more understandable and worthwhile to users.

• femur mesh not done. Says coming soon. (another issue for this?)
• how do you switch between datasets on multiple domains from mesh use case? It's also missing grooming, says coming soon.
• supershapes: maybe link to or show the equation
• shape statistics in python could link to Python API when we have docs for that (Add _graph_ to our API reference documentation #1079)
• Femur Shape Model Directly from Images should have link back to deep_ssm use case it mentions). Do they need to manually download data for this one?
• right ventricle: is there an issue to finish it?

So a couple small changes, maybe some additional issues (so we don't forget), and merge!

[jadie1]

• Femur Shape Model Directly from Images should have link back to deep_ssm use case it mentions). Do they need to manually download data for this one?

No it still automatically downloads. We are just noting that the data was generated by running the femur use case

[iyerkrithika21]

• femur mesh not done. Says coming soon. (another issue for this?)
• how do you switch between datasets on multiple domains from mesh use case? It's also missing grooming, says coming soon.

For all the mesh use cases, grooming will be added in the next release. Right now they run on pre-groomed data.
We have this issue for it: #1386
The name in the multiple domain use case can be changed in the python code. There are comments and print statements in the code to point to it

• shape statistics in python could link to Python API when we have docs for that (Add reference documentation for our API #1079)

Created: #1492

[cchriste]

• Femur Shape Model Directly from Images should have link back to deep_ssm use case it mentions). Do they need to manually download data for this one?

No it still automatically downloads. We are just noting that the data was generated by running the femur use case

Can this be made more clear in the documentation? All that needs to be added, probably to the data section early on, is what you just wrote. Thanks!

[cchriste]

The name in the multiple domain use case can be changed in the python code. There are comments and print statements in the code to point to it

Will you please add a note to the beginning of the issue that clarifies this for the user? Thank you.

[jadie1]

• right ventricle: is there an issue to finish it?

I am unclear on this use case... Looks like Archana added the documentation.
@archanasri is there an issue for the RV use case? Should we remove it from the doc for now?

[jadie1]

All of Cameron's suggested changes have been made. The right ventricle use case does not show up in the web doc (it's not in the yml) so I think it is okay to leave it.

I also added the note about windows visualization to the notebooks for issue #1113

Should be ready to merge!