search

rheiland / xml2jupyter

Generate Jupyter widgets (and a notebook) from a PhysiCell XML configuration file
BSD 3-Clause "New" or "Revised" License
8 stars 5 forks source link

Add a simpler example #3

Open choldgraf opened 5 years ago

choldgraf commented 5 years ago

The demo for this project is really cool - though it is a bit complex. I stepped through the GUI, but was still a bit unclear how I could integrate the script into my own workflow. For example, the "usage" section says that you don't technically need Jupyter to run this package, and uses the command line in its sample code, whereas the example utilizes a pre-rendered GUI. I think there should be a minimal example showing the XML structure that this supports, the command to process it, and the kind of output it generates.

choldgraf commented 5 years ago

Another thing I noticed is that the structure of the python configuration file isn't super clearly explained (I also don't see a CLI API documentation in the README anywhere)

rheiland commented 5 years ago

Integrating into one's own workflow currently assumes that workflow involves a custom PhysiCell simulation. I've tried to emphasize this in the README (as well as the paper). I did provide a minimal example showing the supported XML structure in the README. For my part, I think I've been a bit confused about what needs to be said in a JOSS paper vs. a JOSS repo. Obviously, it doesn't hurt to duplicate, but it does seem a bit redundant.

Not sure I understand the comment about a CLI API doc. Don't think there's enough there for an API, but maybe I'm misunderstanding.

choldgraf commented 5 years ago

re: the CLI stuff, I think I had mis-interpreted the functionality of the package, so feel free to dismiss that :-)

re: what should go into the JOSS paper vs. the repository, I think the repository will have much more potential viewership than the paper, so any "useful" information should be in the repo documentation IMO

choldgraf commented 5 years ago

Looking through this more, I think the documentation would benefit from some basic information about the inputs and outputs. E.g. many Python modules have a section like 

Inputs
------
input_parameter : type
  description

Outputs
-------
output_one : type
  description

and most CLI modules have help associated with them (e.g. if you used argparse to parse inputs, you could provide help for each input).

Could you add in the README a section that explains what each input to the script is, an example of how it's structured, etc, as well as the script will output? E.g., it seems like it outputs a full python module that's meant to be imported (but can only be done from within the same folder since it won't be in the PATH)

choldgraf commented 5 years ago

Another question: I've gotten this to correctly output a widget that shows the configuration values. But I haven't figured out how to make the plot with visualizations etc. The documentation says there are "static files" you can add somewhere, but there's no example or instructions for how to do so. Can you add this into the README?

rheiland commented 5 years ago

Added documentation header to xml2jupyter.py. Still not using argparse, but familiar with it and may reconsider in the future. Also added brief descriptions of modules in README.

Added section in README describing how one runs the full GUI (with the sample data visualized).

choldgraf commented 5 years ago

Nice - that definitely helps. I added that content to the README in a pull request here: https://github.com/rheiland/xml2jupyter/pull/6 I think that would make it more discoverable