create a flow diagram and description of the process of name alignment

[jhpoelen]

to help document the process of name alignment

[jhpoelen]

@jtmiller28 - today in a conversation with bat biologist Aja Sherman @ajacsherman a desire for a name alignment flow diagram came to the surface again. I was thinking to create, and then also remembered https://github.com/Big-Bee-Network/name-alignment-workshop/issues/9, and I was wondering whether I can re-use your flow diagram. If not, I can create one and share with you instead.

[jtmiller28]

Hi Jorrit, Thats right! I had momentarily forgotten about that. I will try to create one and post it on this issue to see if you have any suggestions/ideas to add.

[jtmiller28]

Hi @jhpoelen , if you have a moment I made some quick flow diagrams illustrating the overall process of the alignment tool + another illustrating the data fed and output of the alignment. Ill drop the rough draft here, let me know if you have any thoughts/additions.

[jhpoelen]

@jtmiller28 very cool! Thanks for sharing your drafts.

Some thoughts I had are:

• with "commit alignment", what do you mean? Do you mean saving the alignment workflow configuration, or the process of running the name alignment.
• some boxes refer to data (e.g., scientific name field) others to processes (like parsing, something that takes some input and produces output). I was wondering whether you have ideas on how to distinguish the two.

[jtmiller28]

Hi Jorrit,

1. Commit alignment refers to the commiting step in regards to editing the readme to initiate alignment. I initially thought it'd be a good way to integrate some of the unfriendly github language into the diagram to make better sense in what is happening/the process. But if it causes more confusion, I can change it to saving alignment configuration and proceed to start alignment.

2. Not sure! Color coding with a legend might be an option, say yellow for user inputs, grey for intermediates, and light blue for outputs? Was already "testing" that route with Yellow/Orange indicating user data/steps that the user should take. Any other suggestions in regards to this?

[jhpoelen]

@jtmiller28 thanks for your prompt reply.

re: 1. I leave this up to you! Maybe you can ask some of your peers to what communicates most information

re: 2. some diagrams use different shapes for different kind of things. Perhaps UML will inspire . . . https://en.wikipedia.org/wiki/Activity_diagram . I leave the final decision up to you and what makes most sense to you and your peers.

[jtmiller28]

Well now thats interesting, I was not aware of UML (My flow diagrams come from ecological modeling theory rather than CS). Ill try it out and see!

[jhpoelen]

Whatever is more intuitive to you. UML can be kind of clunky.

[jtmiller28]

Second rough draft utilizing some UML: Agreed its a tad clunky, but I always enjoy trying to find different ways to break down and visualize systems. Maybe a bit intuitive with the legend added?

[jhpoelen]

Wow that looks pretty neat! And yes, the UML folks can come across as a bit funky every now and then. But hey, you can know add "UML" to your CV ; )

I leave it up to you to choose the format that makes most sense to you. Perhaps the selfish use of the workshop documentation is to remind your future self of what you've done . . .

[jhpoelen]

btw - I liked your explicit reference to default catalogs. Perhaps do the same with names? We do have a default name list.

[jtmiller28]

I think I enjoy the logic of these types of diagrams, though trying to keep in mind that simplest explanation of whats going on is probably for the best. For now I'll go with these unless there's pushback about how approachable they are.

Forgot about the default name list! Changes should be reflected in this new diagram.

[jhpoelen]

Fancy! Thanks for updating the diagram. Curious to see what will make it into the workshop publication.