Skip to content

Commit aa315b7

Browse files
jonzamorajonzamora
authored
Updated GenePattern Module Tutorial
1 parent e856e06 commit aa315b7

File tree

1 file changed

+116
-0
lines changed

1 file changed

+116
-0
lines changed

‎GenePattern Module Tutorial.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Creating your First GenePattern Module 💻 🧬
2+
---
3+
Hello, and welcome to GenePattern! If you have found yourself reading this document, then you must be interested in learning about how to develop GenePattern Modules.
4+
5+
Lucky for you, this is the right place to be!
6+
We have written some steps for you so that your first module development process goes as smooth as possible.
7+
8+
Note that for certain steps, we will include a ⚠️ sign to indicate important facts. We will try to be as descriptive and succinct about these facts as possible to ensure that you are developing your module without any issues.
9+
10+
Without further ado, here are those steps:
11+
12+
## Steps 📖
13+
---
14+
#### Step 0.1 - If you have not already, create an account through `beta.genepattern.org` 📝
15+
- When you arrive on the website, select the `Click to Register` option above the sign-in box.
16+
- Once you have been re-directed to the registration page, enter in your:
17+
1. Username
18+
2. Password
19+
3. Email
20+
- From here, use your login credentials to sign into `beta.genepattern.org`.
21+
22+
#### Step 0.2 - Request Access to GenePattern Modules 🔐
23+
- When you log into `beta.genepattern.org` for the first time, you will want to look at the top-left portion of your screen and locate the `Modules & Pipelines` drop-down menu.
24+
> ## ⚠️ Important
25+
> You will likely only have access to 4 Options on this drop-down menu: `New Pipeline`, `Install from Repository`, `Install from ZIP`, and `Manage`.
26+
>
27+
> To gain access to the `New Module` development option, please request access by contacting a member of the GenePattern Development Team.
28+
>
29+
> From here, you will be given Module Developer privileges.
30+
31+
- If you have made it this far, you are well on your way to developing your first GenePattern Module.
32+
33+
#### Step 1 - Under `Modules & Pipelines`, select `New Module` ✅
34+
- Selecting this option will take you to a new page where you will find a comprehensive module development interface.
35+
36+
> ## ⚠️ Important
37+
> We are going to be working with the `ABasicModule` repository from Github. If you have not already cloned this repository to your local machine or downloaded the files as a ZIP, do so right away at the following [link]([https://github.com/genepattern/ABasicModule](https://github.com/genepattern/ABasicModule))
38+
>
39+
> We will be specifically working with the `.py` files under the `src` folder.
40+
41+
#### Step 2 - Specify Module Details 🔍
42+
- When developing a GenePattern Module, there are 4 essential components:
43+
1. Details
44+
2. Support Files
45+
3. Command Line
46+
4. Parameters
47+
- We will start by filling out the Module Details (Name, Description, Author, Organization, etc.)
48+
> ## ⚠️ Important
49+
> The module we are working with will simply be adding text to an existing `.txt` file that a user provides as an input to the GenePattern Module. We will want our module to be kept `private`, and we will want our Docker Image to be `genepattern/docker-python36`.
50+
>
51+
> Our docker container can be found at the following [link](https://hub.docker.com/r/genepattern/docker-python36) for those interested.
52+
>
53+
> Since this is our First Module, our Version Increment will be `New major version (v1)` to indicate that our module is going to start at Version 1.
54+
>
55+
> This module's category should be `Demo`, since our module's purpose is for demonstration / learning.
56+
>
57+
> The final important detail to fill out here is the output file format. Here, since our module will be adding text to an existing `.txt` file, we will choose `.txt` as our output file format as well.
58+
>
59+
> The other details are not relatively important for the following basic module, so if the details were described above, make sure your module's details match the descriptions from above. In the future, your module(s) will involve details that are more applicable to the analyses done through GenePattern.
60+
61+
#### Step 3 - Include Support Files 📑
62+
- In the `src` folder of the `ABasicModule` directory, there should be 3 `.py` files and 1 `.txt` file.
63+
- Add those files to the current module you are working on.
64+
- We are adding these files to the module so that your module can carry out the processes included in your `.py` files.
65+
66+
#### Step 4 - Command Line Specifications ⌨️
67+
> ## ⚠️ Important
68+
> Since we are going to be running `.py` files, keep the command line type as `Custom`.
69+
>
70+
> To ensure that the command line understands we are running `.py` files, type `python` in the included text box as you would in the terminal.
71+
>
72+
> Following the `python` prefix, press the [Space] bar once and type `<libdir>ABasicModule.py` as shown here.
73+
>
74+
> What `<libdir>` does is it serves as a variable that the GenePattern server substitutes for the path to the working directory for where the uploaded files are stored. In basic terms, it finds your working directory of files for you!
75+
>
76+
> We then type `ABasicModule.py` to ensure that our module is processing this file each time it is called.
77+
78+
#### Step 5 - Add Parameters 🗳
79+
- We are almost done! Now, we need to specify the required parameters for our module.
80+
- If you haven't already, take a look at the `ABasicModule.py` file found under the `src` folder.
81+
> ## ⚠️ Important
82+
> There are 4 required parameters in this `.py` file, and they are all prefaced by `parser.add_argument()`.
83+
>
84+
> The 4 parameters we will want our module to include are:
85+
> 1. filename
86+
> 2. addtext
87+
> 3. message
88+
> 4. output_filename
89+
>
90+
> For each of the 4 parameters, it is important to read through the `ABasicModule.py` file and pay special attention to each parameter's **flags**, **input type**, and **default values** (if any).
91+
- The `filename` parameter's input field, unlike the other 3 parameters, should be a `File Field`. This option can be found under the drop down menu labeled `Type of field to display*:`.
92+
- The `File Format` should be `.txt` since we will be altering the `.txt` file that is passed in as a parameter.
93+
- The `addtext` parameter should have a default value of `False`. While writing this parameter, you should select the option `add a drop-down list` and add `True` to the list of values.
94+
- `filename` and `addtext` should have 1 minimum number of values and 1 maximum number of values. This is to ensure that a `.txt` file is being processed and that a boolean value will determine whether text will be appended to the file.
95+
- Conversely, `message` and `output_filename` will have 0 minimum number of values and 1 maximum number of values. This is because it is possible that the user wants to add nothing to the `.txt` file and the `output_filename` will have an arbitrary, default name of your choosing.
96+
97+
#### Final Step - Save and Run the Module 💾👟
98+
- Now that we have developed our module, it is time to scroll to the top of the screen and choose the `Save & Run` option.
99+
- We will now want to run our module and see if it works as expected.
100+
- First, we want to go to the Home screen of `beta.genepattern.org`
101+
- Next, under `Search Modules & Pipelines`, type the name of your module
102+
- Once it shows up, select it
103+
- You will now test it by doing the following:
104+
1. Upload `created_file_ground_truth.txt` from the `src` folder of `ABasicModule`
105+
2. Set `addtext` to **True**
106+
3. Type any message you'd like
107+
4. Type any output filename you'd like
108+
5. On the bottom-right side of the screen, click the `Run` button
109+
- From here, your program will (hopefully) run properly and produce a `.txt` file that includes your custom message.
110+
- To open the `.txt` file, simply click on the hyperlink named `(your_file_name).txt` after your module has finished running. This will open your `.txt` in a new tab on your browser.
111+
112+
## Congratulations! 🎉 You have just created your first GenePattern Module
113+
---
114+
Now that you know the basics of how to develop a GenePattern Module, you are ready to go ahead and create your own modules for GenePattern.
115+
116+
Best of luck with your future work!

0 commit comments

Comments
 (0)