 So welcome to the last part of this tutorial. So my name is Matthias Berndt. I'm working at the Center for Environment Research, the U of Z in Leipzig, Germany. So I'm a bioinformatician and I'm working with Galaxy for a few years. So we host our own Galaxy server for our research center and I'm developing tools for three to four years, I would say. So in this part of the tutorial, I would like to introduce you to Planemo, showing you here the main GitHub page with some information. So GitHub.com, galaxyprojects.planemo, but maybe even more important could be the documentation, which is hosted at readthedocs.io, which contains also quite a lot of useful information for tool development. So advanced tool development topics, how to FAQ section, you have best practices, and so on and so forth. So this section here, Building Galaxy Tools itself, is kind of a different tutorial for how to build tools. So a rich source of documentation. So what is Planemo? Planemo is a command line tool that helps you, for instance, to develop tools. So it helps you to link tools to make a static source code analysis of your Galaxy tool XML files. It also allows you to test Galaxy tools. It means that the tests that are defined in the Galaxy tool test section are executed on a Galaxy server, which is run within or from Planemo. And the third thing that we want to cover in this tutorial is to serve Galaxy tools. So this means that a Galaxy instance is started, and the tool is displayed within a Galaxy, which helps you to fine tune, let's say, the representation, also test the tool more or less manually. OK, the first thing that we want to do, what I need to do, is to install Planemo itself. So Planemo is a Python software, and you can find it on PyPy. And PyPy software can be installed with PIP. So if we would just do this, then this would go to your system's Python software installation location, which would need super-user access, which is not always available in particular high-performance systems. So we will install it in a so-called Python virtual environment, which we need to create first, which is quite easy. So we do this with the following command, virtual-env, which creates a virtual-env in the location that we specify, temp-v-env, in this case. So for a long term, on the long term, you should choose a location that is persistent. So I just do it for the tutorial here in TMP. So it will be gone after a while after reboot. But maybe you install it in your home directory or some other permanent location. And I usually specify with minus p that I just want to be sure that Python 3 is used. So many systems still have Python 2 and Python 3 available. And I just want to make sure that Python 3 is used. So then we can just enter. And virtual environment is created. So this is basically just a directory which has its own file system tree. And in particular, it contains links to the actual Python implementation and also contains pip, the Python package installer. So the first thing that we always need to do then to work with this Python virtual environment is to activate it. And we do this by sourcing. So just type dot or type source, whatever you prefer. And then the pass to your virtual environment and then bin activate. And this activates your virtual environment, which is always indicated with the name of the virtual environment or in your prompt. So it should. So then we can install planemo, pip install planemo, which would install the latest version, which is useful, but you could also specify which version you want to install. So this will now download planemo itself and all its requirements. So this might take a while. So here it's quite fast because I did this before and all the packages are taken from the cache. So just consider that it might take a few minutes in particular if you are on a slow internet connection. So when everything is downloaded, it's installed. And everything goes into the path where your virtual environment is located. So since this is owned by you, you can install whatever you want in this virtual environment. So if this is done, we have planemo ready to go. So the command is planemo. And let's just check with minus version if it's running. So we see we have installed planemo version 0.7.4.4. Might be different if you check out this tutorial later. So planemo minus minus help will give you an overview of the commands that are available in planemo. And you'll see it's quite a lot. So I even need to scroll here. We will consider, first of all, the lint command. We will consider the surf command and the test command. But there is many more to do. You can, for instance, tool init, which would create starting XML for a tool. Then there are things to upload tools to the toolshed. And many more things, also commands to work with conduct packages. But the three lint, test, and surf are probably the most used functionalities of a planning. So if you want to have help on one of these commands, then you just type planemo, then, for instance, lint. So the name of the command and then minus minus help for the corresponding command. And then there are command line parameters that you might want to apply. OK, that's it, basically, for the installation. And then we can go right away into testing tools and linting tools. So the first thing we want to do is to change into the directory of the example tool that is provided with the tutorial. It's called Belero Phone. Let's just open the door. Here we have the tool XML file, which looks good. So then let's, first of all, lint the tool. So this is really easy, planemo lint. Planemo lint will just lint all the tools in the current working directory. So we can just execute this, or we could add explicitly the XML file that we want to lint. There's also a shortcut, so we can just type planemo l, which would lint the tool. So let's execute this. It has a little bit of output, and in the end, it tells us if it was successful or not. So in this case, it wasn't. So we can now check the detailed output. So first of all, the linter checks the order of the elements in our XML file, and it tells us that requirement is at the wrong position. So it's after the command section, but it should be before. So we can simply move this. Then the output check tells us that the output doesn't define an output format, which is correct. So this is missing. So we can just add this here. So let's further the inputs. There's no warning. Then we have a warning for the help section because there is still a to-do, because somebody thought that it might be cool to have more documentation. So more documentation. So let's see. Then we have some information that the tool targets the 16-0-1 Galaxy profile. So no profile was specified here, but it might be a good idea. Many repositories like the IOC even demand that the profile is not older than the year. So let's just do this profile because 20-0-1. So tool contains a command, has citations, and is also valid XML. So let's save this and linter again. And yeah, that's basically it. Now, after our changes, linting is successful. So we see that now the new profile version is detected, and so on and so forth. So the Planimolint command helps you to find errors or common mistakes in your tool XML file. So it's a static code analysis, which can be really helpful. So the next command that we want to cover here is Planimoltest. This has lots of options. So I only will mention two of them later. For the other ones, I think it's a really good idea to go through them once, at least, to just read the documentation here. And in case you have questions, what this and that parameter does, just ask it through while we are doing the tutorial. So Planimoltest, like Planimolint, the execution is just Planimoltest, which we'll do the following. So let's just go through the output while it's doing those. So the first thing it does is some git actions. So it basically gets a clone of Galaxy. So this is basically located in your home directory in .planimol, which stores the Galaxy repository or clone of the Galaxy repository, kind of bare repository. And this is then deployed into your temp directory. So after this is done, Galaxy is starting. And the first thing to do there, also Galaxy is certain in Python, is it sets up its own virtual environment and then installs, again, quite a lot of Python packages which are needed to run Galaxy. So also this might need a while when you do this the first time or if the requirements update, which happens from time to time. So after this is done, Galaxy basically installs the database. Let's see where this happens. Galaxy main queue creating database. So it creates a new database for this Scratch Galaxy that is just running. Let me just increase this here. And then after a while, Galaxy is running. You see that it's running on local host on a specific port. So I think it's a random port, I'm not sure. And then it's basically running the tool. So the first test basically starts here. Test one, starting. The first thing it does, the tool uploads or Planemo uploads the test data from your test data directory. So this is done with the upload tool. The upload tool is running from here to here, essentially. So it creates a script for the upload. And then it's basically it. And the second thing, the second job that is running is the actual tool script, another upload. Sorry for this. And then job three is the actual tool. So basically what is executed is this script. So the so-called tool script. What it does basically is it activates a conda environment. So this might also need a while. So before, essentially, after you see this output, it might also here need a while until it continues because Galaxy will create conda environment that is used by the tool. Anyway, then the script is generated. So activation of the conda environment. And then the actual tool is executed. And you see here the command sign that is generated. And then the tool is executed. And you see that there is a problem. So the test fails. It says that test files differ between the ones in the test data directory and the ones generated in this Galaxy Run. So we have two lines of difference. And we can also see this here. So what's basically different is the PG line. Which is created by Bellerofone. So basically the output stores what programs have been run to generate the data that we see. In this case, it's Bellerofone. And the problem is that the data set differs here. So the test data basically was generated manually. Was using forward.bum and reverse.bum for the data set names. But in Galaxy, it's this hash data set name dot dot. So what we need to do is to allow a difference between the generated test output and the one that is provided in the test data directory. So I think this was line stiff equals two. So we'll allow one difference, which is manifested in one removed line, one added line. Therefore, we have two. So let's just name more lint again. Because I'm actually not sure if it's line stiff. Yeah, this seems to be correct. And then we can test again. Before we do this, I want to show you something different, which is the output generated by Planimo. So Planimo generates two outputs. One is an HTML file, which is by default named tooltestoutput.html. And one JSON file. So mostly interesting is the HTML file. So let's just open this. So this is basically a nice-looking report. What's the result of your test? So it tells you how many tests have been executed and how many failed, how many passed, and so on. And if you click here on the text failed tests, then you can see the test report. So it shows you the problems that have been found. It shows you the command line that has been used, the exit code, job parameters, and so on. So usually, this is sufficient to determine what's going on in your test. And only in really few cases, you need to check the output of Planimo test itself. So let's test this again with our change. Again, Galaxy is starting. The requirements are checked. So this should now be as fast as on my computer here, because you will also now have already the clone of Galaxy. You will already have the requirements. And then this doesn't take too long. The Galaxy virtual environment is just activated. Again, the database is created. And now the test should be starting in a second. So Galaxy is up. First test is starting. So this is the first upload running. Now we have the second upload, the actual tool. And now the test runs OK. And in the end, we also see the summary here. All tests executed have passed. So that's wonderful. There'll be one more note. So we see here all sorts of outputs, so all the get requests that are made. And also output. So this will go away soon. So this is essentially it's not a bug, but it's not really nice, because it makes it more difficult to see what is actually going on. So don't wonder if in the near future this will go away. So many of the outputs. And then you will only see the most important pieces of information for you. So let's just undo the change here. Now I want to show you, let's say, my most favorite command line options of Planimo test. So the first is dealing with the problem that often it's good to have many tests. So let's assume you have maybe two or three tools. Each of them has five to 10 tests. So my rule of thumb is always that if you have a parameter, then you should have at least one test covering this parameter. So maybe you have an integer parameter. Then at least one test should set it to a non-default value. And then you can check if it's set correctly on the command line using assertions, or you can check if this changes the output as expected. And if you have that many tests, of course, this needs quite a while to execute them using Planimo test. And now we can have the case that maybe just one out of the 20, 30 tests that you're executing is failing. And then you are working on fixing this. It might be as simple as in our case here, but often it is not. And it needs many iterations of running Planimo test. And running all those failed tests, all the successful tests, again, usually is not really helpful. And so there is an option for Planimo that allows you to run the same tests again, but executing only the failed ones. So in our example here, it's not really realistic because we only have one failed test. But I just want to show you how the system called. So the option is called failed. So this will lead to the execution of only the failed test of the previous iteration. And how does Planimo know which tests failed or not? So this is basically stored in the JSON file of the output. So we just have a look here. So it's an hierarchical document which contains the information of all tests and somewhere hidden is the information if it failed or not. So this is basically used by Planimo test failed. And the other option that I use quite a lot is no cleanup. So usually when Planimo is finished, all the temporary, so the Galaxy instance that is created in the temp directory is deleted and also all the job output directories and so on and so forth. But sometimes it can be helpful for debugging to keep those directories. And I will show you how to work with them. For debugging, a Galaxy tool run. So let's just wait for the tests running again. Database has been created, Galaxy is up and now the two uploads are starting. This is the first one, actually tool starts. So here's an interesting piece of information. So the actual tools, so what we can do now is we can change into this directory which is the working directory of our local phone job. And the problem, if you don't run this with the no cleanup option is that this will be done after Planimo finished. But now since we use no cleanup, it's still there. So what we have here basically is two shells. So this one here, some colors. So this one basically sets up everything, the environment for the job. So it sets variables, it creates directories and it executes the actual tool script. So it changes into the working directory in our job directory and then executes this tool script and records our exit codes and redirects outputs and so on and so forth. So the actual tool script is this one here. This is also the one that we see in the output of Galaxy. So what is this doing is it activates the condo environment and we can now do this here. So we are now basically in an environment that is more or less the same as the one that is executed from the Galaxy. And now we can just execute this command line here and then see if this fails or not. So in this case, it doesn't. We can also have a look manually in the output. So for instance, with some tools, and then we see the generated file. So in case you have problems with the generated command line, then you can basically play around with the generated command line and try to fix it in an interactive way, so to say. This can often be much faster than iterating a planning mode test and planning mode test and planning mode test again. And here you can be much faster sometimes. Okay, let's go back and go to the last command that we want to cover in this tutorial, which is planning more surf, planning more surf. You can call it in the tool directory and then it will basically start a Galaxy instance running the tools contained in your directory. So again, it does the same clone and get, starting Galaxy, but here it will do a little bit more that we'll start after the initialization of the requirements, which starts here. It basically installs all the client code needed for Galaxy. And this will need quite a while. So I would say 15 minutes, something like this. So this would be now a good time point to have a break, maybe get a coffee or your favorite drink. And then we will continue after Galaxy started. So now Galaxy started. So basically the same things as for planning more tests started, but in addition, if we go through, there's loads of things happening here for the initialization of the client code, also loads of downloads happening. And in the end, we will see that it has a skeleton so instance main is running and a little bit up. We find here listening at local house port 1990. So we can copy this text open browser and open it. So we see that our Galaxy instance is running and we can check now the tool form. So we see how it looks like. We see maybe we should add a description to the tool. So the description tag is missing more or less. We see the help, we see how the citations would look like. Actually it seems they're missing, I don't know why. So, and we can of course test the tool. So let's upload some data on. So this Galaxy instance works completely as a normal Galaxy instance, but it just has this single tool running. Yeah, what's going wrong here? So for some reason, this is stuck. So now I restarted the plan demo self. I don't know what went wrong, but now it seems to be fine. So I go to the browser, open local house 1990 and can check the tool and I can upload data. Now it really works. And I can also choose the test data from a test data directory, just upload it, start. I also noted that now the citation is shown. So apparently something went wrong during the first, my first try to plan a more self. So now the upload is happening and now you're fine to choose the upload data. But hey, it doesn't work at all. So the problem is, so that we have actually a bum input and the tool only accepts some. So there's something wrong here and this needs to be fixed. So we can fix this by just adding unsorted bum as a data type for the input and then we can reload the tool. So the nice thing is that if we change the tool then we will see that the tool is passed again. I don't know why this is throwing an error here, but tool loading works. So we have the forward and the reverse and then we can execute it. And then we see the same thing as in plan demo test that the tool script is generated, it's running and in Galaxy we see that also the tool is running now. Yeah, and here the problem was that we also need to set output to unsorted.bum, short comment on this just quickly. And as you see, this is one nice side effect of plan demo serve. So sometimes it's faster to say in particular for hard to debug problems. It's faster to play around with the tool in a plan demo serve session and just updating the tool XML file. Of course, plan demo serve startup as you have seen needs quite a while and then you need to see when this can get faster iterating test runs. Because you just saved the Galaxy startup time, that you would have in plan demo test, but the plan demo serve upload time is quite fast. So maybe a little bit to the problem here. So this seems to be bug currently in Galaxy that if you have some as input, this also accepts bum which it shouldn't. So we are currently trying to fix this. So this should have been detected already in the plan demo test, but we have seen that at least in the plan demo serve session we can find out that something is wrong here. Okay, that's basically it for plan demo that should get you started in developing high quality Galaxy tools. And in the next part, I want to show you how to contribute your tool to one of the public repositories or to your own repository that you could set up.