Writing tutorials

[SimonBiggs]

The PyMedPhys documentation aims to be based upon the "grand unified theory of documentation":

https://diataxis.fr/

One thing that is sorely missing are tutorials that show newcomers how they can be successful with PyMedPhys.

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented.

-- https://diataxis.fr/tutorials/

If you are interested in contributing to the PyMedPhys project this would be a brilliant way to target one of the biggest gaps for helping newcomers be successful at the beginning of their PyMedPhys journey.

[nlambriICH]

Hi @SimonBiggs

I'd like to give my contribution on this!

Since I'm new to PyMedPhys, I think I would need some guidance about what topic I should focus on in order to start writing a simple tutorial.

Is there a specific module I should start from?

[SimonBiggs]

Hi @nlambriICH,

That would be brilliant :). An imperfect measure of what PyMedPhys is being most used for is how it is cited within the literature:

https://scholar.google.com.au/scholar?q=pymedphys

Using that to judge where best to start might be great? I have noticed a lot of people who use the gamma implementation don't use the parameters that can significantly speed up the calculation. For example when only a pass rate is desired, such as in the following paper:

https://aapm.onlinelibrary.wiley.com/doi/full/10.1002/mp.15683

Then parameters such as "random subset" and "max gamma" are very helpful to speed up the calculation. I think it would be quite neat to have a tutorial where by the end the learner has practically utilised the pymedphys gamma function for a quick calculation of the pass rate.

I'd be happy to also help you get set up with writing tutorials, potentially as we get you set up you can keep a record of the steps and a tutorial could form on how to write and submit a tutorial to PyMedPhys? That would also be an awesome tutorial :)

Let me know your thoughts. At the end of the day, you feel free to focus on what you're most passionate on and I can help you make it happen :).

[nlambriICH]

I think starting from a tutorial for the gamma calculation would be great! I also agree that this could be a great opportunity to write a guide on how to add new tutorials!

If I understood correctly, we need a new "Tutorials" section in the documentation of PyMedPhys. A good first tutorial would be one that explains in details the parameters used for the gamma evaluation to provide the user a deeper understanding of this function.

I'll use this documentation page as a reference to get started.

[SimonBiggs]

Yup, sounds good :). To help write it the following section on "the language of tutorials" can help act as a bit of an initial template:

https://diataxis.fr/tutorials/#the-language-of-tutorials

[SimonBiggs]

Hi @nlambriICH,

There is a new PyMedPhys user who is keen to get their feet wet with PyMedPhys:

https://pymedphys.discourse.group/t/learning-python-in-prep-for-grad-school/215/4

Potentially they might be a great test participant of the tutorial? Potentially worth chatting with them, and getting feedback on draft iterations of the tutorial(s)? What are your thoughts?

Cheers,
Simon

[nlambriICH]

I think it might be a good idea, however as I'm still new to PyMedPhys and will be working on it in my spare time, I don't know how long it will take me to write the first tutorial...

Maybe we could point out some python resources, and stay in touch during the developement of the tutorial? (I don't have enough knowledge of this project to suggest a possible contribution)

[SimonBiggs]

Hi @Matthew-Jennings,

Here is another user who would be interested in writing up tutorials. Might you be interested in spearheading getting these tutorials written with this group of people Matt?

[Matthew-Jennings]

@SimonBiggs, sure, I can dedicate some time.

@nlambriICH, have you tried going through the PyMedPhys Contributors' documentation? Following the setup instructions for your OS is a good place to start

[nlambriICH]

Hi @Matthew-Jennings,

Yes, I've already followed the instructions and setup the PyMedPhys project.

I've added a new notebook with a tutorial for the gamma calculation. I think I'll submit a pull request in a short time when I think the tutorial is ready for review!

[SimonBiggs]

I think I'll submit a pull request in a short time when I think the tutorial is ready for review!

Feel free to submit the PR as soon as you've begun working on it, and then just use the "request review" feature once it is ready for review:

That way, other's can chime in and help early before it is "finished". It would suck to be travelling in the wrong direction when most of the work has already been done.

And to be doubly sure, when creating a PR you can mark it as a "draft PR" if you'd like.

[Matthew-Jennings]

Hi @Matthew-Jennings,

Yes, I've already followed the instructions and setup the PyMedPhys project.

I've added a new notebook with a tutorial for the gamma calculation. I think I'll submit a pull request in a short time when I think the tutorial is ready for review!

@nlambriICH, great! Just ping me as per @SimonBiggs' instructions when you're ready. :)

I'd second his point about opening a pull request early. There's really no harm in pushing your changes from the beginning - no one is here to judge; we really do appreciate contributions and will work with you to get them in main.

[nlambriICH]

Thanks @SimonBiggs! However, I think I don't have the rights to request the review of a specific person.

@Matthew-Jennings, I've just created the PR, thanks!

[jrkerns]

TIL about that site. I like it very much!

[SimonBiggs]

Absolute pleasure! Also, btw, side note, the next release of pymedphys will no longer have a pylinac dependency, so, you should be able to readily use it interchangeably within your tool stack 🙂